# rajmaurya0904/kronos-options architecture

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

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

## Overview

Kronos Options Signal System turns index-market data into probabilistic forecasts, directional signals, and option recommendations, then evaluates them through historical backtests or simulated live trading; a separately documented, safety-locked real-order path is also present. Data collection, cleaning, modeling, signal classification, and option mapping are distinct stages. Backtester and PaperTrader orchestrate the stages; SQLite supports stored results and the dashboard presents them. The README supplies the main workflow and capabilities; some subsystem links reflect that documentation because their source was not sampled.

Main entry points: [`src/paper_trader.py`](https://github.com/rajmaurya0904/kronos-options/blob/master/src/paper_trader.py) (Paper Trader), [`src/backtester.py`](https://github.com/rajmaurya0904/kronos-options/blob/master/src/backtester.py) (Walk-Forward Backtester), [`src/broker/base.py`](https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/base.py) (Broker Interface), [`src/db.py`](https://github.com/rajmaurya0904/kronos-options/blob/master/src/db.py) (SQLite Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_data["Market Data & Forecasting"]
  node_fetcher["Data Fetcher<br/>[data_fetcher.py]"]
  node_cleaner["Data Cleaner<br/>[data_cleaner.py]"]
  node_forecaster["Kronos Forecaster<br/>[forecaster.py]"]
  node_broker_interface["Broker Interface<br/>[base.py]"]
  node_upstox["Upstox Broker<br/>[upstox.py]"]
  node_zerodha["Zerodha Stub<br/>[zerodha.py]"]
end

subgraph group_recommendations["Signals &amp; Options"]
  node_signal_engine["Signal Engine<br/>[signal_engine.py]"]
  node_options_mapper["Options Mapper<br/>[options_mapper.py]"]
end

subgraph group_trading["Trading &amp; Evaluation"]
  node_backtester["Walk-Forward Backtester<br/>[backtester.py]"]
  node_paper_trader["Paper Trader<br/>[paper_trader.py]"]
  node_live_trader["Live Trader<br/>[live_trader.py]"]
end

subgraph group_persistence_ui["Persistence &amp; Dashboard"]
  node_database[("SQLite Store<br/>[db.py]")]
  node_dashboard["Streamlit Dashboard<br/>[app.py]"]
end

node_user(("Operator"))
node_market_api["Upstox API"]
node_kronos_model["Kronos Model"]
node_notification["Desktop Notifications"]

node_user -->|"starts loop"| node_paper_trader
node_user -->|"runs backtest"| node_backtester
node_user -->|"views results"| node_dashboard
node_fetcher -->|"requests candles"| node_broker_interface
node_broker_interface -->|"implemented by"| node_upstox
node_broker_interface -.->|"stub alternative"| node_zerodha
node_upstox -->|"requests market data"| node_market_api
node_fetcher -->|"provides bars"| node_cleaner
node_forecaster -->|"runs predictions"| node_kronos_model
node_paper_trader -->|"fetches bars"| node_fetcher
node_paper_trader -->|"cleans bars"| node_cleaner
node_paper_trader -->|"forecasts prices"| node_forecaster
node_paper_trader -->|"generates signal"| node_signal_engine
node_paper_trader -->|"maps recommendation"| node_options_mapper
node_paper_trader -->|"gets option chain"| node_broker_interface
node_paper_trader -->|"logs paper trades"| node_database
node_paper_trader -->|"sends alerts"| node_notification
node_backtester -->|"fetches history"| node_fetcher
node_backtester -->|"forecasts bars"| node_forecaster
node_backtester -->|"generates signals"| node_signal_engine
node_backtester -->|"maps trades"| node_options_mapper
node_backtester -->|"requests option data"| node_broker_interface
node_backtester -->|"saves run results"| node_database
node_live_trader -.->|"places real orders"| node_broker_interface
node_signal_engine -->|"saves signals"| node_database
node_forecaster -->|"saves forecasts"| node_database
node_options_mapper -->|"fetches option chain"| node_broker_interface
node_dashboard -->|"reads forecasts and trades"| node_database

click node_fetcher "https://github.com/rajmaurya0904/kronos-options/blob/master/src/data_fetcher.py"
click node_cleaner "https://github.com/rajmaurya0904/kronos-options/blob/master/src/data_cleaner.py"
click node_forecaster "https://github.com/rajmaurya0904/kronos-options/blob/master/src/forecaster.py"
click node_signal_engine "https://github.com/rajmaurya0904/kronos-options/blob/master/src/signal_engine.py"
click node_options_mapper "https://github.com/rajmaurya0904/kronos-options/blob/master/src/options_mapper.py"
click node_backtester "https://github.com/rajmaurya0904/kronos-options/blob/master/src/backtester.py"
click node_paper_trader "https://github.com/rajmaurya0904/kronos-options/blob/master/src/paper_trader.py"
click node_live_trader "https://github.com/rajmaurya0904/kronos-options/blob/master/src/live_trader.py"
click node_broker_interface "https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/base.py"
click node_upstox "https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/upstox.py"
click node_zerodha "https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/zerodha.py"
click node_database "https://github.com/rajmaurya0904/kronos-options/blob/master/src/db.py"
click node_dashboard "https://github.com/rajmaurya0904/kronos-options/blob/master/dashboard/app.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_fetcher,node_cleaner,node_forecaster,node_broker_interface,node_upstox,node_zerodha toneBlue
class node_signal_engine,node_options_mapper toneAmber
class node_backtester,node_paper_trader,node_live_trader,node_market_api toneMint
class node_database,node_dashboard toneRose
class node_user,node_kronos_model,node_notification toneIndigo
```

## Components

### Market Data & Forecasting

- [Data Fetcher](https://github.com/rajmaurya0904/kronos-options/blob/master/src/data_fetcher.py): `src/data_fetcher.py`
- [Data Cleaner](https://github.com/rajmaurya0904/kronos-options/blob/master/src/data_cleaner.py): `src/data_cleaner.py`
- [Kronos Forecaster](https://github.com/rajmaurya0904/kronos-options/blob/master/src/forecaster.py): `src/forecaster.py`
- [Broker Interface](https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/base.py): `src/broker/base.py`
- [Upstox Broker](https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/upstox.py): `src/broker/upstox.py`
- [Zerodha Stub](https://github.com/rajmaurya0904/kronos-options/blob/master/src/broker/zerodha.py): `src/broker/zerodha.py`

### Signals & Options

- [Signal Engine](https://github.com/rajmaurya0904/kronos-options/blob/master/src/signal_engine.py): `src/signal_engine.py`
- [Options Mapper](https://github.com/rajmaurya0904/kronos-options/blob/master/src/options_mapper.py): `src/options_mapper.py`

### Trading & Evaluation

- [Walk-Forward Backtester](https://github.com/rajmaurya0904/kronos-options/blob/master/src/backtester.py): `src/backtester.py`
- [Paper Trader](https://github.com/rajmaurya0904/kronos-options/blob/master/src/paper_trader.py): `src/paper_trader.py`
- [Live Trader](https://github.com/rajmaurya0904/kronos-options/blob/master/src/live_trader.py): `src/live_trader.py`

### Persistence & Dashboard

- [SQLite Store](https://github.com/rajmaurya0904/kronos-options/blob/master/src/db.py): `src/db.py`
- [Streamlit Dashboard](https://github.com/rajmaurya0904/kronos-options/blob/master/dashboard/app.py): `dashboard/app.py`

### Other components

- **Operator**
- **Upstox API**
- **Kronos Model**
- **Desktop Notifications**

## Connections

- Operator → Paper Trader: starts loop
- Operator → Walk-Forward Backtester: runs backtest
- Operator → Streamlit Dashboard: views results
- Data Fetcher → Broker Interface: requests candles
- Broker Interface → Upstox Broker: implemented by
- Broker Interface → Zerodha Stub: stub alternative
- Upstox Broker → Upstox API: requests market data
- Data Fetcher → Data Cleaner: provides bars
- Kronos Forecaster → Kronos Model: runs predictions
- Paper Trader → Data Fetcher: fetches bars
- Paper Trader → Data Cleaner: cleans bars
- Paper Trader → Kronos Forecaster: forecasts prices
- Paper Trader → Signal Engine: generates signal
- Paper Trader → Options Mapper: maps recommendation
- Paper Trader → Broker Interface: gets option chain
- Paper Trader → SQLite Store: logs paper trades
- Paper Trader → Desktop Notifications: sends alerts
- Walk-Forward Backtester → Data Fetcher: fetches history
- Walk-Forward Backtester → Kronos Forecaster: forecasts bars
- Walk-Forward Backtester → Signal Engine: generates signals
- Walk-Forward Backtester → Options Mapper: maps trades
- Walk-Forward Backtester → Broker Interface: requests option data
- Walk-Forward Backtester → SQLite Store: saves run results
- Live Trader → Broker Interface: places real orders
- Signal Engine → SQLite Store: saves signals
- Kronos Forecaster → SQLite Store: saves forecasts
- Options Mapper → Broker Interface: fetches option chain
- Streamlit Dashboard → SQLite Store: reads forecasts and trades