# sircharan/stocky-ai architecture

> Architecture diagram of the GitHub repository sircharan/stocky-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sircharan/stocky-ai
- Repository: https://github.com/sircharan/stocky-ai

## Overview

Stocky AI is a personal Indian-markets trading assistant delivered through a Telegram bot and a web chat, with a separate marketing site. Users submit natural-language requests or choose a web feature; the bot or web API dispatches requests to trading, market-data, analysis, and research capabilities, then returns results in the originating interface. The web product also persists conversations, watchlists, and feedback. The README documents additional feature breadth beyond the sampled code; those branches are represented at subsystem level, while edges are limited to documented or excerpted relationships.

Main entry points: [`stocky-web/backend/app/main.py`](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/main.py) (REST API routes), [`stocky-web/backend/app/handlers/chat.py`](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/chat.py) (Chat API), [`stocky-ai/bot/main.py`](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/main.py) (Bot runtime), [`stocky-ai/bot/handlers/nlp.py`](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/nlp.py) (Bot commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web chat and API"]
  node_web_ui["Chat interface<br/>[ChatShell.tsx]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_api_routes["REST API routes<br/>[main.py]"]
  node_web_store[("Application database<br/>[database.py]")]
  node_context["Conversation context<br/>[context_manager.py]"]
  node_web_user_features["User features<br/>[watchlist.py]"]
end

subgraph group_research["Research and intelligence"]
  node_analysis["Stock analysis<br/>[analyse.py]"]
  node_council["Research council<br/>[council.py]"]
  node_market_intel["Market intelligence<br/>[scan.py]"]
  node_ai_models["AI model clients<br/>[ai_client.py]"]
  node_data_enricher["Unified data layer<br/>[data_enricher.py]"]
end

subgraph group_trading["Trading services"]
  node_trade_api["Trade operations<br/>[trading.py]"]
  node_options["Options analytics<br/>[options.py]"]
end

subgraph group_telegram["Telegram assistant"]
  node_bot_runtime["Bot runtime<br/>[main.py]"]
  node_bot_handlers["Bot commands<br/>[nlp.py]"]
  node_bot_analysis["Bot stock analysis<br/>[analyse.py]"]
  node_bot_trading["Bot trade commands<br/>[trading.py]"]
  node_bot_kite["Bot Kite client<br/>[kite_client.py]"]
  node_bot_store[("Bot database<br/>[database.py]")]
end

subgraph group_site["Marketing site"]
  node_landing["Marketing pages<br/>[page.tsx]"]
  node_waitlist["Waitlist endpoint<br/>[route.ts]"]
end

node_web_user(("Web user"))
node_kite["Zerodha Kite"]
node_dhan["Dhan market data"]
node_telegram_user(("Telegram user"))
node_landing_visitor(("Site visitor"))

node_web_user -->|"uses"| node_web_ui
node_web_ui -.->|"sends requests"| node_api_routes
node_api_routes -->|"routes chat"| node_chat_api
node_api_routes -->|"routes features"| node_market_intel
node_api_routes -->|"routes trades"| node_trade_api
node_api_routes -->|"routes options"| node_options
node_chat_api -.->|"persists conversations"| node_web_store
node_chat_api -.->|"uses context"| node_context
node_chat_api -.->|"requests responses"| node_ai_models
node_council -->|"calls agents"| node_ai_models
node_analysis -.->|"enriches data"| node_data_enricher
node_market_intel -.->|"uses market data"| node_data_enricher
node_trade_api -.->|"places orders"| node_kite
node_options -.->|"gets options data"| node_dhan
node_web_user_features -.->|"persists preferences"| node_web_store
node_telegram_user -->|"sends commands"| node_bot_runtime
node_bot_runtime -->|"dispatches commands"| node_bot_handlers
node_bot_handlers -->|"dispatches analysis"| node_bot_analysis
node_bot_handlers -->|"dispatches trades"| node_bot_trading
node_bot_analysis -->|"logs activity"| node_bot_store
node_bot_trading -.->|"executes trades"| node_bot_kite
node_bot_kite -->|"calls broker"| node_kite
node_bot_runtime -->|"initializes store"| node_bot_store
node_landing_visitor -->|"views"| node_landing
node_landing -.->|"submits signup"| node_waitlist

click node_web_ui "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/frontend/src/app/chat/ChatShell.tsx"
click node_chat_api "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/chat.py"
click node_api_routes "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/main.py"
click node_web_store "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/database.py"
click node_context "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/context_manager.py"
click node_web_user_features "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/watchlist.py"
click node_analysis "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/analyse.py"
click node_council "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/council.py"
click node_market_intel "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/scan.py"
click node_ai_models "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/ai_client.py"
click node_data_enricher "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/services/data_enricher.py"
click node_trade_api "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/trading.py"
click node_options "https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/options.py"
click node_bot_runtime "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/main.py"
click node_bot_handlers "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/nlp.py"
click node_bot_analysis "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/analyse.py"
click node_bot_trading "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/trading.py"
click node_bot_kite "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/kite_client.py"
click node_bot_store "https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/database.py"
click node_landing "https://github.com/sircharan/stocky-ai/blob/main/stocky-landing/src/app/page.tsx"
click node_waitlist "https://github.com/sircharan/stocky-ai/blob/main/stocky-landing/src/app/api/waitlist/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_ui,node_chat_api,node_api_routes,node_web_store,node_context,node_web_user_features,node_web_user,node_telegram_user toneBlue
class node_analysis,node_council,node_market_intel,node_ai_models,node_data_enricher toneAmber
class node_trade_api,node_options toneMint
class node_bot_runtime,node_bot_handlers,node_bot_analysis,node_bot_trading,node_bot_kite,node_bot_store toneRose
class node_landing,node_waitlist,node_kite,node_dhan,node_landing_visitor toneIndigo
```

## Components

### Web chat and API

- [Chat interface](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/frontend/src/app/chat/ChatShell.tsx): `stocky-web/frontend/src/app/chat/ChatShell.tsx`
- [Chat API](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/chat.py): `stocky-web/backend/app/handlers/chat.py`
- [REST API routes](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/main.py): `stocky-web/backend/app/main.py`
- [Application database](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/database.py): `stocky-web/backend/app/database.py`
- [Conversation context](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/context_manager.py): `stocky-web/backend/app/context_manager.py`
- [User features](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/watchlist.py): `stocky-web/backend/app/handlers/watchlist.py`

### Research and intelligence

- [Stock analysis](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/analyse.py): `stocky-web/backend/app/handlers/analyse.py`
- [Research council](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/council.py): `stocky-web/backend/app/handlers/council.py`
- [Market intelligence](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/scan.py): `stocky-web/backend/app/handlers/scan.py`
- [AI model clients](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/ai_client.py): `stocky-web/backend/app/ai_client.py`
- [Unified data layer](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/services/data_enricher.py): `stocky-web/backend/app/services/data_enricher.py`

### Trading services

- [Trade operations](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/trading.py): `stocky-web/backend/app/handlers/trading.py`
- [Options analytics](https://github.com/sircharan/stocky-ai/blob/main/stocky-web/backend/app/handlers/options.py): `stocky-web/backend/app/handlers/options.py`

### Telegram assistant

- [Bot runtime](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/main.py): `stocky-ai/bot/main.py`
- [Bot commands](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/nlp.py): `stocky-ai/bot/handlers/nlp.py`
- [Bot stock analysis](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/analyse.py): `stocky-ai/bot/handlers/analyse.py`
- [Bot trade commands](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/handlers/trading.py): `stocky-ai/bot/handlers/trading.py`
- [Bot Kite client](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/kite_client.py): `stocky-ai/bot/kite_client.py`
- [Bot database](https://github.com/sircharan/stocky-ai/blob/main/stocky-ai/bot/database.py): `stocky-ai/bot/database.py`

### Marketing site

- [Marketing pages](https://github.com/sircharan/stocky-ai/blob/main/stocky-landing/src/app/page.tsx): `stocky-landing/src/app/page.tsx`
- [Waitlist endpoint](https://github.com/sircharan/stocky-ai/blob/main/stocky-landing/src/app/api/waitlist/route.ts): `stocky-landing/src/app/api/waitlist/route.ts`

### Other components

- **Web user**
- **Zerodha Kite**
- **Dhan market data**
- **Telegram user**
- **Site visitor**

## Connections

- Web user → Chat interface: uses (evidence: `README.md`)
- Chat interface → REST API routes: sends requests (evidence: `README.md`)
- REST API routes → Chat API: routes chat (evidence: `stocky-web/backend/app/main.py`)
- REST API routes → Market intelligence: routes features (evidence: `stocky-web/backend/app/main.py`)
- REST API routes → Trade operations: routes trades (evidence: `stocky-web/backend/app/main.py`)
- REST API routes → Options analytics: routes options (evidence: `stocky-web/backend/app/main.py`)
- Chat API → Application database: persists conversations (evidence: `README.md`)
- Chat API → Conversation context: uses context
- Chat API → AI model clients: requests responses
- Research council → AI model clients: calls agents
- Stock analysis → Unified data layer: enriches data
- Market intelligence → Unified data layer: uses market data
- Trade operations → Zerodha Kite: places orders (evidence: `README.md`)
- Options analytics → Dhan market data: gets options data (evidence: `README.md`)
- User features → Application database: persists preferences (evidence: `README.md`)
- Telegram user → Bot runtime: sends commands (evidence: `README.md`)
- Bot runtime → Bot commands: dispatches commands (evidence: `stocky-ai/bot/main.py`)
- Bot commands → Bot stock analysis: dispatches analysis (evidence: `stocky-ai/bot/handlers/nlp.py`)
- Bot commands → Bot trade commands: dispatches trades (evidence: `stocky-ai/bot/handlers/nlp.py`)
- Bot stock analysis → Bot database: logs activity (evidence: `stocky-ai/bot/handlers/analyse.py`)
- Bot trade commands → Bot Kite client: executes trades (evidence: `README.md`)
- Bot Kite client → Zerodha Kite: calls broker (evidence: `stocky-ai/bot/kite_client.py`)
- Bot runtime → Bot database: initializes store (evidence: `stocky-ai/bot/main.py`)
- Site visitor → Marketing pages: views (evidence: `README.md`)
- Marketing pages → Waitlist endpoint: submits signup