# parvdaga/stockbro architecture

> Architecture diagram of the GitHub repository parvdaga/stockbro, 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/parvdaga/stockbro
- Repository: https://github.com/parvdaga/stockbro

## Overview

StockBro AI provides Indian-market stock quotes, historical charts, news, and AI-generated financial guidance through a FastAPI backend and Streamlit interface. The main workflow is a user query entering the interface and API, being parsed and handled by the master agent or a domain endpoint, then drawing on market/news integrations and returning results. Authentication and watchlists are additional product branches. Source excerpts establish much of the backend wiring; the README documents the frontend/backend split, but does not show the frontend’s request implementation.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/router.py) (API Router), [`backend/app/integrations/groww.py`](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/groww.py) (Groww Client), [`backend/app/agents/master_agent.py`](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/master_agent.py) (Master Agent), [`backend/app/integrations/newsdata.py`](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/newsdata.py) (NewsData Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User Interface"]
  node_streamlit["Streamlit App<br/>[main.py]"]
end

subgraph group_api["API and Accounts"]
  node_backend["FastAPI App<br/>[main.py]"]
  node_api_router["API Router<br/>[router.py]"]
  node_chat_api["Chat API<br/>[chat.py]"]
  node_stocks_api["Stocks API<br/>[stocks.py]"]
  node_charts_api["Charts API<br/>[charts.py]"]
  node_news_api["News API<br/>[news.py]"]
  node_auth_api["Auth API<br/>[auth.py]"]
  node_watchlist_api["Watchlist API<br/>[watchlist.py]"]
end

subgraph group_agents["AI Analysis"]
  node_master_agent["Master Agent<br/>[master_agent.py]"]
  node_query_router["Intent Router<br/>[query_router.py]"]
  node_finance_agent["Finance Agent<br/>[finance_agent.py]"]
  node_news_agent["News Agent<br/>[news_agent.py]"]
  node_knowledge["Market Knowledge<br/>[knowledge_base.py]"]
  node_shared_model["Shared LLM Model<br/>[shared_model.py]"]
end

subgraph group_data["Market Data"]
  node_stock_service["Stock Service<br/>[stock_service.py]"]
  node_groww["Groww Client<br/>[groww.py]"]
  node_newsdata["NewsData Client<br/>[newsdata.py]"]
end

subgraph group_platform["Shared Infrastructure"]
  node_dependencies["Auth Dependencies<br/>[dependencies.py]"]
  node_supabase_client["Supabase Client<br/>[supabase_client.py]"]
  node_cache["TTL Cache<br/>[cache.py]"]
  node_rate_limiter["Rate Limiter<br/>[rate_limiter.py]"]
  node_retry["Retry Logic<br/>[retry.py]"]
end

node_user(("Investor"))
node_supabase[("Supabase")]
node_llm{{"Groq / Gemini"}}
node_groww_service{{"Groww Market Data"}}
node_news_service{{"NewsData.io"}}

node_user -->|"asks / views"| node_streamlit
node_streamlit -.->|"uses backend"| node_backend
node_backend -->|"mounts routes"| node_api_router
node_api_router -->|"includes"| node_chat_api
node_api_router -->|"includes"| node_stocks_api
node_api_router -->|"includes"| node_charts_api
node_api_router -->|"includes"| node_news_api
node_api_router -->|"includes"| node_auth_api
node_api_router -->|"includes"| node_watchlist_api
node_chat_api -->|"invokes"| node_master_agent
node_chat_api -->|"routes intent"| node_query_router
node_master_agent -->|"parses queries"| node_query_router
node_master_agent -->|"uses tools"| node_finance_agent
node_master_agent -->|"uses tools"| node_news_agent
node_master_agent -->|"reads knowledge"| node_knowledge
node_master_agent -->|"gets model"| node_shared_model
node_finance_agent -->|"gets model"| node_shared_model
node_news_agent -->|"gets model"| node_shared_model
node_shared_model -->|"configures provider"| node_llm
node_finance_agent -->|"fetches prices"| node_groww
node_news_agent -->|"fetches news"| node_newsdata
node_stocks_api -->|"calls service"| node_stock_service
node_stock_service -->|"requests stock data"| node_groww
node_charts_api -->|"requests history"| node_groww
node_news_api -->|"requests news"| node_newsdata
node_groww -->|"fetches market data"| node_groww_service
node_newsdata -->|"fetches articles"| node_news_service
node_groww -->|"caches responses"| node_cache
node_groww -->|"uses limits"| node_rate_limiter
node_groww -->|"retries failures"| node_retry
node_newsdata -->|"caches responses"| node_cache
node_newsdata -->|"uses limits"| node_rate_limiter
node_newsdata -->|"retries failures"| node_retry
node_auth_api -->|"uses auth"| node_dependencies
node_watchlist_api -->|"requires user"| node_dependencies
node_dependencies -->|"gets client"| node_supabase_client
node_supabase_client -.->|"connects to"| node_supabase

click node_streamlit "https://github.com/parvdaga/stockbro/blob/main/streamlit_app/main.py"
click node_backend "https://github.com/parvdaga/stockbro/blob/main/backend/app/main.py"
click node_api_router "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/router.py"
click node_chat_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/chat.py"
click node_stocks_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/stocks.py"
click node_charts_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/charts.py"
click node_news_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/news.py"
click node_auth_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/auth.py"
click node_watchlist_api "https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/watchlist.py"
click node_dependencies "https://github.com/parvdaga/stockbro/blob/main/backend/app/core/dependencies.py"
click node_supabase_client "https://github.com/parvdaga/stockbro/blob/main/backend/app/core/supabase_client.py"
click node_master_agent "https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/master_agent.py"
click node_query_router "https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/query_router.py"
click node_finance_agent "https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/finance_agent.py"
click node_news_agent "https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/news_agent.py"
click node_knowledge "https://github.com/parvdaga/stockbro/blob/main/backend/app/core/knowledge_base.py"
click node_shared_model "https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/shared_model.py"
click node_stock_service "https://github.com/parvdaga/stockbro/blob/main/backend/app/services/stock_service.py"
click node_groww "https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/groww.py"
click node_newsdata "https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/newsdata.py"
click node_cache "https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/cache.py"
click node_rate_limiter "https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/rate_limiter.py"
click node_retry "https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/retry.py"

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_streamlit toneBlue
class node_backend,node_api_router,node_chat_api,node_stocks_api,node_charts_api,node_news_api,node_auth_api,node_watchlist_api,node_supabase toneAmber
class node_master_agent,node_query_router,node_finance_agent,node_news_agent,node_knowledge,node_shared_model toneMint
class node_stock_service,node_groww,node_newsdata toneRose
class node_dependencies,node_supabase_client,node_cache,node_rate_limiter,node_retry,node_user,node_llm,node_groww_service,node_news_service toneIndigo
```

## Components

### User Interface

- [Streamlit App](https://github.com/parvdaga/stockbro/blob/main/streamlit_app/main.py): `streamlit_app/main.py`

### API and Accounts

- [FastAPI App](https://github.com/parvdaga/stockbro/blob/main/backend/app/main.py): `backend/app/main.py`
- [API Router](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Chat API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [Stocks API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/stocks.py): `backend/app/api/v1/stocks.py`
- [Charts API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/charts.py): `backend/app/api/v1/charts.py`
- [News API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/news.py): `backend/app/api/v1/news.py`
- [Auth API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Watchlist API](https://github.com/parvdaga/stockbro/blob/main/backend/app/api/v1/watchlist.py): `backend/app/api/v1/watchlist.py`

### AI Analysis

- [Master Agent](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/master_agent.py): `backend/app/agents/master_agent.py`
- [Intent Router](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/query_router.py): `backend/app/agents/query_router.py`
- [Finance Agent](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/finance_agent.py): `backend/app/agents/finance_agent.py`
- [News Agent](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/news_agent.py): `backend/app/agents/news_agent.py`
- [Market Knowledge](https://github.com/parvdaga/stockbro/blob/main/backend/app/core/knowledge_base.py): `backend/app/core/knowledge_base.py`
- [Shared LLM Model](https://github.com/parvdaga/stockbro/blob/main/backend/app/agents/shared_model.py): `backend/app/agents/shared_model.py`

### Market Data

- [Stock Service](https://github.com/parvdaga/stockbro/blob/main/backend/app/services/stock_service.py): `backend/app/services/stock_service.py`
- [Groww Client](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/groww.py): `backend/app/integrations/groww.py`
- [NewsData Client](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/newsdata.py): `backend/app/integrations/newsdata.py`

### Shared Infrastructure

- [Auth Dependencies](https://github.com/parvdaga/stockbro/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`
- [Supabase Client](https://github.com/parvdaga/stockbro/blob/main/backend/app/core/supabase_client.py): `backend/app/core/supabase_client.py`
- [TTL Cache](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/cache.py): `backend/app/integrations/cache.py`
- [Rate Limiter](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/rate_limiter.py): `backend/app/integrations/rate_limiter.py`
- [Retry Logic](https://github.com/parvdaga/stockbro/blob/main/backend/app/integrations/retry.py): `backend/app/integrations/retry.py`

### Other components

- **Investor**
- **Supabase**
- **Groq / Gemini**
- **Groww Market Data**
- **NewsData.io**

## Connections

- Investor → Streamlit App: asks / views (evidence: `README.md`)
- Streamlit App → FastAPI App: uses backend (evidence: `README.md`)
- FastAPI App → API Router: mounts routes (evidence: `backend/app/main.py`)
- API Router → Chat API: includes (evidence: `backend/app/api/v1/router.py`)
- API Router → Stocks API: includes (evidence: `backend/app/api/v1/router.py`)
- API Router → Charts API: includes (evidence: `backend/app/api/v1/router.py`)
- API Router → News API: includes (evidence: `backend/app/api/v1/router.py`)
- API Router → Auth API: includes (evidence: `backend/app/api/v1/router.py`)
- API Router → Watchlist API: includes (evidence: `backend/app/api/v1/router.py`)
- Chat API → Master Agent: invokes (evidence: `backend/app/api/v1/chat.py`)
- Chat API → Intent Router: routes intent (evidence: `backend/app/api/v1/chat.py`)
- Master Agent → Intent Router: parses queries (evidence: `backend/app/agents/master_agent.py`)
- Master Agent → Finance Agent: uses tools (evidence: `backend/app/agents/master_agent.py`)
- Master Agent → News Agent: uses tools (evidence: `backend/app/agents/master_agent.py`)
- Master Agent → Market Knowledge: reads knowledge (evidence: `backend/app/agents/master_agent.py`)
- Master Agent → Shared LLM Model: gets model (evidence: `backend/app/agents/master_agent.py`)
- Finance Agent → Shared LLM Model: gets model (evidence: `backend/app/agents/finance_agent.py`)
- News Agent → Shared LLM Model: gets model (evidence: `backend/app/agents/news_agent.py`)
- Shared LLM Model → Groq / Gemini: configures provider (evidence: `backend/app/agents/shared_model.py`)
- Finance Agent → Groww Client: fetches prices (evidence: `backend/app/agents/finance_agent.py`)
- News Agent → NewsData Client: fetches news (evidence: `backend/app/agents/news_agent.py`)
- Stocks API → Stock Service: calls service (evidence: `backend/app/api/v1/stocks.py`)
- Stock Service → Groww Client: requests stock data (evidence: `backend/app/services/stock_service.py`)
- Charts API → Groww Client: requests history (evidence: `backend/app/api/v1/charts.py`)
- News API → NewsData Client: requests news (evidence: `backend/app/api/v1/news.py`)
- Groww Client → Groww Market Data: fetches market data (evidence: `backend/app/integrations/groww.py`)
- NewsData Client → NewsData.io: fetches articles (evidence: `backend/app/integrations/newsdata.py`)
- Groww Client → TTL Cache: caches responses (evidence: `backend/app/integrations/groww.py`)
- Groww Client → Rate Limiter: uses limits (evidence: `backend/app/integrations/groww.py`)
- Groww Client → Retry Logic: retries failures (evidence: `backend/app/integrations/groww.py`)
- NewsData Client → TTL Cache: caches responses (evidence: `backend/app/integrations/newsdata.py`)
- NewsData Client → Rate Limiter: uses limits (evidence: `backend/app/integrations/newsdata.py`)
- NewsData Client → Retry Logic: retries failures (evidence: `backend/app/integrations/newsdata.py`)
- Auth API → Auth Dependencies: uses auth (evidence: `backend/app/api/v1/auth.py`)
- Watchlist API → Auth Dependencies: requires user (evidence: `backend/app/api/v1/watchlist.py`)
- Auth Dependencies → Supabase Client: gets client (evidence: `backend/app/core/dependencies.py`)
- Supabase Client → Supabase: connects to
