# indubitablysrivathsan/candl architecture

> Architecture diagram of the GitHub repository indubitablysrivathsan/candl, 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/indubitablysrivathsan/candl
- Repository: https://github.com/indubitablysrivathsan/candl

## Overview

candL is a self-hosted NSE end-of-day analytics product. Traders and analysts explore options, futures, stocks, market activity, participant positioning, and FII activity in a React terminal; the frontend requests analytics from FastAPI, which queries local DuckDB. On startup, the API invokes a sync that fetches NSE archives, processes them, and tracks per-date/file progress. The README documents these capabilities and the ingestion flow; sampled source confirms the API startup hook, options queries, and database layer, but not every route or pipeline call in detail.

Main entry points: [`frontend/src/App.jsx`](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/App.jsx) (React app), [`frontend/src/api/client.js`](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/api/client.js) (API client), [`pipeline/startup_sync.py`](https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/startup_sync.py) (Startup sync), [`api/main.py`](https://github.com/indubitablysrivathsan/candl/blob/main/api/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Analytics interface"]
  node_app["React app<br/>[App.jsx]"]
  node_options["Options analysis<br/>[Options.jsx]"]
  node_futures["Futures analytics<br/>[Futures.jsx]"]
  node_stocks["Stock analysis<br/>[Stocks.jsx]"]
  node_market["Market overview<br/>[Market.jsx]"]
  node_participants["Participant flows<br/>[Participants.jsx]"]
  node_fii["FII analytics<br/>[FII.jsx]"]
  node_client["API client<br/>[client.js]"]
end

subgraph group_service["API service"]
  node_api["FastAPI app<br/>[main.py]"]
  node_routes["Analytics routes"]
end

subgraph group_ingest["Data ingestion"]
  node_sync["Startup sync<br/>[startup_sync.py]"]
  node_downloader["Archive downloader<br/>[downloader.py]"]
  node_processors["Data processors"]
  node_manifest["Progress manifest<br/>[manifest.py]"]
end

subgraph group_storage["Local data"]
  node_db_layer["Query layer<br/>[db.py]"]
  node_duckdb[("DuckDB store")]
end

node_analyst(("Trader / analyst"))
node_nse["NSE archives"]

node_analyst -->|"uses"| node_app
node_app -->|"routes to"| node_options
node_app -->|"routes to"| node_futures
node_app -->|"routes to"| node_stocks
node_app -->|"routes to"| node_market
node_app -->|"routes to"| node_participants
node_app -->|"routes to"| node_fii
node_options -->|"requests data"| node_client
node_futures -->|"requests data"| node_client
node_stocks -->|"requests data"| node_client
node_market -->|"requests data"| node_client
node_participants -->|"requests data"| node_client
node_fii -->|"requests data"| node_client
node_client -->|"HTTP requests"| node_api
node_api -->|"dispatches"| node_routes
node_routes -->|"queries"| node_db_layer
node_db_layer -->|"reads"| node_duckdb
node_api -->|"runs at startup"| node_sync
node_sync -->|"downloads files"| node_downloader
node_downloader -->|"fetches archives"| node_nse
node_sync -->|"runs processing"| node_processors
node_processors -->|"writes processed data"| node_duckdb
node_sync -->|"tracks progress"| node_manifest

click node_app "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/App.jsx"
click node_options "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Options.jsx"
click node_futures "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Futures.jsx"
click node_stocks "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Stocks.jsx"
click node_market "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Market.jsx"
click node_participants "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Participants.jsx"
click node_fii "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/FII.jsx"
click node_client "https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/api/client.js"
click node_api "https://github.com/indubitablysrivathsan/candl/blob/main/api/main.py"
click node_routes "https://github.com/indubitablysrivathsan/candl/tree/main/api/routes"
click node_db_layer "https://github.com/indubitablysrivathsan/candl/blob/main/api/db.py"
click node_sync "https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/startup_sync.py"
click node_downloader "https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/downloader.py"
click node_processors "https://github.com/indubitablysrivathsan/candl/tree/main/pipeline/processors"
click node_manifest "https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/manifest.py"

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_app,node_options,node_futures,node_stocks,node_market,node_participants,node_fii,node_client toneBlue
class node_api,node_routes toneAmber
class node_sync,node_downloader,node_processors,node_manifest toneMint
class node_db_layer,node_duckdb toneRose
class node_analyst,node_nse toneIndigo
```

## Components

### Analytics interface

- [React app](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Options analysis](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Options.jsx): `frontend/src/pages/Options.jsx`
- [Futures analytics](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Futures.jsx): `frontend/src/pages/Futures.jsx`
- [Stock analysis](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Stocks.jsx): `frontend/src/pages/Stocks.jsx`
- [Market overview](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Market.jsx): `frontend/src/pages/Market.jsx`
- [Participant flows](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/Participants.jsx): `frontend/src/pages/Participants.jsx`
- [FII analytics](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/pages/FII.jsx): `frontend/src/pages/FII.jsx`
- [API client](https://github.com/indubitablysrivathsan/candl/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### API service

- [FastAPI app](https://github.com/indubitablysrivathsan/candl/blob/main/api/main.py): `api/main.py`
- [Analytics routes](https://github.com/indubitablysrivathsan/candl/tree/main/api/routes): `api/routes`

### Data ingestion

- [Startup sync](https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/startup_sync.py): `pipeline/startup_sync.py`
- [Archive downloader](https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/downloader.py): `pipeline/downloader.py`
- [Data processors](https://github.com/indubitablysrivathsan/candl/tree/main/pipeline/processors): `pipeline/processors`
- [Progress manifest](https://github.com/indubitablysrivathsan/candl/blob/main/pipeline/manifest.py): `pipeline/manifest.py`

### Local data

- [Query layer](https://github.com/indubitablysrivathsan/candl/blob/main/api/db.py): `api/db.py`
- **DuckDB store**

### Other components

- **Trader / analyst**
- **NSE archives**

## Connections

- Trader / analyst → React app: uses
- React app → Options analysis: routes to
- React app → Futures analytics: routes to
- React app → Stock analysis: routes to
- React app → Market overview: routes to
- React app → Participant flows: routes to
- React app → FII analytics: routes to
- Options analysis → API client: requests data
- Futures analytics → API client: requests data
- Stock analysis → API client: requests data
- Market overview → API client: requests data
- Participant flows → API client: requests data
- FII analytics → API client: requests data
- API client → FastAPI app: HTTP requests
- FastAPI app → Analytics routes: dispatches
- Analytics routes → Query layer: queries
- Query layer → DuckDB store: reads
- FastAPI app → Startup sync: runs at startup
- Startup sync → Archive downloader: downloads files
- Archive downloader → NSE archives: fetches archives
- Startup sync → Data processors: runs processing
- Data processors → DuckDB store: writes processed data
- Startup sync → Progress manifest: tracks progress