# idanya/algo-trader architecture

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

- Interactive diagram: https://gitdiagram.com/idanya/algo-trader
- Repository: https://github.com/idanya/algo-trader

## Overview

algo-trader is a Python strategy builder, historical backtester, and partially implemented real-time trader. Its principal workflow reads market candles, passes them through configurable processors and per-candle strategies, and can persist results or dispatch signals; pipeline terminators run after source exhaustion. The README documents historical Yahoo/Binance loading, real-time Binance input, technical indicators, and optional Interactive Brokers support. The pipeline execution and sink calls are shown in excerpts; several feature branches are documented but their runtime wiring is unsampled, so those links are omitted rather than inferred.

Main entry points: [`src/algotrader/pipeline/pipeline.py`](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/pipeline.py) (Pipeline), [`src/algotrader/pipeline/processors`](https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/processors) (Candle Processors), [`libs/ib_client/ibapi/client.py`](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/client.py) (IB API Client), [`src/algotrader/cli/pipeline.py`](https://github.com/idanya/algo-trader/blob/main/src/algotrader/cli/pipeline.py) (Pipeline Loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market Data"]
  node_source["Candle Sources"]
  node_market_providers["Market Providers"]
  node_candle["Candle Model<br/>[candle.py]"]
end

subgraph group_pipeline["Pipeline Runtime"]
  node_cli["CLI<br/>[main.py]"]
  node_pipeline_loader["Pipeline Loading<br/>[pipeline.py]"]
  node_pipeline["Pipeline<br/>[pipeline.py]"]
  node_runner["Pipeline Runner<br/>[runner.py]"]
  node_processors["Candle Processors"]
  node_context["Shared Context<br/>[shared_context.py]"]
  node_technicals["Technical Analysis<br/>[technicals.py]"]
  node_calculation["Indicator Calculations<br/>[technicals.py]"]
  node_terminator["Pipeline Terminators"]
end

subgraph group_trading["Strategy Trading"]
  node_strategy_processor["Strategy Processor<br/>[strategy.py]"]
  node_strategies["Trading Strategies"]
  node_signal["Strategy Signals<br/>[strategy_signal.py]"]
  node_executor["Signal Executor"]
end

subgraph group_ib["IB Integration"]
  node_ib_connector["IB Connector"]
  node_ib_client["IB API Client<br/>[client.py]"]
  node_ib_protocol["IB Protocol Models<br/>[common.py]"]
  node_ib_decoder["IB Message Decoder<br/>[decoder.py]"]
  node_ib_wrapper["IB Response Wrapper<br/>[wrapper.py]"]
  node_ib_order["IB Order Model<br/>[order.py]"]
end

subgraph group_state["Persistence"]
  node_storage_sink["Storage Sink"]
  node_storage_provider["Storage Provider"]
  node_mongodb[("MongoDB Storage<br/>[mongodb_storage.py]")]
  node_serialization["Serialization<br/>[store.py]"]
end

node_user(("Pipeline User"))

node_user -->|"runs"| node_cli
node_cli -->|"routes to"| node_pipeline_loader
node_pipeline_loader -->|"loads"| node_pipeline
node_pipeline_loader -->|"runs via"| node_runner
node_runner -->|"runs"| node_pipeline
node_pipeline -->|"reads"| node_source
node_pipeline -->|"processes candles"| node_processors
node_pipeline -->|"terminates with"| node_terminator
node_source -->|"produces"| node_candle
node_market_providers -.->|"supplies data"| node_source
node_processors -->|"shares state"| node_context
node_processors -.->|"includes"| node_technicals
node_technicals -->|"calculates with"| node_calculation
node_processors -.->|"includes"| node_strategy_processor
node_strategy_processor -->|"executes"| node_strategies
node_strategies -->|"dispatches"| node_signal
node_strategy_processor -->|"passes signals"| node_executor
node_storage_sink -->|"saves candles"| node_storage_provider
node_storage_provider -.->|"implemented by"| node_mongodb
node_pipeline -->|"serializes via"| node_serialization
node_ib_connector -.->|"uses"| node_ib_client
node_ib_client -->|"encodes messages"| node_ib_protocol
node_ib_client -->|"decodes responses"| node_ib_decoder
node_ib_decoder -->|"dispatches callbacks"| node_ib_wrapper
node_ib_client -->|"encodes orders"| node_ib_order
node_ib_decoder -->|"decodes orders"| node_ib_order

click node_cli "https://github.com/idanya/algo-trader/blob/main/src/algotrader/cli/main.py"
click node_pipeline_loader "https://github.com/idanya/algo-trader/blob/main/src/algotrader/cli/pipeline.py"
click node_pipeline "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/pipeline.py"
click node_runner "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/runner.py"
click node_source "https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/sources"
click node_market_providers "https://github.com/idanya/algo-trader/tree/main/src/algotrader/market"
click node_candle "https://github.com/idanya/algo-trader/blob/main/src/algotrader/entities/candle.py"
click node_processors "https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/processors"
click node_context "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/shared_context.py"
click node_technicals "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/technicals.py"
click node_calculation "https://github.com/idanya/algo-trader/blob/main/src/algotrader/calc/technicals.py"
click node_strategy_processor "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/strategy.py"
click node_strategies "https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/strategies"
click node_signal "https://github.com/idanya/algo-trader/blob/main/src/algotrader/entities/strategy_signal.py"
click node_executor "https://github.com/idanya/algo-trader/blob/main/src/algotrader/trade/signals_executor.py"
click node_terminator "https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/terminators"
click node_storage_sink "https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/storage_provider_sink.py"
click node_storage_provider "https://github.com/idanya/algo-trader/blob/main/src/algotrader/storage/storage_provider.py"
click node_mongodb "https://github.com/idanya/algo-trader/blob/main/src/algotrader/storage/mongodb_storage.py"
click node_serialization "https://github.com/idanya/algo-trader/blob/main/src/algotrader/serialization/store.py"
click node_ib_connector "https://github.com/idanya/algo-trader/blob/main/src/algotrader/providers/ib/interactive_brokers_connector.py"
click node_ib_client "https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/client.py"
click node_ib_protocol "https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/common.py"
click node_ib_decoder "https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/decoder.py"
click node_ib_wrapper "https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/wrapper.py"
click node_ib_order "https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/order.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_source,node_market_providers,node_candle,node_user toneBlue
class node_cli,node_pipeline_loader,node_pipeline,node_runner,node_processors,node_context,node_technicals,node_calculation,node_terminator toneAmber
class node_strategy_processor,node_strategies,node_signal,node_executor toneMint
class node_ib_connector,node_ib_client,node_ib_protocol,node_ib_decoder,node_ib_wrapper,node_ib_order toneRose
class node_storage_sink,node_storage_provider,node_mongodb,node_serialization toneIndigo
```

## Components

### Market Data

- [Candle Sources](https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/sources): `src/algotrader/pipeline/sources`
- [Market Providers](https://github.com/idanya/algo-trader/tree/main/src/algotrader/market): `src/algotrader/market`
- [Candle Model](https://github.com/idanya/algo-trader/blob/main/src/algotrader/entities/candle.py): `src/algotrader/entities/candle.py`

### Pipeline Runtime

- [CLI](https://github.com/idanya/algo-trader/blob/main/src/algotrader/cli/main.py): `src/algotrader/cli/main.py`
- [Pipeline Loading](https://github.com/idanya/algo-trader/blob/main/src/algotrader/cli/pipeline.py): `src/algotrader/cli/pipeline.py`
- [Pipeline](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/pipeline.py): `src/algotrader/pipeline/pipeline.py`
- [Pipeline Runner](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/runner.py): `src/algotrader/pipeline/runner.py`
- [Candle Processors](https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/processors): `src/algotrader/pipeline/processors`
- [Shared Context](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/shared_context.py): `src/algotrader/pipeline/shared_context.py`
- [Technical Analysis](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/technicals.py): `src/algotrader/pipeline/processors/technicals.py`
- [Indicator Calculations](https://github.com/idanya/algo-trader/blob/main/src/algotrader/calc/technicals.py): `src/algotrader/calc/technicals.py`
- [Pipeline Terminators](https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/terminators): `src/algotrader/pipeline/terminators`

### Strategy Trading

- [Strategy Processor](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/strategy.py): `src/algotrader/pipeline/processors/strategy.py`
- [Trading Strategies](https://github.com/idanya/algo-trader/tree/main/src/algotrader/pipeline/strategies): `src/algotrader/pipeline/strategies`
- [Strategy Signals](https://github.com/idanya/algo-trader/blob/main/src/algotrader/entities/strategy_signal.py): `src/algotrader/entities/strategy_signal.py`
- [Signal Executor](https://github.com/idanya/algo-trader/blob/main/src/algotrader/trade/signals_executor.py): `src/algotrader/trade/signals_executor.py`

### IB Integration

- [IB Connector](https://github.com/idanya/algo-trader/blob/main/src/algotrader/providers/ib/interactive_brokers_connector.py): `src/algotrader/providers/ib/interactive_brokers_connector.py`
- [IB API Client](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/client.py): `libs/ib_client/ibapi/client.py`
- [IB Protocol Models](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/common.py): `libs/ib_client/ibapi/common.py`
- [IB Message Decoder](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/decoder.py): `libs/ib_client/ibapi/decoder.py`
- [IB Response Wrapper](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/wrapper.py): `libs/ib_client/ibapi/wrapper.py`
- [IB Order Model](https://github.com/idanya/algo-trader/blob/main/libs/ib_client/ibapi/order.py): `libs/ib_client/ibapi/order.py`

### Persistence

- [Storage Sink](https://github.com/idanya/algo-trader/blob/main/src/algotrader/pipeline/processors/storage_provider_sink.py): `src/algotrader/pipeline/processors/storage_provider_sink.py`
- [Storage Provider](https://github.com/idanya/algo-trader/blob/main/src/algotrader/storage/storage_provider.py): `src/algotrader/storage/storage_provider.py`
- [MongoDB Storage](https://github.com/idanya/algo-trader/blob/main/src/algotrader/storage/mongodb_storage.py): `src/algotrader/storage/mongodb_storage.py`
- [Serialization](https://github.com/idanya/algo-trader/blob/main/src/algotrader/serialization/store.py): `src/algotrader/serialization/store.py`

### Other components

- **Pipeline User**

## Connections

- Pipeline User → CLI: runs (evidence: `src/algotrader/cli/main.py`)
- CLI → Pipeline Loading: routes to (evidence: `src/algotrader/cli/main.py`)
- Pipeline Loading → Pipeline: loads (evidence: `src/algotrader/cli/pipeline.py`)
- Pipeline Loading → Pipeline Runner: runs via (evidence: `src/algotrader/cli/pipeline.py`)
- Pipeline Runner → Pipeline: runs
- Pipeline → Candle Sources: reads (evidence: `src/algotrader/pipeline/pipeline.py`)
- Pipeline → Candle Processors: processes candles (evidence: `src/algotrader/pipeline/pipeline.py`)
- Pipeline → Pipeline Terminators: terminates with (evidence: `src/algotrader/pipeline/pipeline.py`)
- Candle Sources → Candle Model: produces
- Market Providers → Candle Sources: supplies data
- Candle Processors → Shared Context: shares state (evidence: `src/algotrader/pipeline/processors/storage_provider_sink.py`)
- Candle Processors → Technical Analysis: includes
- Technical Analysis → Indicator Calculations: calculates with (evidence: `src/algotrader/calc/technicals.py`)
- Candle Processors → Strategy Processor: includes
- Strategy Processor → Trading Strategies: executes
- Trading Strategies → Strategy Signals: dispatches
- Strategy Processor → Signal Executor: passes signals
- Storage Sink → Storage Provider: saves candles (evidence: `src/algotrader/pipeline/processors/storage_provider_sink.py`)
- Storage Provider → MongoDB Storage: implemented by (evidence: `src/algotrader/storage/mongodb_storage.py`)
- Pipeline → Serialization: serializes via (evidence: `src/algotrader/pipeline/pipeline.py`)
- IB Connector → IB API Client: uses
- IB API Client → IB Protocol Models: encodes messages (evidence: `libs/ib_client/ibapi/client.py`)
- IB API Client → IB Message Decoder: decodes responses (evidence: `libs/ib_client/ibapi/client.py`)
- IB Message Decoder → IB Response Wrapper: dispatches callbacks (evidence: `libs/ib_client/ibapi/decoder.py`)
- IB API Client → IB Order Model: encodes orders (evidence: `libs/ib_client/ibapi/client.py`)
- IB Message Decoder → IB Order Model: decodes orders (evidence: `libs/ib_client/ibapi/decoder.py`)
