# svsairevanth/indian-stock-ai-agent architecture

> Architecture diagram of the GitHub repository svsairevanth/indian-stock-ai-agent, 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/svsairevanth/indian-stock-ai-agent
- Repository: https://github.com/svsairevanth/indian-stock-ai-agent

## Overview

This is an Indian-market stock-analysis application: a user submits a stock or portfolio question, the web service runs a coordinated analysis, and returns a recommendation with a generated PDF report. The documented analysis spans fundamentals, technicals, sentiment/news, macro conditions, company documents, bull/bear debate, and risk; portfolio review is available when holdings are supplied. The graph emphasizes the web workflow and major analysis capabilities. Some subsystem links rely on README descriptions or source-index references because their implementation excerpts were not provided.

Main entry points: [`agents/pipeline_orchestrator.py`](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/pipeline_orchestrator.py) (Analysis pipeline), [`web_server.py`](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/web_server.py) (Web service), [`agents/technical_analyst.py`](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/technical_analyst.py) (Technical analysis), [`agents/sentiment_analyst.py`](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/sentiment_analyst.py) (Sentiment analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_chat["Web chat<br/>[chat.html]"]
  node_server["Web service<br/>[web_server.py]"]
end

subgraph group_analysis["Analysis workflow"]
  node_pipeline["Analysis pipeline"]
  node_fundamental["Fundamental analysis"]
  node_technical["Technical analysis"]
  node_sentiment["Sentiment analysis"]
  node_news["News intelligence"]
  node_macro["Macro analysis<br/>[macro_analyst.py]"]
  node_documents["Document analysis"]
  node_debate["Bull-bear debate<br/>[debate_judge.py]"]
  node_risk["Risk management<br/>[risk_manager.py]"]
  node_portfolio["Portfolio analysis"]
end

subgraph group_data["Analysis tools"]
  node_stockdata["Stock data<br/>[stock_data.py]"]
  node_technicaltools["Technical indicators"]
  node_sentimenttools["Sentiment scoring"]
  node_newsfetch["News fetching<br/>[news_fetcher.py]"]
  node_exa["Live research<br/>[exa_research.py]"]
  node_macrodata["Macro data<br/>[macro_data.py]"]
  node_doctools["Company documents"]
  node_risktools["Risk calculations<br/>[risk_management.py]"]
  node_portfoliotools["Portfolio metrics"]
end

subgraph group_delivery["Persistence and reports"]
  node_pdf["PDF report<br/>[pdf_generator.py]"]
  node_sqlite[("Application database<br/>[app_data.db]")]
end

node_user(("Investor"))
node_exa_service["Exa MCP"]

node_user -->|"submits question"| node_chat
node_chat -->|"sends chat"| node_server
node_server -->|"runs analysis"| node_pipeline
node_pipeline -->|"invokes analysis"| node_fundamental
node_pipeline -->|"invokes analysis"| node_technical
node_pipeline -->|"invokes analysis"| node_sentiment
node_pipeline -->|"invokes analysis"| node_news
node_pipeline -->|"invokes analysis"| node_macro
node_pipeline -->|"invokes analysis"| node_documents
node_pipeline -->|"invokes debate"| node_debate
node_pipeline -->|"invokes assessment"| node_risk
node_pipeline -.->|"invokes when relevant"| node_portfolio
node_fundamental -->|"fetches metrics"| node_stockdata
node_technical -->|"calculates indicators"| node_technicaltools
node_technical -->|"fetches prices"| node_stockdata
node_sentiment -->|"fetches news"| node_newsfetch
node_sentiment -->|"scores sentiment"| node_sentimenttools
node_news -->|"requests research"| node_exa
node_news -->|"uses scoring"| node_sentimenttools
node_exa -->|"calls MCP"| node_exa_service
node_macro -->|"fetches indicators"| node_macrodata
node_documents -->|"analyzes filings"| node_doctools
node_risk -->|"calculates trade risk"| node_risktools
node_portfolio -->|"analyzes holdings"| node_portfoliotools
node_pipeline -->|"generates report"| node_pdf
node_server -->|"persists history"| node_sqlite
node_server -->|"serves report"| node_pdf

click node_chat "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/chat.html"
click node_server "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/web_server.py"
click node_pipeline "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/pipeline_orchestrator.py"
click node_fundamental "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/fundamental_analyst.py"
click node_technical "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/technical_analyst.py"
click node_sentiment "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/sentiment_analyst.py"
click node_news "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/news_intelligence_agent.py"
click node_macro "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/macro_analyst.py"
click node_documents "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/document_analyst.py"
click node_debate "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/debate_judge.py"
click node_risk "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/risk_manager.py"
click node_portfolio "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/portfolio_analyst.py"
click node_stockdata "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/stock_data.py"
click node_technicaltools "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/technical_analysis.py"
click node_sentimenttools "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/sentiment_analyzer.py"
click node_newsfetch "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/news_fetcher.py"
click node_exa "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/exa_research.py"
click node_macrodata "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/macro_data.py"
click node_doctools "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/document_analyzer.py"
click node_risktools "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/risk_management.py"
click node_portfoliotools "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/portfolio_analyzer.py"
click node_pdf "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/pdf_generator.py"
click node_sqlite "https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/app_data.db"

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_chat,node_server toneBlue
class node_pipeline,node_fundamental,node_technical,node_sentiment,node_news,node_macro,node_documents,node_debate,node_risk,node_portfolio toneAmber
class node_stockdata,node_technicaltools,node_sentimenttools,node_newsfetch,node_exa,node_macrodata,node_doctools,node_risktools,node_portfoliotools toneMint
class node_pdf,node_sqlite toneRose
class node_user,node_exa_service toneIndigo
```

## Components

### User interface

- [Web chat](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/chat.html): `chat.html`
- [Web service](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/web_server.py): `web_server.py`

### Analysis workflow

- [Analysis pipeline](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/pipeline_orchestrator.py): `agents/pipeline_orchestrator.py`
- [Fundamental analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/fundamental_analyst.py): `agents/fundamental_analyst.py`
- [Technical analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/technical_analyst.py): `agents/technical_analyst.py`
- [Sentiment analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/sentiment_analyst.py): `agents/sentiment_analyst.py`
- [News intelligence](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/news_intelligence_agent.py): `agents/news_intelligence_agent.py`
- [Macro analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/macro_analyst.py): `agents/macro_analyst.py`
- [Document analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/document_analyst.py): `agents/document_analyst.py`
- [Bull-bear debate](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/debate_judge.py): `agents/debate_judge.py`
- [Risk management](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/risk_manager.py): `agents/risk_manager.py`
- [Portfolio analysis](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/agents/portfolio_analyst.py): `agents/portfolio_analyst.py`

### Analysis tools

- [Stock data](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/stock_data.py): `tools/stock_data.py`
- [Technical indicators](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/technical_analysis.py): `tools/technical_analysis.py`
- [Sentiment scoring](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/sentiment_analyzer.py): `tools/sentiment_analyzer.py`
- [News fetching](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/news_fetcher.py): `tools/news_fetcher.py`
- [Live research](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/exa_research.py): `tools/exa_research.py`
- [Macro data](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/macro_data.py): `tools/macro_data.py`
- [Company documents](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/document_analyzer.py): `tools/document_analyzer.py`
- [Risk calculations](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/risk_management.py): `tools/risk_management.py`
- [Portfolio metrics](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/tools/portfolio_analyzer.py): `tools/portfolio_analyzer.py`

### Persistence and reports

- [PDF report](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/pdf_generator.py): `pdf_generator.py`
- [Application database](https://github.com/svsairevanth/indian-stock-ai-agent/blob/master/app_data.db): `app_data.db`

### Other components

- **Investor**
- **Exa MCP**

## Connections

- Investor → Web chat: submits question (evidence: `README.md`)
- Web chat → Web service: sends chat (evidence: `README.md`)
- Web service → Analysis pipeline: runs analysis (evidence: `web_server.py`)
- Analysis pipeline → Fundamental analysis: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Technical analysis: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Sentiment analysis: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → News intelligence: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Macro analysis: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Document analysis: invokes analysis (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Bull-bear debate: invokes debate (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Risk management: invokes assessment (evidence: `agents/pipeline_orchestrator.py`)
- Analysis pipeline → Portfolio analysis: invokes when relevant (evidence: `README.md`)
- Fundamental analysis → Stock data: fetches metrics (evidence: `agents/fundamental_analyst.py`)
- Technical analysis → Technical indicators: calculates indicators (evidence: `agents/technical_analyst.py`)
- Technical analysis → Stock data: fetches prices (evidence: `agents/technical_analyst.py`)
- Sentiment analysis → News fetching: fetches news (evidence: `agents/sentiment_analyst.py`)
- Sentiment analysis → Sentiment scoring: scores sentiment (evidence: `agents/sentiment_analyst.py`)
- News intelligence → Live research: requests research (evidence: `agents/news_intelligence_agent.py`)
- News intelligence → Sentiment scoring: uses scoring (evidence: `agents/news_intelligence_agent.py`)
- Live research → Exa MCP: calls MCP (evidence: `tools/exa_research.py`)
- Macro analysis → Macro data: fetches indicators (evidence: `agents/macro_analyst.py`)
- Document analysis → Company documents: analyzes filings (evidence: `agents/document_analyst.py`)
- Risk management → Risk calculations: calculates trade risk (evidence: `agents/risk_manager.py`)
- Portfolio analysis → Portfolio metrics: analyzes holdings (evidence: `agents/portfolio_analyst.py`)
- Analysis pipeline → PDF report: generates report (evidence: `agents/pipeline_orchestrator.py`)
- Web service → Application database: persists history (evidence: `README.md`)
- Web service → PDF report: serves report (evidence: `README.md`)
