# kishorejegan/nifty-optionchain-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kishorejegan/nifty-optionchain-ai
- Repository: https://github.com/kishorejegan/nifty-optionchain-ai

## Overview

#### Purpose and Product Surface
NIFTY-OPTIONCHAIN-AI is a B2C SaaS for Indian NIFTY options traders: it collects/analyzes option-chain market data, produces AI-assisted trading insights, supports automated monitoring/alerts, and exposes chat and analysis interfaces. The repo contains multiple client implementations and legacy/alternate artifacts; the primary server-side product is under `Backend/`.

#### Backend API Runtime
The FastAPI-style application is entered through `Backend/app/main.py`, with application settings in `Backend/app/config.py`. HTTP concerns are separated into route modules for market data, analysis, recipes, control operations, and files:
- `Backend/app/routers/market.py`
- `Backend/app/routers/analysis.py`
- `Backend/app/routers/recipes.py`

Cross-cutting request boundaries include Firebase authentication, logging, rate limiting, and security middleware:
- `Backend/app/auth/firebase_auth.py`
- `Backend/app/middleware/rate_limit.py`
- `Backend/app/middleware/security.py`

#### Market Data and Quantitative Analysis
Market acquisition is centered on an NSE client and supporting scraper paths, then passed into analysis/domain models. The main boundary isolates external NSE responses from API-facing market representations:
- `Backend/app/services/nse_client.py`
- `Backend/nse_scraper.py`
- `Backend/app/models/market.py`

Quant modules calculate option-chain signals such as open-interest/strike analysis, divergence, charts, and trading logic:
- `Backend/ai_brain/data_engine.py`
- `Backend/ai_brain/strike_analyzer.py`
- `Backend/ai_brain/quant_logic.py`

This data layer is the core dependency for both direct market endpoints and AI-driven analysis.

#### AI Agent and Orchestration Layer
`ai_brain` is a separate intelligence subsystem, with an agent core, tool registry, tool implementations, and persistence/auth support:
- `Backend/ai_brain/agent/agent_core.py`
- `Backend/ai_brain/agent/tool_registry.py`
- `Backend/ai_brain/agent/tools/analysis_tools.py`

The agent can invoke market, analysis, scheduling, and alert tools rather than coupling LLM conversation directly to data sources. Higher-level application orchestration coordinates analysis execution, classification, RAG, safety, and recipe-driven workflows:
- `Backend/app/services/orchestrator.py`
- `Backend/app/services/analysis_runner.py`
- `Backend/app/services/rag.py`

LLM/server and conversational entry modules exist in `Backend/ai_brain/llm_server.py` and `Backend/ai_brain/copilot.py`; provider credentials/configuration are expected through environment files.

#### Alerts, Notifications, and Persistence Boundaries
Alert evaluation is modeled in the agent layer and exposed through application notification services:
- `Backend/ai_brain/agent/alert_engine.py`
- `Backend/ai_brain/agent/tools/alert_tools.py`
- `Backend/app/services/notifications.py`

Firebase is the material external identity/backend integration, used via:
- `Backend/app/auth/firebase_auth.py`
- `Backend/app/services/firebase.py`

Recipes provide reusable/user-configurable analysis or automation flows:
- `Backend/app/services/recipe_engine.py`
- `Backend/app/models/recipe.py`
- `Backend/app/routers/recipes.py`

#### Client and Extension Entry Points
A Vite/React browser extension client lives in `Backend/extension/`, beginning at `Backend/extension/src/main.jsx` and communicating through `Backend/extension/src/services/api.js`; Chrome extension lifecycle is configured in `Backend/extension/public/manifest.json`.

A richer TypeScript Vite UI exists independently in `New UI/`, with app composition and workspace tabs at:
- `New UI/src/main.tsx`
- `New UI/src/App.tsx`
- `New UI/src/components/AgentWorkspace.tsx`

`intraday-extension/` appears to be another packaged extension variant, with its own API client and manifest:
- `intraday-extension/src/services/api.ts`
- `intraday-extension/public/manifest.json`

#### Operational Entry Points and Infrastructure
Standalone scripts support server/system startup and market-monitor/analysis modes:
- `Backend/server.py`
- `Backend/start_all.py`
- `Backend/run_analysis_system.py`

Python dependencies are split between backend and AI-brain requirements:
- `Backend/requirements.txt`
- `Backend/ai_brain/requirements.txt`

GitHub Actions defines backend and extension CI workflows:
- `Backend/.github/workflows/backend.yml`
- `Backend/.github/workflows/extension.yml`

Main entry points: [`Backend/app/main.py`](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/main.py) (FastAPI application), [`Backend/app/services/orchestrator.py`](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/orchestrator.py) (Analysis orchestrator), [`Backend/app/services/nse_client.py`](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/nse_client.py) (NSE market client), [`Backend/ai_brain/agent/agent_core.py`](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/agent_core.py) (Agent core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_fastapi["FastAPI application<br/>API runtime<br/>[main.py]"]
  node_middleware["Auth &amp; request controls<br/>middleware<br/>[firebase_auth.py]"]
  node_market_routes["Market API<br/>route module<br/>[market.py]"]
  node_analysis_routes["Analysis API<br/>route module<br/>[analysis.py]"]
  node_recipe_routes["Recipe API<br/>route module<br/>[recipes.py]"]
  node_market_service["NSE market client<br/>market service<br/>[nse_client.py]"]
  node_market_models["Market models<br/>domain models<br/>[market.py]"]
  node_orchestrator["Analysis orchestrator<br/>workflow service<br/>[orchestrator.py]"]
  node_recipe_engine["Recipe engine<br/>automation service<br/>[recipe_engine.py]"]
  node_notifications["Notifications<br/>notification service<br/>[notifications.py]"]
end

subgraph group_intelligence["AI &amp; Quant Engine"]
  node_quant_engine["Quant data engine<br/>quant analysis<br/>[data_engine.py]"]
  node_agent_core{{"Agent core<br/>AI agent<br/>[agent_core.py]"}}
  node_tool_registry["Agent tool registry<br/>tool dispatch<br/>[tool_registry.py]"]
  node_alert_engine["Alert engine<br/>alert evaluator<br/>[alert_engine.py]"]
  node_llm_server["LLM server<br/>LLM runtime<br/>[llm_server.py]"]
end

subgraph group_clients["Clients"]
  node_extension["Browser extension<br/>React extension client<br/>[main.jsx]"]
  node_new_ui["Trader workspace UI<br/>TypeScript Vite client<br/>[App.tsx]"]
  node_extension_variant["Intraday extension<br/>extension client<br/>[api.ts]"]
end

node_firebase[("Firebase<br/>external identity backend<br/>[firebase.py]")]
node_nse["NSE<br/>external market source"]

node_extension -->|"API calls"| node_fastapi
node_new_ui -->|"API calls"| node_fastapi
node_extension_variant -->|"API calls"| node_fastapi
node_fastapi -->|"applies"| node_middleware
node_middleware -->|"verifies identity"| node_firebase
node_fastapi -->|"serves"| node_market_routes
node_fastapi -->|"serves"| node_analysis_routes
node_fastapi -->|"serves"| node_recipe_routes
node_market_routes -->|"fetches"| node_market_service
node_market_service -->|"acquires data"| node_nse
node_market_service -->|"maps to"| node_market_models
node_market_models -->|"feeds"| node_quant_engine
node_analysis_routes -->|"runs"| node_orchestrator
node_orchestrator -->|"executes analysis"| node_quant_engine
node_orchestrator -->|"delegates AI tasks"| node_agent_core
node_agent_core -->|"uses"| node_llm_server
node_agent_core -->|"invokes tools"| node_tool_registry
node_tool_registry -->|"analysis tools"| node_quant_engine
node_tool_registry -->|"alert tools"| node_alert_engine
node_alert_engine -->|"triggers"| node_notifications
node_recipe_routes -->|"manages flows"| node_recipe_engine
node_recipe_engine -->|"executes workflows"| node_orchestrator

click node_fastapi "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/main.py"
click node_middleware "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/auth/firebase_auth.py"
click node_market_routes "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/market.py"
click node_analysis_routes "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/analysis.py"
click node_recipe_routes "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/recipes.py"
click node_market_service "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/nse_client.py"
click node_market_models "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/models/market.py"
click node_orchestrator "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/orchestrator.py"
click node_recipe_engine "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/recipe_engine.py"
click node_notifications "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/notifications.py"
click node_firebase "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/firebase.py"
click node_quant_engine "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/data_engine.py"
click node_agent_core "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/agent_core.py"
click node_tool_registry "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/tool_registry.py"
click node_alert_engine "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/alert_engine.py"
click node_llm_server "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/llm_server.py"
click node_extension "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/extension/src/main.jsx"
click node_new_ui "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/New%20UI/src/App.tsx"
click node_extension_variant "https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/intraday-extension/src/services/api.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_fastapi,node_middleware,node_market_routes,node_analysis_routes,node_recipe_routes,node_market_service,node_market_models,node_orchestrator,node_recipe_engine,node_notifications toneBlue
class node_quant_engine,node_agent_core,node_tool_registry,node_alert_engine,node_llm_server toneAmber
class node_extension,node_new_ui,node_extension_variant toneMint
class node_firebase,node_nse toneNeutral
```

## Components

### Backend API

- [FastAPI application](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/main.py): API runtime · `Backend/app/main.py`
- [Auth & request controls](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/auth/firebase_auth.py): middleware · Firebase auth, rate limiting, and security boundaries. · `Backend/app/auth/firebase_auth.py`
- [Market API](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/market.py): route module · `Backend/app/routers/market.py`
- [Analysis API](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/analysis.py): route module · `Backend/app/routers/analysis.py`
- [Recipe API](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/routers/recipes.py): route module · `Backend/app/routers/recipes.py`
- [NSE market client](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/nse_client.py): market service · Normalizes external NSE market responses. · `Backend/app/services/nse_client.py`
- [Market models](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/models/market.py): domain models · `Backend/app/models/market.py`
- [Analysis orchestrator](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/orchestrator.py): workflow service · Coordinates analysis, RAG, safety, and workflows. · `Backend/app/services/orchestrator.py`
- [Recipe engine](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/recipe_engine.py): automation service · `Backend/app/services/recipe_engine.py`
- [Notifications](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/notifications.py): notification service · `Backend/app/services/notifications.py`

### AI & Quant Engine

- [Quant data engine](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/data_engine.py): quant analysis · Computes option-chain signals and trading logic. · `Backend/ai_brain/data_engine.py`
- [Agent core](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/agent_core.py): AI agent · `Backend/ai_brain/agent/agent_core.py`
- [Agent tool registry](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/tool_registry.py): tool dispatch · `Backend/ai_brain/agent/tool_registry.py`
- [Alert engine](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/agent/alert_engine.py): alert evaluator · `Backend/ai_brain/agent/alert_engine.py`
- [LLM server](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/ai_brain/llm_server.py): LLM runtime · `Backend/ai_brain/llm_server.py`

### Clients

- [Browser extension](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/extension/src/main.jsx): React extension client · `Backend/extension/src/main.jsx`
- [Trader workspace UI](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/New%20UI/src/App.tsx): TypeScript Vite client · `New UI/src/App.tsx`
- [Intraday extension](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/intraday-extension/src/services/api.ts): extension client · `intraday-extension/src/services/api.ts`

### Other components

- [Firebase](https://github.com/kishorejegan/nifty-optionchain-ai/blob/main/Backend/app/services/firebase.py): external identity backend · `Backend/app/services/firebase.py`
- **NSE**: external market source

## Connections

- Browser extension → FastAPI application: API calls
- Trader workspace UI → FastAPI application: API calls
- Intraday extension → FastAPI application: API calls
- FastAPI application → Auth & request controls: applies
- Auth & request controls → Firebase: verifies identity
- FastAPI application → Market API: serves
- FastAPI application → Analysis API: serves
- FastAPI application → Recipe API: serves
- Market API → NSE market client: fetches
- NSE market client → NSE: acquires data
- NSE market client → Market models: maps to
- Market models → Quant data engine: feeds
- Analysis API → Analysis orchestrator: runs
- Analysis orchestrator → Quant data engine: executes analysis
- Analysis orchestrator → Agent core: delegates AI tasks
- Agent core → LLM server: uses
- Agent core → Agent tool registry: invokes tools
- Agent tool registry → Quant data engine: analysis tools
- Agent tool registry → Alert engine: alert tools
- Alert engine → Notifications: triggers
- Recipe API → Recipe engine: manages flows
- Recipe engine → Analysis orchestrator: executes workflows