# brndnmtthws/thetagang architecture

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

- Interactive diagram: https://gitdiagram.com/brndnmtthws/thetagang
- Repository: https://github.com/brndnmtthws/thetagang

## Overview

ThetaGang is a configurable IBKR portfolio-trading bot. A configured run enters through the CLI, then coordinates portfolio stages that plan option, share-rebalancing, hedging, and post-trade actions; orders are supervised against the broker. The README also documents regime-aware gates, cash management, accounting, external decision providers, and exchange-hours enforcement. The excerpts show several engine dependencies and broker interactions, but not all stage wiring, so uncertain links are omitted; some documented capabilities are represented at their best-supported module path.

Main entry points: [`thetagang/portfolio_manager.py`](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/portfolio_manager.py) (Portfolio manager), [`thetagang/strategies/post_engine.py`](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/post_engine.py) (Post management), [`thetagang/ibkr.py`](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/ibkr.py) (IBKR adapter), [`thetagang/thetagang.py`](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/thetagang.py) (Startup runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run and configuration"]
  node_cli["CLI<br/>[main.py]"]
  node_startup["Startup runner<br/>[thetagang.py]"]
  node_migration["Config migration"]
  node_config["Config models<br/>[config_models.py]"]
end

subgraph group_planning["Portfolio planning"]
  node_manager["Portfolio manager"]
  node_accounting["Account accounting<br/>[accounting.py]"]
  node_options["Wheel options<br/>[options_engine.py]"]
  node_equity["Share rebalance<br/>[equity_engine.py]"]
  node_regime["Regime rebalance<br/>[regime_engine.py]"]
  node_post["Post management<br/>[post_engine.py]"]
  node_tailhedge["Tail hedge"]
  node_tailharvest["Tail harvest policy"]
  node_hours["Exchange hours<br/>[exchange_hours.py]"]
end

subgraph group_broker["Broker and orders"]
  node_ibkr["IBKR adapter<br/>[ibkr.py]"]
  node_scanner["Option scanner<br/>[options.py]"]
  node_orderops["Order operations"]
  node_orders["Order records<br/>[orders.py]"]
  node_execution["Order supervision<br/>[order_execution.py]"]
end

subgraph group_state["State and decisions"]
  node_external["Decision providers"]
  node_store[("SQLite state<br/>[db.py]")]
end

node_operator(("Operator"))
node_broker_service(("IBKR service"))

node_operator -->|"starts run"| node_cli
node_cli -->|"invokes"| node_startup
node_startup -->|"checks schema"| node_migration
node_startup -->|"loads settings"| node_config
node_startup -->|"starts portfolio"| node_manager
node_manager -->|"summarizes account"| node_accounting
node_manager -->|"runs strategy"| node_options
node_manager -->|"runs strategy"| node_equity
node_manager -->|"plans rebalance"| node_regime
node_manager -->|"runs post stage"| node_post
node_post -->|"manages hedge"| node_tailhedge
node_regime -->|"uses policy"| node_tailharvest
node_manager -.->|"requests decisions"| node_external
node_manager -->|"checks session"| node_hours
node_options -->|"requests market data"| node_ibkr
node_options -->|"finds contracts"| node_scanner
node_equity -->|"requests quotes"| node_ibkr
node_equity -->|"creates orders"| node_orderops
node_post -->|"requests market data"| node_ibkr
node_post -->|"finds contracts"| node_scanner
node_post -->|"creates orders"| node_orderops
node_tailhedge -->|"reads/writes state"| node_store
node_manager -->|"tracks orders"| node_orders
node_orderops -->|"records orders"| node_orders
node_execution -->|"supervises trades"| node_ibkr
node_execution -->|"records events"| node_store
node_ibkr -->|"connects"| node_broker_service

click node_cli "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/main.py"
click node_startup "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/thetagang.py"
click node_migration "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/config_migration/startup_migration.py"
click node_config "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/config_models.py"
click node_manager "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/portfolio_manager.py"
click node_accounting "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/accounting.py"
click node_options "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/options_engine.py"
click node_equity "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/equity_engine.py"
click node_regime "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/regime_engine.py"
click node_post "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/post_engine.py"
click node_tailhedge "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/tail_hedge_engine.py"
click node_tailharvest "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/tail_harvest_policy.py"
click node_external "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/external_decisions.py"
click node_hours "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/exchange_hours.py"
click node_ibkr "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/ibkr.py"
click node_scanner "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/options.py"
click node_orderops "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/trading_operations.py"
click node_orders "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/orders.py"
click node_execution "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/order_execution.py"
click node_store "https://github.com/brndnmtthws/thetagang/blob/main/thetagang/db.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_cli,node_startup,node_migration,node_config toneBlue
class node_manager,node_accounting,node_options,node_equity,node_regime,node_post,node_tailhedge,node_tailharvest,node_hours toneAmber
class node_ibkr,node_scanner,node_orderops,node_orders,node_execution toneMint
class node_external,node_store toneRose
class node_operator,node_broker_service toneIndigo
```

## Components

### Run and configuration

- [CLI](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/main.py): `thetagang/main.py`
- [Startup runner](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/thetagang.py): `thetagang/thetagang.py`
- [Config migration](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/config_migration/startup_migration.py): `thetagang/config_migration/startup_migration.py`
- [Config models](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/config_models.py): `thetagang/config_models.py`

### Portfolio planning

- [Portfolio manager](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/portfolio_manager.py): `thetagang/portfolio_manager.py`
- [Account accounting](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/accounting.py): `thetagang/accounting.py`
- [Wheel options](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/options_engine.py): `thetagang/strategies/options_engine.py`
- [Share rebalance](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/equity_engine.py): `thetagang/strategies/equity_engine.py`
- [Regime rebalance](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/regime_engine.py): `thetagang/strategies/regime_engine.py`
- [Post management](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/post_engine.py): `thetagang/strategies/post_engine.py`
- [Tail hedge](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/tail_hedge_engine.py): `thetagang/strategies/tail_hedge_engine.py`
- [Tail harvest policy](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/strategies/tail_harvest_policy.py): `thetagang/strategies/tail_harvest_policy.py`
- [Exchange hours](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/exchange_hours.py): `thetagang/exchange_hours.py`

### Broker and orders

- [IBKR adapter](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/ibkr.py): `thetagang/ibkr.py`
- [Option scanner](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/options.py): `thetagang/options.py`
- [Order operations](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/trading_operations.py): `thetagang/trading_operations.py`
- [Order records](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/orders.py): `thetagang/orders.py`
- [Order supervision](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/order_execution.py): `thetagang/order_execution.py`

### State and decisions

- [Decision providers](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/external_decisions.py): `thetagang/external_decisions.py`
- [SQLite state](https://github.com/brndnmtthws/thetagang/blob/main/thetagang/db.py): `thetagang/db.py`

### Other components

- **Operator**
- **IBKR service**

## Connections

- Operator → CLI: starts run
- CLI → Startup runner: invokes
- Startup runner → Config migration: checks schema
- Startup runner → Config models: loads settings
- Startup runner → Portfolio manager: starts portfolio
- Portfolio manager → Account accounting: summarizes account
- Portfolio manager → Wheel options: runs strategy
- Portfolio manager → Share rebalance: runs strategy
- Portfolio manager → Regime rebalance: plans rebalance
- Portfolio manager → Post management: runs post stage
- Post management → Tail hedge: manages hedge
- Regime rebalance → Tail harvest policy: uses policy
- Portfolio manager → Decision providers: requests decisions
- Portfolio manager → Exchange hours: checks session
- Wheel options → IBKR adapter: requests market data
- Wheel options → Option scanner: finds contracts
- Share rebalance → IBKR adapter: requests quotes
- Share rebalance → Order operations: creates orders
- Post management → IBKR adapter: requests market data
- Post management → Option scanner: finds contracts
- Post management → Order operations: creates orders
- Tail hedge → SQLite state: reads/writes state
- Portfolio manager → Order records: tracks orders
- Order operations → Order records: records orders
- Order supervision → IBKR adapter: supervises trades
- Order supervision → SQLite state: records events
- IBKR adapter → IBKR service: connects