# rajmaurya0904/bhav architecture

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

- Interactive diagram: https://gitdiagram.com/rajmaurya0904/bhav
- Repository: https://github.com/rajmaurya0904/bhav

## Overview

Bhav is an NSE options backtesting product with CLI and web entry points. Users configure a run and provide a Python strategy; the runner loads live Upstox or offline workbook data, resolves contracts, simulates bars and portfolio costs, computes metrics and Monte Carlo robustness, then writes run artifacts for the dashboard. Strategy generation and validation form a separate capability. The graph follows relationships shown in excerpts or the README; unsampled API, frontend, and runtime wiring is represented conservatively.

Main entry points: [`bhav/engine/bar_engine.py`](https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/bar_engine.py) (Bar engine), [`bhav/cli.py`](https://github.com/rajmaurya0904/bhav/blob/main/bhav/cli.py) (Bhav CLI), [`bhav/api/server.py`](https://github.com/rajmaurya0904/bhav/blob/main/bhav/api/server.py) (Runs API), [`bhav/output/writer.py`](https://github.com/rajmaurya0904/bhav/blob/main/bhav/output/writer.py) (Result writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run interfaces"]
  node_cli["Bhav CLI<br/>[cli.py]"]
  node_api["Runs API<br/>[server.py]"]
  node_frontend["Web UI<br/>[page.tsx]"]
  node_results_page["Run dashboard<br/>[page.tsx]"]
end

subgraph group_data["Market data"]
  node_upstox{{"Upstox API"}}
  node_upstox_client["Upstox client<br/>[upstox_client.py]"]
  node_resolver["Contract resolver<br/>[instruments.py]"]
  node_reader["Live data reader<br/>[reader.py]"]
  node_cache[("Candle cache<br/>[cache.py]")]
  node_excel["Workbook source<br/>[excel_source.py]"]
  node_calendar["Trading calendar<br/>[calendar.py]"]
  node_underlyings["Underlying rules<br/>[underlyings.py]"]
  node_futures["Futures roll<br/>[futures.py]"]
end

subgraph group_simulation["Backtest simulation"]
  node_strategy["User strategy<br/>[strategy.py]"]
  node_engine["Bar engine<br/>[bar_engine.py]"]
  node_portfolio["Portfolio ledger<br/>[portfolio.py]"]
  node_costs["Indian cost model<br/>[costs.py]"]
end

subgraph group_results["Results and analysis"]
  node_report["Performance metrics<br/>[report.py]"]
  node_montecarlo["Monte Carlo<br/>[montecarlo.py]"]
  node_writer["Result writer<br/>[writer.py]"]
  node_run_store[("Run artifacts")]
end

subgraph group_generation["Strategy generation"]
  node_claude{{"Claude CLI"}}
  node_generator["Strategy generator"]
  node_prompt["Strategy prompt<br/>[prompt.py]"]
  node_validator["AST safety gate<br/>[validate.py]"]
  node_ai_api["AI frontend client<br/>[ai-prompt.ts]"]
end

node_cli_user(("CLI user"))
node_web_user(("Web user"))

node_cli_user -->|"runs backtest"| node_cli
node_web_user -->|"configures run"| node_frontend
node_frontend -.->|"submits run"| node_api
node_api -.->|"launches run"| node_engine
node_cli -->|"runs simulation"| node_engine
node_cli -->|"selects offline data"| node_excel
node_cli -.->|"selects live reader"| node_reader
node_cli -.->|"selects live resolver"| node_resolver
node_cli -.->|"computes metrics"| node_report
node_cli -.->|"bootstraps trades"| node_montecarlo
node_cli -->|"writes results"| node_writer
node_upstox_client -->|"requests candles"| node_upstox
node_resolver -->|"loads contracts"| node_upstox_client
node_reader -->|"fetches candles"| node_upstox_client
node_reader -.->|"reads and writes"| node_cache
node_engine -->|"reads bars"| node_reader
node_engine -->|"resolves options"| node_resolver
node_engine -->|"gets trading days"| node_calendar
node_engine -->|"gets lot size"| node_underlyings
node_engine -.->|"rolls future"| node_futures
node_engine -->|"dispatches bars"| node_strategy
node_engine -->|"updates positions"| node_portfolio
node_portfolio -->|"prices and charges"| node_costs
node_report -->|"reads trades and equity"| node_portfolio
node_montecarlo -->|"resamples trades"| node_portfolio
node_writer -->|"serializes trades"| node_portfolio
node_writer -->|"serializes metrics"| node_report
node_writer -->|"serializes robustness"| node_montecarlo
node_writer -->|"writes artifacts"| node_run_store
node_api -->|"lists run artifacts"| node_run_store
node_results_page -.->|"loads run details"| node_api
node_ai_api -.->|"requests generation"| node_api
node_api -->|"generates strategy"| node_generator
node_generator -->|"drives CLI"| node_claude
node_generator -->|"builds prompt"| node_prompt
node_generator -->|"validates output"| node_validator
node_validator -.->|"guards uploads"| node_api

click node_cli "https://github.com/rajmaurya0904/bhav/blob/main/bhav/cli.py"
click node_api "https://github.com/rajmaurya0904/bhav/blob/main/bhav/api/server.py"
click node_frontend "https://github.com/rajmaurya0904/bhav/blob/main/frontend/app/new/page.tsx"
click node_results_page "https://github.com/rajmaurya0904/bhav/blob/main/frontend/app/backtests/%5Bid%5D/page.tsx"
click node_upstox_client "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/upstox_client.py"
click node_resolver "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/instruments.py"
click node_reader "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/reader.py"
click node_cache "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/cache.py"
click node_excel "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/excel_source.py"
click node_calendar "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/calendar.py"
click node_underlyings "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/underlyings.py"
click node_futures "https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/futures.py"
click node_strategy "https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/strategy.py"
click node_engine "https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/bar_engine.py"
click node_portfolio "https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/portfolio.py"
click node_costs "https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/costs.py"
click node_report "https://github.com/rajmaurya0904/bhav/blob/main/bhav/metrics/report.py"
click node_montecarlo "https://github.com/rajmaurya0904/bhav/blob/main/bhav/metrics/montecarlo.py"
click node_writer "https://github.com/rajmaurya0904/bhav/blob/main/bhav/output/writer.py"
click node_generator "https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/claude_generator.py"
click node_prompt "https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/prompt.py"
click node_validator "https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/validate.py"
click node_ai_api "https://github.com/rajmaurya0904/bhav/blob/main/frontend/lib/ai-prompt.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_cli,node_api,node_frontend,node_results_page,node_cli_user,node_web_user toneBlue
class node_upstox,node_upstox_client,node_resolver,node_reader,node_cache,node_excel,node_calendar,node_underlyings,node_futures toneAmber
class node_strategy,node_engine,node_portfolio,node_costs toneMint
class node_report,node_montecarlo,node_writer,node_run_store toneRose
class node_claude,node_generator,node_prompt,node_validator,node_ai_api toneIndigo
```

## Components

### Run interfaces

- [Bhav CLI](https://github.com/rajmaurya0904/bhav/blob/main/bhav/cli.py): `bhav/cli.py`
- [Runs API](https://github.com/rajmaurya0904/bhav/blob/main/bhav/api/server.py): `bhav/api/server.py`
- [Web UI](https://github.com/rajmaurya0904/bhav/blob/main/frontend/app/new/page.tsx): `frontend/app/new/page.tsx`
- [Run dashboard](https://github.com/rajmaurya0904/bhav/blob/main/frontend/app/backtests/%5Bid%5D/page.tsx): `frontend/app/backtests/[id]/page.tsx`

### Market data

- **Upstox API**
- [Upstox client](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/upstox_client.py): `bhav/data/upstox_client.py`
- [Contract resolver](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/instruments.py): `bhav/data/instruments.py`
- [Live data reader](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/reader.py): `bhav/data/reader.py`
- [Candle cache](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/cache.py): `bhav/data/cache.py`
- [Workbook source](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/excel_source.py): `bhav/data/excel_source.py`
- [Trading calendar](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/calendar.py): `bhav/data/calendar.py`
- [Underlying rules](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/underlyings.py): `bhav/data/underlyings.py`
- [Futures roll](https://github.com/rajmaurya0904/bhav/blob/main/bhav/data/futures.py): `bhav/data/futures.py`

### Backtest simulation

- [User strategy](https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/strategy.py): `bhav/engine/strategy.py`
- [Bar engine](https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/bar_engine.py): `bhav/engine/bar_engine.py`
- [Portfolio ledger](https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/portfolio.py): `bhav/engine/portfolio.py`
- [Indian cost model](https://github.com/rajmaurya0904/bhav/blob/main/bhav/engine/costs.py): `bhav/engine/costs.py`

### Results and analysis

- [Performance metrics](https://github.com/rajmaurya0904/bhav/blob/main/bhav/metrics/report.py): `bhav/metrics/report.py`
- [Monte Carlo](https://github.com/rajmaurya0904/bhav/blob/main/bhav/metrics/montecarlo.py): `bhav/metrics/montecarlo.py`
- [Result writer](https://github.com/rajmaurya0904/bhav/blob/main/bhav/output/writer.py): `bhav/output/writer.py`
- **Run artifacts**

### Strategy generation

- **Claude CLI**
- [Strategy generator](https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/claude_generator.py): `bhav/ai/claude_generator.py`
- [Strategy prompt](https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/prompt.py): `bhav/ai/prompt.py`
- [AST safety gate](https://github.com/rajmaurya0904/bhav/blob/main/bhav/ai/validate.py): `bhav/ai/validate.py`
- [AI frontend client](https://github.com/rajmaurya0904/bhav/blob/main/frontend/lib/ai-prompt.ts): `frontend/lib/ai-prompt.ts`

### Other components

- **CLI user**
- **Web user**

## Connections

- CLI user → Bhav CLI: runs backtest
- Web user → Web UI: configures run
- Web UI → Runs API: submits run
- Runs API → Bar engine: launches run (evidence: `bhav/api/server.py`)
- Bhav CLI → Bar engine: runs simulation (evidence: `bhav/cli.py`)
- Bhav CLI → Workbook source: selects offline data (evidence: `bhav/cli.py`)
- Bhav CLI → Live data reader: selects live reader (evidence: `bhav/cli.py`)
- Bhav CLI → Contract resolver: selects live resolver (evidence: `bhav/cli.py`)
- Bhav CLI → Performance metrics: computes metrics (evidence: `bhav/cli.py`)
- Bhav CLI → Monte Carlo: bootstraps trades (evidence: `bhav/cli.py`)
- Bhav CLI → Result writer: writes results (evidence: `bhav/cli.py`)
- Upstox client → Upstox API: requests candles (evidence: `bhav/data/upstox_client.py`)
- Contract resolver → Upstox client: loads contracts (evidence: `bhav/data/instruments.py`)
- Live data reader → Upstox client: fetches candles (evidence: `bhav/data/reader.py`)
- Live data reader → Candle cache: reads and writes (evidence: `bhav/data/reader.py`)
- Bar engine → Live data reader: reads bars (evidence: `bhav/engine/bar_engine.py`)
- Bar engine → Contract resolver: resolves options (evidence: `bhav/engine/bar_engine.py`)
- Bar engine → Trading calendar: gets trading days (evidence: `bhav/engine/bar_engine.py`)
- Bar engine → Underlying rules: gets lot size (evidence: `bhav/engine/bar_engine.py`)
- Bar engine → Futures roll: rolls future
- Bar engine → User strategy: dispatches bars (evidence: `bhav/engine/bar_engine.py`)
- Bar engine → Portfolio ledger: updates positions (evidence: `bhav/engine/bar_engine.py`)
- Portfolio ledger → Indian cost model: prices and charges (evidence: `bhav/engine/portfolio.py`)
- Performance metrics → Portfolio ledger: reads trades and equity (evidence: `bhav/metrics/report.py`)
- Monte Carlo → Portfolio ledger: resamples trades (evidence: `bhav/metrics/montecarlo.py`)
- Result writer → Portfolio ledger: serializes trades (evidence: `bhav/output/writer.py`)
- Result writer → Performance metrics: serializes metrics (evidence: `bhav/output/writer.py`)
- Result writer → Monte Carlo: serializes robustness (evidence: `bhav/output/writer.py`)
- Result writer → Run artifacts: writes artifacts (evidence: `bhav/output/writer.py`)
- Runs API → Run artifacts: lists run artifacts (evidence: `bhav/api/server.py`)
- Run dashboard → Runs API: loads run details
- AI frontend client → Runs API: requests generation
- Runs API → Strategy generator: generates strategy (evidence: `bhav/api/server.py`)
- Strategy generator → Claude CLI: drives CLI (evidence: `bhav/ai/claude_generator.py`)
- Strategy generator → Strategy prompt: builds prompt (evidence: `bhav/ai/claude_generator.py`)
- Strategy generator → AST safety gate: validates output (evidence: `bhav/ai/claude_generator.py`)
- AST safety gate → Runs API: guards uploads