📈 Stock Discovery & Market Analysis Platform

A modular, Streamlit-based stock market analysis application built on top of the Zerodha Kite Connect API. Below is a clean, polished, open-source–ready README refactored from your earlier version. This version is suitable for GitHub public repositories, recruiters, contributors, and maintainers. Tone is neutral, professional, and community-friendly, while still explaining internals clearly.

You can use this as-is for README.md.

📈 Stock Discovery & Market Analysis Platform

A modular, Streamlit-based stock market analysis application built on top of the Zerodha Kite Connect API. The project emphasizes clean architecture, separation of concerns, and performance, making it easy to extend for backtesting, algo trading, or multi-broker integrations.

🚀 Features

🔍 Stock search by symbol or company name
📊 Live price & historical OHLC data
📈 High-performance candlestick charts (Lightweight Charts)
⭐ Favorites / watchlist management
👤 User profile, funds & margins view
⚡ Instrument caching for fast search
🔐 Secure environment-based configuration

🧱 Architecture Overview

The application follows a layered architecture:

UI Layer (Streamlit)
        ↓
Service Layer (Business Logic)
        ↓
Broker Client Layer (Zerodha Kite)
        ↓
External Broker APIs

Core Principles

UI never communicates directly with broker APIs
All broker logic is isolated in services
Configuration and secrets are environment-driven
Services are reusable and testable

📁 Project Structure

│
├── main.py
│
├── config/
│   ├── settings.py
│   └── env.py
│
├── services/
│   ├── kite_client.py
│   ├── profile_service.py
│   ├── search_service.py
│   ├── data_service.py
│   └── fav_service.py
│
├── ui/
│   ├── profile.py
│   ├── search.py
│   ├── saved.py
│   └── lightweight_charts.py
│
├── utils/
│   ├── instruments.py
│   ├── charts.py
│   └── downloader.py
│
├── data/
│   ├── favorites.json
│   └── cache/
│
├── requirements.txt
└── .env

🧩 Detailed Component Explanation

`main.py` — Application Entry Point

Initializes Streamlit
Configures page layout and navigation
Creates shared service instances
Acts as the orchestration layer for the app

`config/` — Configuration Layer

`settings.py`

Centralized application constants
Time intervals, feature flags, defaults
Keeps configuration out of business logic

`env.py`

Loads environment variables from .env
Prevents secrets from being hardcoded
Enables easy environment switching

`services/` — Business Logic Layer

`kite_client.py`

Initializes and manages the KiteConnect client
Implemented as a singleton
Handles authentication and session reuse

`profile_service.py`

Fetches user profile information
Retrieves funds and margin details
Normalizes broker responses for UI

`search_service.py`

Performs stock search using cached instruments
Maps company names → trading symbols

`data_service.py`

Fetches historical OHLC data
Retrieves live market quotes
Prepares data for chart rendering

`fav_service.py`

Manages favorites/watchlist persistence
Abstracts storage away from UI

`ui/` — Presentation Layer

`search.py`

Core trading interface
Search bar and symbol selection
Triggers data fetch and chart updates

`profile.py`

Displays user profile and account data
Uses profile_service exclusively

`saved.py`

Displays saved/watchlisted stocks
Loads data via fav_service

`lightweight_charts.py`

High-performance chart renderer
Candlestick, volume, and indicator support
Optimized for real-time updates

`utils/` — Utility Layer

`instruments.py`

Loads and caches instrument dump
Enables fast symbol-to-token mapping
Avoids repeated API calls

`charts.py`

Shared Plotly helper functions
Used for non-real-time visualizations

`downloader.py`

CSV export utilities
Enables data downloads

`data/` — Local Persistence

favorites.json stores user watchlists
cache/ holds cached instrument dumps
Designed for easy migration to DB/Redis later

🔄 Application Workflow

Startup

main.py
 → load env
   → load settings
     → initialize Kite client
       → load instrument cache

Stock Search

UI (search.py)
 → SearchService
   → InstrumentCache

Market Data

UI (search.py)
 → DataService
   → KiteClient
     → Zerodha API

Profile & Funds

UI (profile.py)
 → ProfileService
   → KiteClient

Favorites

UI (saved.py)
 → FavService
   → favorites.json

🛠 Installation & Setup

Prerequisites

Python 3.9+
Zerodha Kite Connect account

Install Dependencies

pip install -r requirements.txt

Environment Variables

Create a .env file:

KITE_API_KEY=your_api_key
KITE_ACCESS_TOKEN=your_access_token

Run the App

streamlit run main.py

🧪 Extensibility & Roadmap

Planned or easily extendable features:

WebSocket live tick streaming
Backtesting engine
Algo trading execution
Multi-broker support (AngelOne, Upstox)
Database-backed persistence
Strategy indicators & signals

🧩 System Design Diagram

🏗 High-Level System Architecture

┌─────────────────────────────┐
│        User Browser         │
│  (Search • Charts • Profile)│
└───────────────┬─────────────┘
                │
                ▼
┌─────────────────────────────┐
│     Streamlit UI Layer      │
│  ───────────────────────── │
│  • search.py                │
│  • profile.py               │
│  • saved.py                 │
│  • lightweight_charts.py    │
└───────────────┬─────────────┘
                │
                ▼
┌─────────────────────────────┐
│     Service Layer           │
│  ───────────────────────── │
│  • SearchService            │
│  • DataService              │
│  • ProfileService           │
│  • FavService               │
└───────────────┬─────────────┘
                │
                ▼
┌─────────────────────────────┐
│   Broker Client Layer       │
│  ───────────────────────── │
│  • KiteClient (Singleton)   │
│  • Auth / Session Handling  │
└───────────────┬─────────────┘
                │
                ▼
┌─────────────────────────────┐
│   Zerodha Kite Connect API  │
│  ───────────────────────── │
│  • Quotes                   │
│  • Historical OHLC          │
│  • Profile & Margins        │
└───────────────┬─────────────┘
                │
                ▼
┌─────────────────────────────┐
│   Local Storage & Cache     │
│  ───────────────────────── │
│  • Instrument Cache         │
│  • favorites.json           │
└─────────────────────────────┘

🔍 Component Responsibilities

1️⃣ User / Browser

Interacts with the application via Streamlit UI
Requests data through UI actions (search, select stock, view profile)

2️⃣ UI Layer (Streamlit)

Role

Presentation & interaction only
No broker logic
No raw API calls

Key Responsibilities

Render search interface
Display charts and tables
Trigger service calls
Maintain UI state across reruns

3️⃣ Service Layer (Business Logic)

Why this layer exists

Isolates business rules
Makes logic testable and reusable
Prevents UI → Broker coupling

Responsibilities

Search logic using cached instruments
Fetch & normalize market data
Fetch profile, funds, margins
Handle favorites persistence

4️⃣ Broker Client Layer (KiteClient)

Key Characteristics

Singleton pattern
Authenticated session reuse
Centralized API error handling

Why singleton

Streamlit reruns scripts frequently
Prevents repeated login / token issues
Avoids rate-limit problems

5️⃣ Zerodha Kite Connect API

Provides

Live market quotes
Historical OHLC candles
User profile & margin data

Access Rules

Accessed only through KiteClient
Never directly from UI

6️⃣ Cache & Local Storage

Instrument Cache

Loaded once at startup
Enables instant symbol search
Avoids heavy repeated API calls

favorites.json

Lightweight persistence
User watchlist storage
Easily replaceable with DB later

🔄 End-to-End Data Flow

🔍 Stock Search

User
 → UI (search.py)
   → SearchService
     → Instrument Cache

📊 Market Data

User
 → UI
   → DataService
     → KiteClient
       → Zerodha API

👤 Profile & Funds

User
 → UI (profile.py)
   → ProfileService
     → KiteClient

⭐ Favorites

User
 → UI (saved.py)
   → FavService
     → favorites.json

🎯 Why This Design Is Strong

Clean separation of concerns
Scalable to multi-broker support
Interview-grade architecture
Easy migration to:
- WebSockets
- Databases
- Algo-trading engines
Open-source contributor friendly

🚀 Future Architecture Extensions

WebSocket live ticks
Redis instrument cache
Backtesting engine
Strategy execution engine
Cloud deployment (Docker)

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.idea		.idea
Services		Services
UI		UI
Utils		Utils
config		config
data		data
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
main.py		main.py
portfolio.html		portfolio.html
requirements.txt		requirements.txt
test.py		test.py

Folders and files

Latest commit

History

Repository files navigation

📈 Stock Discovery & Market Analysis Platform

📈 Stock Discovery & Market Analysis Platform

🚀 Features

🧱 Architecture Overview

Core Principles

📁 Project Structure

🧩 Detailed Component Explanation

main.py — Application Entry Point

config/ — Configuration Layer

settings.py

env.py

services/ — Business Logic Layer

kite_client.py

profile_service.py

search_service.py

data_service.py

fav_service.py

ui/ — Presentation Layer

search.py

profile.py

saved.py

lightweight_charts.py

utils/ — Utility Layer

instruments.py

charts.py

downloader.py

data/ — Local Persistence

🔄 Application Workflow

Startup

Stock Search

Market Data

Profile & Funds

Favorites

🛠 Installation & Setup

Prerequisites

Install Dependencies

Environment Variables

Run the App

🧪 Extensibility & Roadmap

🧩 System Design Diagram

🏗 High-Level System Architecture

🔍 Component Responsibilities

1️⃣ User / Browser

2️⃣ UI Layer (Streamlit)

3️⃣ Service Layer (Business Logic)

4️⃣ Broker Client Layer (KiteClient)

5️⃣ Zerodha Kite Connect API

6️⃣ Cache & Local Storage

🔄 End-to-End Data Flow

🔍 Stock Search

📊 Market Data

👤 Profile & Funds

⭐ Favorites

🎯 Why This Design Is Strong

🚀 Future Architecture Extensions

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`main.py` — Application Entry Point

`config/` — Configuration Layer

`settings.py`

`env.py`

`services/` — Business Logic Layer

`kite_client.py`

`profile_service.py`

`search_service.py`

`data_service.py`

`fav_service.py`

`ui/` — Presentation Layer

`search.py`

`profile.py`

`saved.py`

`lightweight_charts.py`

`utils/` — Utility Layer

`instruments.py`

`charts.py`

`downloader.py`

`data/` — Local Persistence