# harsha238/indiaquant-mcp-stock-ai-assistant architecture

> Architecture diagram of the GitHub repository harsha238/indiaquant-mcp-stock-ai-assistant, 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/harsha238/indiaquant-mcp-stock-ai-assistant
- Repository: https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant

## Overview

IndiaQuant MCP serves stock-market analytics through FastAPI endpoints that return prices, signals, options analysis, sentiment, Greeks, and portfolio results. Its main workflow is an AI agent or API client requesting a tool, the server dispatching to a domain module, and that module obtaining market/news data or using portfolio storage before returning a result. The README documents additional capabilities such as sector heatmaps and market scanning. Sampled source supports the principal calls; unsampled internals are represented only where documented.

Main entry points: [`server.py`](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/server.py) (FastAPI Tools), [`modules/market_data.py`](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py) (Market Data), [`modules/signals.py`](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/signals.py) (Trade Signals), [`modules/portfolio.py`](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/portfolio.py) (Portfolio Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Layer"]
  node_server["FastAPI Tools<br/>[server.py]"]
end

subgraph group_analytics["Market Analytics"]
  node_market_data["Market Data<br/>[market_data.py]"]
  node_sector_heatmap["Sector Heatmap<br/>[market_data.py]"]
  node_signals["Trade Signals<br/>[signals.py]"]
  node_market_scanner["Market Scanner<br/>[signals.py]"]
  node_indicators["Technical Indicators<br/>[indicators.py]"]
  node_options_chain["Options Chain<br/>[market_data.py]"]
  node_options_analysis["Unusual Activity"]
  node_greeks["Greeks Calculator<br/>[black_scholes.py]"]
  node_sentiment["News Sentiment<br/>[sentiment.py]"]
end

subgraph group_portfolio["Portfolio"]
  node_portfolio["Portfolio Manager<br/>[portfolio.py]"]
  node_portfolio_db[("Portfolio Database<br/>[portfolio.db]")]
end

subgraph group_integrations["External Data"]
  node_yahoo["Yahoo Finance"]
  node_newsapi["NewsAPI"]
end

node_client(("AI Agent / Client"))

node_client -->|"requests tools"| node_server
node_server -->|"gets prices"| node_market_data
node_server -->|"gets chain"| node_options_chain
node_server -->|"generates signal"| node_signals
node_server -->|"scans market"| node_market_scanner
node_server -->|"gets heatmap"| node_sector_heatmap
node_server -->|"detects activity"| node_options_analysis
node_server -->|"calculates Greeks"| node_greeks
node_server -->|"analyzes sentiment"| node_sentiment
node_server -->|"manages portfolio"| node_portfolio
node_market_data -->|"fetches market data"| node_yahoo
node_sector_heatmap -->|"reads price changes"| node_market_data
node_options_chain -->|"fetches option chain"| node_yahoo
node_options_analysis -->|"fetches option data"| node_yahoo
node_signals -->|"loads history"| node_market_data
node_signals -->|"calculates indicators"| node_indicators
node_market_scanner -->|"loads history"| node_market_data
node_market_scanner -->|"calculates RSI"| node_indicators
node_portfolio -->|"gets live prices"| node_market_data
node_portfolio -->|"reads and writes"| node_portfolio_db
node_sentiment -->|"requests headlines"| node_newsapi

click node_server "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/server.py"
click node_market_data "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py"
click node_sector_heatmap "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py"
click node_signals "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/signals.py"
click node_market_scanner "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/signals.py"
click node_indicators "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/utils/indicators.py"
click node_options_chain "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py"
click node_options_analysis "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/options_analysis.py"
click node_greeks "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/utils/black_scholes.py"
click node_sentiment "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/sentiment.py"
click node_portfolio "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/portfolio.py"
click node_portfolio_db "https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/database/portfolio.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_server,node_client toneBlue
class node_market_data,node_sector_heatmap,node_signals,node_market_scanner,node_indicators,node_options_chain,node_options_analysis,node_greeks,node_sentiment toneAmber
class node_portfolio,node_portfolio_db toneMint
class node_yahoo,node_newsapi toneRose
```

## Components

### API Layer

- [FastAPI Tools](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/server.py): `server.py`

### Market Analytics

- [Market Data](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py): `modules/market_data.py`
- [Sector Heatmap](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py): `modules/market_data.py`
- [Trade Signals](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/signals.py): `modules/signals.py`
- [Market Scanner](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/signals.py): `modules/signals.py`
- [Technical Indicators](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/utils/indicators.py): `utils/indicators.py`
- [Options Chain](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/market_data.py): `modules/market_data.py`
- [Unusual Activity](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/options_analysis.py): `modules/options_analysis.py`
- [Greeks Calculator](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/utils/black_scholes.py): `utils/black_scholes.py`
- [News Sentiment](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/sentiment.py): `modules/sentiment.py`

### Portfolio

- [Portfolio Manager](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/modules/portfolio.py): `modules/portfolio.py`
- [Portfolio Database](https://github.com/harsha238/indiaquant-mcp-stock-ai-assistant/blob/main/database/portfolio.db): `database/portfolio.db`

### External Data

- **Yahoo Finance**
- **NewsAPI**

### Other components

- **AI Agent / Client**

## Connections

- AI Agent / Client → FastAPI Tools: requests tools (evidence: `README.md`)
- FastAPI Tools → Market Data: gets prices (evidence: `server.py`)
- FastAPI Tools → Options Chain: gets chain (evidence: `server.py`)
- FastAPI Tools → Trade Signals: generates signal (evidence: `server.py`)
- FastAPI Tools → Market Scanner: scans market (evidence: `server.py`)
- FastAPI Tools → Sector Heatmap: gets heatmap (evidence: `server.py`)
- FastAPI Tools → Unusual Activity: detects activity (evidence: `server.py`)
- FastAPI Tools → Greeks Calculator: calculates Greeks (evidence: `server.py`)
- FastAPI Tools → News Sentiment: analyzes sentiment (evidence: `server.py`)
- FastAPI Tools → Portfolio Manager: manages portfolio (evidence: `server.py`)
- Market Data → Yahoo Finance: fetches market data (evidence: `modules/market_data.py`)
- Sector Heatmap → Market Data: reads price changes (evidence: `modules/market_data.py`)
- Options Chain → Yahoo Finance: fetches option chain (evidence: `modules/market_data.py`)
- Unusual Activity → Yahoo Finance: fetches option data (evidence: `modules/options_analysis.py`)
- Trade Signals → Market Data: loads history (evidence: `modules/signals.py`)
- Trade Signals → Technical Indicators: calculates indicators (evidence: `modules/signals.py`)
- Market Scanner → Market Data: loads history (evidence: `modules/signals.py`)
- Market Scanner → Technical Indicators: calculates RSI (evidence: `modules/signals.py`)
- Portfolio Manager → Market Data: gets live prices (evidence: `modules/portfolio.py`)
- Portfolio Manager → Portfolio Database: reads and writes (evidence: `modules/portfolio.py`)
- News Sentiment → NewsAPI: requests headlines (evidence: `modules/sentiment.py`)