# periza0/cashcarrybot architecture

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

- Interactive diagram: https://gitdiagram.com/periza0/cashcarrybot
- Repository: https://github.com/periza0/cashcarrybot

## Overview

This repository is a two-mode futures-arbitrage bot: the live engine processes Zerodha ticks, while the backtest engine evaluates aligned historical minute bars. Both calculate cost-of-carry fair value, compare mispricing with estimated costs, track expiry-based positions and P&L, and log signals to CSV. The README also describes instrument discovery, dividend lookup, transaction-cost filtering, and risk tracking. Source excerpts show implementation details for both engines; some broader README capabilities, such as live authentication and trade execution, are not evidenced as separate runtime components.

Main entry points: [`CashAndCarry.py`](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py) (Trade Decision), [`backTest.py`](https://github.com/periza0/cashcarrybot/blob/main/backTest.py) (Trade Decision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live Trading"]
  node_live_engine["Live Engine<br/>[CashAndCarry.py]"]
  node_streaming["Tick Stream<br/>[CashAndCarry.py]"]
  node_live_state[("Position State<br/>[CashAndCarry.py]")]
  node_live_log["Live Signal Log<br/>[CashAndCarry.py]"]
end

subgraph group_backtest["Backtesting"]
  node_backtest_engine["Backtest Engine<br/>[backTest.py]"]
  node_historical_data["Historical Bars<br/>[backTest.py]"]
  node_backtest_state[("Backtest State<br/>[backTest.py]")]
  node_backtest_log["Backtest Signal Log<br/>[backTest.py]"]
end

subgraph group_strategy["Arbitrage Strategy"]
  node_pricing["Fair Value<br/>[CashAndCarry.py]"]
  node_costs["Cost Estimate<br/>[CashAndCarry.py]"]
  node_decision["Trade Decision<br/>[CashAndCarry.py]"]
  node_risk_pnl["Risk and P&amp;L<br/>[CashAndCarry.py]"]
  node_backtest_pricing["Fair Value<br/>[backTest.py]"]
  node_backtest_costs["Cost Estimate<br/>[backTest.py]"]
  node_backtest_decision["Trade Decision<br/>[backTest.py]"]
  node_backtest_risk["Risk and P&amp;L<br/>[backTest.py]"]
end

subgraph group_integrations["Data Integrations"]
  node_instruments["Instrument Discovery<br/>[CashAndCarry.py]"]
  node_kite["Kite Connect"]
  node_dividend["Dividend Lookup<br/>[CashAndCarry.py]"]
  node_screener["Screener.in"]
  node_history_instruments["Backtest Instruments<br/>[backTest.py]"]
  node_history_kite["Kite Connect"]
end

node_trader(("Trader"))

node_trader -->|"starts"| node_live_engine
node_live_engine -->|"authenticates"| node_kite
node_live_engine -->|"discovers"| node_instruments
node_instruments -->|"fetches instruments"| node_kite
node_live_engine -->|"retrieves yield"| node_dividend
node_dividend -->|"requests data"| node_screener
node_live_engine -->|"starts stream"| node_streaming
node_streaming -->|"subscribes"| node_kite
node_streaming -->|"provides prices"| node_pricing
node_streaming -->|"invokes"| node_decision
node_decision -->|"calculates value"| node_pricing
node_decision -->|"estimates costs"| node_costs
node_decision -->|"updates position"| node_live_state
node_decision -->|"realizes P&amp;L"| node_risk_pnl
node_decision -->|"writes signals"| node_live_log
node_trader -->|"starts"| node_backtest_engine
node_backtest_engine -->|"uses tokens"| node_history_instruments
node_history_instruments -->|"fetches instruments"| node_history_kite
node_backtest_engine -->|"fetches bars"| node_historical_data
node_historical_data -->|"requests history"| node_history_kite
node_backtest_engine -->|"retrieves yield"| node_dividend
node_backtest_engine -->|"invokes"| node_backtest_decision
node_backtest_decision -->|"calculates value"| node_backtest_pricing
node_backtest_decision -->|"estimates costs"| node_backtest_costs
node_backtest_decision -->|"updates position"| node_backtest_state
node_backtest_decision -->|"realizes P&amp;L"| node_backtest_risk
node_backtest_decision -->|"writes signals"| node_backtest_log

click node_live_engine "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_streaming "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_live_state "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_live_log "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_backtest_engine "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_historical_data "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_backtest_state "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_backtest_log "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_instruments "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_dividend "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_history_instruments "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_pricing "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_costs "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_decision "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_risk_pnl "https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py"
click node_backtest_pricing "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_backtest_costs "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_backtest_decision "https://github.com/periza0/cashcarrybot/blob/main/backTest.py"
click node_backtest_risk "https://github.com/periza0/cashcarrybot/blob/main/backTest.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_live_engine,node_streaming,node_live_state,node_live_log toneBlue
class node_backtest_engine,node_historical_data,node_backtest_state,node_backtest_log toneAmber
class node_pricing,node_costs,node_decision,node_risk_pnl,node_backtest_pricing,node_backtest_costs,node_backtest_decision,node_backtest_risk toneMint
class node_instruments,node_kite,node_dividend,node_screener,node_history_instruments,node_history_kite toneRose
class node_trader toneIndigo
```

## Components

### Live Trading

- [Live Engine](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Tick Stream](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Position State](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Live Signal Log](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`

### Backtesting

- [Backtest Engine](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Historical Bars](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Backtest State](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Backtest Signal Log](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`

### Arbitrage Strategy

- [Fair Value](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Cost Estimate](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Trade Decision](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Risk and P&L](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- [Fair Value](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Cost Estimate](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Trade Decision](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- [Risk and P&L](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`

### Data Integrations

- [Instrument Discovery](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- **Kite Connect**
- [Dividend Lookup](https://github.com/periza0/cashcarrybot/blob/main/CashAndCarry.py): `CashAndCarry.py`
- **Screener.in**
- [Backtest Instruments](https://github.com/periza0/cashcarrybot/blob/main/backTest.py): `backTest.py`
- **Kite Connect**

### Other components

- **Trader**

## Connections

- Trader → Live Engine: starts (evidence: `CashAndCarry.py`)
- Live Engine → Kite Connect: authenticates (evidence: `CashAndCarry.py`)
- Live Engine → Instrument Discovery: discovers (evidence: `CashAndCarry.py`)
- Instrument Discovery → Kite Connect: fetches instruments (evidence: `CashAndCarry.py`)
- Live Engine → Dividend Lookup: retrieves yield (evidence: `CashAndCarry.py`)
- Dividend Lookup → Screener.in: requests data (evidence: `CashAndCarry.py`)
- Live Engine → Tick Stream: starts stream (evidence: `CashAndCarry.py`)
- Tick Stream → Kite Connect: subscribes (evidence: `CashAndCarry.py`)
- Tick Stream → Fair Value: provides prices (evidence: `CashAndCarry.py`)
- Tick Stream → Trade Decision: invokes (evidence: `CashAndCarry.py`)
- Trade Decision → Fair Value: calculates value (evidence: `CashAndCarry.py`)
- Trade Decision → Cost Estimate: estimates costs (evidence: `CashAndCarry.py`)
- Trade Decision → Position State: updates position (evidence: `CashAndCarry.py`)
- Trade Decision → Risk and P&L: realizes P&L (evidence: `CashAndCarry.py`)
- Trade Decision → Live Signal Log: writes signals (evidence: `CashAndCarry.py`)
- Trader → Backtest Engine: starts (evidence: `backTest.py`)
- Backtest Engine → Backtest Instruments: uses tokens (evidence: `backTest.py`)
- Backtest Instruments → Kite Connect: fetches instruments (evidence: `backTest.py`)
- Backtest Engine → Historical Bars: fetches bars (evidence: `backTest.py`)
- Historical Bars → Kite Connect: requests history (evidence: `backTest.py`)
- Backtest Engine → Dividend Lookup: retrieves yield (evidence: `backTest.py`)
- Backtest Engine → Trade Decision: invokes (evidence: `backTest.py`)
- Trade Decision → Fair Value: calculates value (evidence: `backTest.py`)
- Trade Decision → Cost Estimate: estimates costs (evidence: `backTest.py`)
- Trade Decision → Backtest State: updates position (evidence: `backTest.py`)
- Trade Decision → Risk and P&L: realizes P&L (evidence: `backTest.py`)
- Trade Decision → Backtest Signal Log: writes signals (evidence: `backTest.py`)
