# jaq1b/alpaca_trader architecture

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

- Interactive diagram: https://gitdiagram.com/jaq1b/alpaca_trader
- Repository: https://github.com/jaq1b/alpaca_trader

## Overview

alpaca_trader runs a risk-first Alpaca trading workflow: the CLI configures and dispatches commands; live trading reconciles the broker’s open positions with a SQLite ledger, scans market data, evaluates signals, sizes orders, and manages stops. Separate commands replay historical bars, summarize performance, and resample backtest trades with Monte Carlo. The map retains documented capabilities whose implementation excerpts were not available; those links are omitted where a caller or data flow cannot be evidenced.

Main entry points: [`tradingbot/cli.py`](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/cli.py) (Command router), [`tradingbot/bot.py`](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/bot.py) (Trading loop), [`tradingbot/broker.py`](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/broker.py) (Alpaca client), [`tradingbot/backtest.py`](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/backtest.py) (Historical replay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_main["Python entry<br/>[main.py]"]
  node_cli["Command router<br/>[cli.py]"]
end

subgraph group_trading["Live trading"]
  node_bot["Trading loop<br/>[bot.py]"]
  node_broker["Alpaca client<br/>[broker.py]"]
  node_strategy["Signal strategy<br/>[strategy.py]"]
  node_memory[("Trade ledger<br/>[memory.py]")]
end

subgraph group_analysis["Replay and analysis"]
  node_backtest["Historical replay<br/>[backtest.py]"]
  node_snapshots["Bar snapshots<br/>[snapshots.py]"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_montecarlo["Monte Carlo<br/>[montecarlo.py]"]
end

subgraph group_shared["Shared domain services"]
  node_config["Configuration<br/>[config.py]"]
  node_sizing["Risk and stops<br/>[sizing.py]"]
  node_models["Trade and orders<br/>[models.py]"]
  node_market["Market hours<br/>[market_hours.py]"]
  node_universe["Symbol universe<br/>[universe.py]"]
  node_display["Trading display<br/>[display.py]"]
  node_indicators["Technical indicators<br/>[indicators.py]"]
end

node_user(("Operator"))
node_alpaca["Alpaca services"]

node_user -->|"runs commands"| node_main
node_main -->|"delegates to"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts trading"| node_bot
node_cli -->|"builds client"| node_broker
node_cli -->|"runs replay"| node_backtest
node_cli -->|"requests report"| node_metrics
node_cli -->|"runs resampling"| node_montecarlo
node_cli -->|"formats output"| node_display
node_cli -->|"checks session"| node_market
node_bot -->|"reads positions"| node_broker
node_bot -->|"sends orders"| node_broker
node_bot -->|"reconciles ledger"| node_memory
node_bot -->|"evaluates signals"| node_strategy
node_bot -->|"sizes positions"| node_sizing
node_bot -->|"checks session"| node_market
node_bot -->|"selects symbols"| node_universe
node_broker -->|"requests data and trades"| node_alpaca
node_broker -->|"uses order models"| node_models
node_market -->|"queries calendar"| node_broker
node_memory -->|"builds trade records"| node_models
node_strategy -->|"computes signals"| node_indicators
node_strategy -->|"checks recent results"| node_memory
node_backtest -.->|"downloads bars"| node_broker
node_backtest -->|"replays decisions"| node_strategy
node_backtest -->|"sizes replay trades"| node_sizing
node_backtest -->|"uses bar snapshots"| node_snapshots
node_backtest -->|"uses symbol set"| node_universe
node_snapshots -->|"computes features"| node_indicators
node_metrics -->|"reads ledger"| node_memory
node_metrics -->|"reads portfolio history"| node_broker
node_metrics -->|"uses trade records"| node_models
node_montecarlo -->|"resamples replay trades"| node_backtest

click node_main "https://github.com/jaq1b/alpaca_trader/blob/main/main.py"
click node_cli "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/cli.py"
click node_config "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/config.py"
click node_bot "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/bot.py"
click node_broker "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/broker.py"
click node_strategy "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/strategy.py"
click node_sizing "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/sizing.py"
click node_memory "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/memory.py"
click node_models "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/models.py"
click node_market "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/market_hours.py"
click node_universe "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/universe.py"
click node_display "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/display.py"
click node_backtest "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/backtest.py"
click node_snapshots "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/snapshots.py"
click node_indicators "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/indicators.py"
click node_metrics "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/metrics.py"
click node_montecarlo "https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/montecarlo.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_main,node_cli toneBlue
class node_bot,node_broker,node_strategy,node_memory toneAmber
class node_backtest,node_snapshots,node_metrics,node_montecarlo toneMint
class node_config,node_sizing,node_models,node_market,node_universe,node_display,node_indicators toneRose
class node_user,node_alpaca toneIndigo
```

## Components

### Command entry

- [Python entry](https://github.com/jaq1b/alpaca_trader/blob/main/main.py): `main.py`
- [Command router](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/cli.py): `tradingbot/cli.py`

### Live trading

- [Trading loop](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/bot.py): `tradingbot/bot.py`
- [Alpaca client](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/broker.py): `tradingbot/broker.py`
- [Signal strategy](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/strategy.py): `tradingbot/strategy.py`
- [Trade ledger](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/memory.py): `tradingbot/memory.py`

### Replay and analysis

- [Historical replay](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/backtest.py): `tradingbot/backtest.py`
- [Bar snapshots](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/snapshots.py): `tradingbot/snapshots.py`
- [Performance metrics](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/metrics.py): `tradingbot/metrics.py`
- [Monte Carlo](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/montecarlo.py): `tradingbot/montecarlo.py`

### Shared domain services

- [Configuration](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/config.py): `tradingbot/config.py`
- [Risk and stops](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/sizing.py): `tradingbot/sizing.py`
- [Trade and orders](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/models.py): `tradingbot/models.py`
- [Market hours](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/market_hours.py): `tradingbot/market_hours.py`
- [Symbol universe](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/universe.py): `tradingbot/universe.py`
- [Trading display](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/display.py): `tradingbot/display.py`
- [Technical indicators](https://github.com/jaq1b/alpaca_trader/blob/main/tradingbot/indicators.py): `tradingbot/indicators.py`

### Other components

- **Operator**
- **Alpaca services**

## Connections

- Operator → Python entry: runs commands (evidence: `README.md`)
- Python entry → Command router: delegates to (evidence: `main.py`)
- Command router → Configuration: loads settings (evidence: `tradingbot/cli.py`)
- Command router → Trading loop: starts trading (evidence: `tradingbot/cli.py`)
- Command router → Alpaca client: builds client (evidence: `tradingbot/cli.py`)
- Command router → Historical replay: runs replay (evidence: `tradingbot/cli.py`)
- Command router → Performance metrics: requests report (evidence: `README.md`)
- Command router → Monte Carlo: runs resampling (evidence: `README.md`)
- Command router → Trading display: formats output (evidence: `tradingbot/cli.py`)
- Command router → Market hours: checks session (evidence: `tradingbot/cli.py`)
- Trading loop → Alpaca client: reads positions (evidence: `tradingbot/bot.py`)
- Trading loop → Alpaca client: sends orders (evidence: `README.md`)
- Trading loop → Trade ledger: reconciles ledger (evidence: `README.md`)
- Trading loop → Signal strategy: evaluates signals (evidence: `tradingbot/bot.py`)
- Trading loop → Risk and stops: sizes positions (evidence: `tradingbot/bot.py`)
- Trading loop → Market hours: checks session (evidence: `tradingbot/bot.py`)
- Trading loop → Symbol universe: selects symbols (evidence: `tradingbot/bot.py`)
- Alpaca client → Alpaca services: requests data and trades (evidence: `README.md`)
- Alpaca client → Trade and orders: uses order models (evidence: `tradingbot/broker.py`)
- Market hours → Alpaca client: queries calendar (evidence: `tradingbot/market_hours.py`)
- Trade ledger → Trade and orders: builds trade records (evidence: `tradingbot/memory.py`)
- Signal strategy → Technical indicators: computes signals (evidence: `tradingbot/strategy.py`)
- Signal strategy → Trade ledger: checks recent results (evidence: `tradingbot/strategy.py`)
- Historical replay → Alpaca client: downloads bars
- Historical replay → Signal strategy: replays decisions (evidence: `tradingbot/backtest.py`)
- Historical replay → Risk and stops: sizes replay trades (evidence: `tradingbot/backtest.py`)
- Historical replay → Bar snapshots: uses bar snapshots (evidence: `tradingbot/backtest.py`)
- Historical replay → Symbol universe: uses symbol set (evidence: `tradingbot/backtest.py`)
- Bar snapshots → Technical indicators: computes features (evidence: `tradingbot/snapshots.py`)
- Performance metrics → Trade ledger: reads ledger (evidence: `tradingbot/metrics.py`)
- Performance metrics → Alpaca client: reads portfolio history (evidence: `tradingbot/metrics.py`)
- Performance metrics → Trade and orders: uses trade records (evidence: `tradingbot/metrics.py`)
- Monte Carlo → Historical replay: resamples replay trades (evidence: `README.md`)
