# armaanfarshori/dhan_algo architecture

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

- Interactive diagram: https://gitdiagram.com/armaanfarshori/dhan_algo
- Repository: https://github.com/armaanfarshori/dhan_algo

## Overview

Tessera is a self-hosted NSE trading platform. The main workflow ingests Dhan market data, builds bars, generates and gates strategy signals, applies risk controls, then executes and persists trades; paper trading is the default. A separate API process reads platform state for a polling dashboard. F&O collection/paper trading, options scalping, and historical backtesting are substantial parallel capabilities. The README documents the process-level wiring; sampled source also supports the scalper’s orchestration and dashboard polling, but not every subsystem’s internal calls.

Main entry points: [`db.py`](https://github.com/armaanfarshori/dhan_algo/blob/main/db.py) (TimescaleDB), [`engine/runner.py`](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/runner.py) (Strategy runner), [`engine/execution.py`](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/execution.py) (Executors), [`engine/scalper_orchestrator.py`](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/scalper_orchestrator.py) (Scalper orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Equity Trading"]
  node_trader["Trader process<br/>[trader.py]"]
  node_live_feed["Live feed<br/>[live_feed.py]"]
  node_bar_builder["Bar builder<br/>[bar_builder.py]"]
  node_runner["Strategy runner<br/>[runner.py]"]
  node_orb["ORB strategy<br/>[orb.py]"]
  node_kronos_gate["Kronos gate<br/>[kronos_gate.py]"]
  node_risk["Risk engine<br/>[risk.py]"]
  node_execution["Executors<br/>[execution.py]"]
  node_portfolio["Portfolio<br/>[portfolio.py]"]
end

subgraph group_options["Options Trading"]
  node_fno_collector["F&amp;O collection<br/>[fno_collector.py]"]
  node_fno_paper["F&amp;O paper<br/>[fno_paper.py]"]
  node_scalper["Scalper orchestration"]
  node_scalper_signals["Scalper signals<br/>[options_scalper.py]"]
end

subgraph group_research["Research"]
  node_backtest["Backtesting<br/>[engine.py]"]
  node_fno_backtest["F&amp;O backtesting"]
end

subgraph group_platform["API and Data"]
  node_database[("TimescaleDB<br/>[db.py]")]
  node_api["API process<br/>[api.py]"]
  node_routes["API routes"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard app<br/>[App.jsx]"]
  node_polling["Data polling"]
end

node_operator(("Operator"))
node_dhan_feed(("Dhan feed"))
node_dhan_api(("Dhan API"))

node_dhan_feed -->|"streams ticks"| node_live_feed
node_live_feed -->|"forwards ticks"| node_bar_builder
node_bar_builder -->|"writes bars"| node_database
node_trader -->|"starts feed"| node_live_feed
node_trader -->|"starts runner"| node_runner
node_runner -->|"requests decisions"| node_orb
node_runner -->|"checks signals"| node_kronos_gate
node_runner -->|"checks intent"| node_risk
node_runner -->|"submits orders"| node_execution
node_execution -.->|"places live orders"| node_dhan_api
node_execution -->|"records fills"| node_portfolio
node_portfolio -->|"persists positions"| node_database
node_fno_collector -->|"fetches options data"| node_dhan_api
node_fno_collector -->|"stores market history"| node_database
node_fno_paper -->|"records paper trades"| node_database
node_scalper -->|"polls signals"| node_scalper_signals
node_scalper -->|"checks entries"| node_risk
node_scalper -->|"submits orders"| node_execution
node_backtest -->|"reads bars"| node_database
node_fno_backtest -->|"reads history"| node_database
node_operator -->|"views dashboard"| node_dashboard_app
node_dashboard_app -->|"loads data"| node_polling
node_polling -->|"requests endpoints"| node_api
node_api -->|"dispatches requests"| node_routes
node_routes -->|"queries state"| node_database
node_routes -->|"fetches live account data"| node_dhan_api

click node_trader "https://github.com/armaanfarshori/dhan_algo/blob/main/apps/trader.py"
click node_live_feed "https://github.com/armaanfarshori/dhan_algo/blob/main/core/live_feed.py"
click node_bar_builder "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/bar_builder.py"
click node_runner "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/runner.py"
click node_orb "https://github.com/armaanfarshori/dhan_algo/blob/main/strategies/orb.py"
click node_kronos_gate "https://github.com/armaanfarshori/dhan_algo/blob/main/ml/kronos_gate.py"
click node_risk "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/risk.py"
click node_execution "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/execution.py"
click node_portfolio "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/portfolio.py"
click node_fno_collector "https://github.com/armaanfarshori/dhan_algo/blob/main/core/fno_collector.py"
click node_fno_paper "https://github.com/armaanfarshori/dhan_algo/blob/main/core/fno_paper.py"
click node_scalper "https://github.com/armaanfarshori/dhan_algo/blob/main/engine/scalper_orchestrator.py"
click node_scalper_signals "https://github.com/armaanfarshori/dhan_algo/blob/main/strategies/options_scalper.py"
click node_backtest "https://github.com/armaanfarshori/dhan_algo/blob/main/research/backtest/engine.py"
click node_fno_backtest "https://github.com/armaanfarshori/dhan_algo/blob/main/research/backtest/fno_orchestrator.py"
click node_database "https://github.com/armaanfarshori/dhan_algo/blob/main/db.py"
click node_api "https://github.com/armaanfarshori/dhan_algo/blob/main/apps/api.py"
click node_routes "https://github.com/armaanfarshori/dhan_algo/tree/main/apps/routes"
click node_dashboard_app "https://github.com/armaanfarshori/dhan_algo/blob/main/dashboard/src/App.jsx"
click node_polling "https://github.com/armaanfarshori/dhan_algo/blob/main/dashboard/src/hooks/useDashboardData.js"

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_trader,node_live_feed,node_bar_builder,node_runner,node_orb,node_kronos_gate,node_risk,node_execution,node_portfolio toneBlue
class node_fno_collector,node_fno_paper,node_scalper,node_scalper_signals toneAmber
class node_backtest,node_fno_backtest,node_dhan_api toneMint
class node_database,node_api,node_routes toneRose
class node_dashboard_app,node_polling,node_operator,node_dhan_feed toneIndigo
```

## Components

### Equity Trading

- [Trader process](https://github.com/armaanfarshori/dhan_algo/blob/main/apps/trader.py): `apps/trader.py`
- [Live feed](https://github.com/armaanfarshori/dhan_algo/blob/main/core/live_feed.py): `core/live_feed.py`
- [Bar builder](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/bar_builder.py): `engine/bar_builder.py`
- [Strategy runner](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/runner.py): `engine/runner.py`
- [ORB strategy](https://github.com/armaanfarshori/dhan_algo/blob/main/strategies/orb.py): `strategies/orb.py`
- [Kronos gate](https://github.com/armaanfarshori/dhan_algo/blob/main/ml/kronos_gate.py): `ml/kronos_gate.py`
- [Risk engine](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/risk.py): `engine/risk.py`
- [Executors](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/execution.py): `engine/execution.py`
- [Portfolio](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/portfolio.py): `engine/portfolio.py`

### Options Trading

- [F&O collection](https://github.com/armaanfarshori/dhan_algo/blob/main/core/fno_collector.py): `core/fno_collector.py`
- [F&O paper](https://github.com/armaanfarshori/dhan_algo/blob/main/core/fno_paper.py): `core/fno_paper.py`
- [Scalper orchestration](https://github.com/armaanfarshori/dhan_algo/blob/main/engine/scalper_orchestrator.py): `engine/scalper_orchestrator.py`
- [Scalper signals](https://github.com/armaanfarshori/dhan_algo/blob/main/strategies/options_scalper.py): `strategies/options_scalper.py`

### Research

- [Backtesting](https://github.com/armaanfarshori/dhan_algo/blob/main/research/backtest/engine.py): `research/backtest/engine.py`
- [F&O backtesting](https://github.com/armaanfarshori/dhan_algo/blob/main/research/backtest/fno_orchestrator.py): `research/backtest/fno_orchestrator.py`

### API and Data

- [TimescaleDB](https://github.com/armaanfarshori/dhan_algo/blob/main/db.py): `db.py`
- [API process](https://github.com/armaanfarshori/dhan_algo/blob/main/apps/api.py): `apps/api.py`
- [API routes](https://github.com/armaanfarshori/dhan_algo/tree/main/apps/routes): `apps/routes`

### Dashboard

- [Dashboard app](https://github.com/armaanfarshori/dhan_algo/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Data polling](https://github.com/armaanfarshori/dhan_algo/blob/main/dashboard/src/hooks/useDashboardData.js): `dashboard/src/hooks/useDashboardData.js`

### Other components

- **Operator**
- **Dhan feed**
- **Dhan API**

## Connections

- Dhan feed → Live feed: streams ticks
- Live feed → Bar builder: forwards ticks
- Bar builder → TimescaleDB: writes bars
- Trader process → Live feed: starts feed
- Trader process → Strategy runner: starts runner
- Strategy runner → ORB strategy: requests decisions
- Strategy runner → Kronos gate: checks signals
- Strategy runner → Risk engine: checks intent
- Strategy runner → Executors: submits orders
- Executors → Dhan API: places live orders
- Executors → Portfolio: records fills
- Portfolio → TimescaleDB: persists positions
- F&O collection → Dhan API: fetches options data
- F&O collection → TimescaleDB: stores market history
- F&O paper → TimescaleDB: records paper trades
- Scalper orchestration → Scalper signals: polls signals
- Scalper orchestration → Risk engine: checks entries
- Scalper orchestration → Executors: submits orders
- Backtesting → TimescaleDB: reads bars
- F&O backtesting → TimescaleDB: reads history
- Operator → Dashboard app: views dashboard
- Dashboard app → Data polling: loads data
- Data polling → API process: requests endpoints
- API process → API routes: dispatches requests
- API routes → TimescaleDB: queries state
- API routes → Dhan API: fetches live account data