# cardosojoel/trade architecture

> Architecture diagram of the GitHub repository cardosojoel/trade, 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/cardosojoel/trade
- Repository: https://github.com/cardosojoel/trade

## Overview

Trade is a spot-Bitcoin trading system whose presently supported user workflow is collecting public Bybit candles and evaluating a strategy in a backtest. The engine turns strategy signals into orders through a mandatory risk guard, with simulated execution and required audit recording. The tree also contains session, paper-execution, and reporting/server components, but the README explicitly says paper and live trading are not available. Wiring for unsampled modules is omitted where the excerpts and index do not establish a caller relationship.

Main entry points: [`crates/trade-risk/src/guard.rs`](https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/guard.rs) (Risk guard), [`crates/trade-backtest/src/engine.rs`](https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/engine.rs) (Backtest engine), [`crates/trade-serve/src/app.rs`](https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/app.rs) (Reporting application), [`crates/trade-cli/src/main.rs`](https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/main.rs) (Trade CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["Trade CLI<br/>[main.rs]"]
  node_collect["Collection command<br/>[cmd_collect.rs]"]
  node_backtest_cmd["Backtest command<br/>[cmd_backtest.rs]"]
end

subgraph group_market["Market data"]
  node_bybit_client["Public Bybit client<br/>[client.rs]"]
  node_collector["Candle collector<br/>[collector.rs]"]
  node_market_source["Candle source<br/>[market_source.rs]"]
  node_candle_store[("Candle repository<br/>[candle_repo.rs]")]
end

subgraph group_trading["Trading runtime"]
  node_domain["Trading domain<br/>[types.rs]"]
  node_strategy["SMA strategy<br/>[sma_cross.rs]"]
  node_engine["Backtest engine<br/>[engine.rs]"]
  node_bt_executor["Simulated executor<br/>[executor.rs]"]
  node_bt_run["Backtest outcome<br/>[run.rs]"]
  node_risk_guard["Risk guard<br/>[guard.rs]"]
  node_risk_rules["Risk rules<br/>[rules.rs]"]
  node_kill_switch["Kill switch<br/>[kill_switch.rs]"]
end

subgraph group_persistence["Storage and audit"]
  node_audit["Audit events<br/>[audit.rs]"]
  node_runs[("Run repository<br/>[runs_repo.rs]")]
  node_db[("SQLite access<br/>[db.rs]")]
end

subgraph group_operations["Session and reporting"]
  node_session["Session loop<br/>[laco.rs]"]
  node_paper_executor["Paper executor<br/>[executor.rs]"]
  node_serve_app["Reporting application<br/>[app.rs]"]
  node_serve_queries["Run queries<br/>[consultas.rs]"]
  node_serve_responses["Report responses<br/>[respostas.rs]"]
end

node_user(("Operator"))

node_user -->|"runs commands"| node_cli
node_cli -.->|"dispatches collection"| node_collect
node_cli -.->|"dispatches backtest"| node_backtest_cmd
node_collect -->|"fetches candles"| node_bybit_client
node_collect -->|"stores history"| node_candle_store
node_backtest_cmd -->|"starts backtest"| node_engine
node_engine -->|"requests signals"| node_strategy
node_engine -->|"submits orders"| node_risk_guard
node_engine -->|"constructs executor"| node_bt_executor
node_risk_guard -->|"owns executor"| node_bt_executor
node_risk_guard -->|"evaluates limits"| node_risk_rules
node_risk_guard -->|"checks switch"| node_kill_switch
node_engine -->|"returns outcome"| node_bt_run
node_serve_app -->|"calls queries"| node_serve_queries
node_serve_app -->|"builds responses"| node_serve_responses
node_serve_app -->|"reads run data"| node_runs
node_runs -->|"uses SQLite"| node_db
node_session -.->|"dispatches orders"| node_risk_guard
node_risk_guard -.->|"may wrap executor"| node_paper_executor

click node_cli "https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/main.rs"
click node_collect "https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/cmd_collect.rs"
click node_backtest_cmd "https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/cmd_backtest.rs"
click node_bybit_client "https://github.com/cardosojoel/trade/blob/main/crates/trade-bybit/src/client.rs"
click node_collector "https://github.com/cardosojoel/trade/blob/main/crates/trade-bybit/src/collector.rs"
click node_market_source "https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/market_source.rs"
click node_candle_store "https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/candle_repo.rs"
click node_domain "https://github.com/cardosojoel/trade/blob/main/crates/trade-domain/src/types.rs"
click node_strategy "https://github.com/cardosojoel/trade/blob/main/crates/trade-strategy/src/sma_cross.rs"
click node_engine "https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/engine.rs"
click node_bt_executor "https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/executor.rs"
click node_bt_run "https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/run.rs"
click node_risk_guard "https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/guard.rs"
click node_risk_rules "https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/rules.rs"
click node_kill_switch "https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/kill_switch.rs"
click node_audit "https://github.com/cardosojoel/trade/blob/main/crates/trade-domain/src/audit.rs"
click node_runs "https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/runs_repo.rs"
click node_db "https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/db.rs"
click node_session "https://github.com/cardosojoel/trade/blob/main/crates/trade-session/src/laco.rs"
click node_paper_executor "https://github.com/cardosojoel/trade/blob/main/crates/trade-paper/src/executor.rs"
click node_serve_app "https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/app.rs"
click node_serve_queries "https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/consultas.rs"
click node_serve_responses "https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/respostas.rs"

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_collect,node_backtest_cmd toneBlue
class node_bybit_client,node_collector,node_market_source,node_candle_store toneAmber
class node_domain,node_strategy,node_engine,node_bt_executor,node_bt_run,node_risk_guard,node_risk_rules,node_kill_switch toneMint
class node_audit,node_runs,node_db toneRose
class node_session,node_paper_executor,node_serve_app,node_serve_queries,node_serve_responses,node_user toneIndigo
```

## Components

### User entry

- [Trade CLI](https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/main.rs): `crates/trade-cli/src/main.rs`
- [Collection command](https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/cmd_collect.rs): `crates/trade-cli/src/cmd_collect.rs`
- [Backtest command](https://github.com/cardosojoel/trade/blob/main/crates/trade-cli/src/cmd_backtest.rs): `crates/trade-cli/src/cmd_backtest.rs`

### Market data

- [Public Bybit client](https://github.com/cardosojoel/trade/blob/main/crates/trade-bybit/src/client.rs): `crates/trade-bybit/src/client.rs`
- [Candle collector](https://github.com/cardosojoel/trade/blob/main/crates/trade-bybit/src/collector.rs): `crates/trade-bybit/src/collector.rs`
- [Candle source](https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/market_source.rs): `crates/trade-storage/src/market_source.rs`
- [Candle repository](https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/candle_repo.rs): `crates/trade-storage/src/candle_repo.rs`

### Trading runtime

- [Trading domain](https://github.com/cardosojoel/trade/blob/main/crates/trade-domain/src/types.rs): `crates/trade-domain/src/types.rs`
- [SMA strategy](https://github.com/cardosojoel/trade/blob/main/crates/trade-strategy/src/sma_cross.rs): `crates/trade-strategy/src/sma_cross.rs`
- [Backtest engine](https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/engine.rs): `crates/trade-backtest/src/engine.rs`
- [Simulated executor](https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/executor.rs): `crates/trade-backtest/src/executor.rs`
- [Backtest outcome](https://github.com/cardosojoel/trade/blob/main/crates/trade-backtest/src/run.rs): `crates/trade-backtest/src/run.rs`
- [Risk guard](https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/guard.rs): `crates/trade-risk/src/guard.rs`
- [Risk rules](https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/rules.rs): `crates/trade-risk/src/rules.rs`
- [Kill switch](https://github.com/cardosojoel/trade/blob/main/crates/trade-risk/src/kill_switch.rs): `crates/trade-risk/src/kill_switch.rs`

### Storage and audit

- [Audit events](https://github.com/cardosojoel/trade/blob/main/crates/trade-domain/src/audit.rs): `crates/trade-domain/src/audit.rs`
- [Run repository](https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/runs_repo.rs): `crates/trade-storage/src/runs_repo.rs`
- [SQLite access](https://github.com/cardosojoel/trade/blob/main/crates/trade-storage/src/db.rs): `crates/trade-storage/src/db.rs`

### Session and reporting

- [Session loop](https://github.com/cardosojoel/trade/blob/main/crates/trade-session/src/laco.rs): `crates/trade-session/src/laco.rs`
- [Paper executor](https://github.com/cardosojoel/trade/blob/main/crates/trade-paper/src/executor.rs): `crates/trade-paper/src/executor.rs`
- [Reporting application](https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/app.rs): `crates/trade-serve/src/app.rs`
- [Run queries](https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/consultas.rs): `crates/trade-serve/src/consultas.rs`
- [Report responses](https://github.com/cardosojoel/trade/blob/main/crates/trade-serve/src/respostas.rs): `crates/trade-serve/src/respostas.rs`

### Other components

- **Operator**

## Connections

- Operator → Trade CLI: runs commands (evidence: `README.md`)
- Trade CLI → Collection command: dispatches collection
- Trade CLI → Backtest command: dispatches backtest
- Collection command → Public Bybit client: fetches candles (evidence: `README.md`)
- Collection command → Candle repository: stores history (evidence: `README.md`)
- Backtest command → Backtest engine: starts backtest (evidence: `README.md`)
- Backtest engine → SMA strategy: requests signals (evidence: `README.md`)
- Backtest engine → Risk guard: submits orders (evidence: `crates/trade-backtest/src/engine.rs`)
- Backtest engine → Simulated executor: constructs executor (evidence: `crates/trade-backtest/src/engine.rs`)
- Risk guard → Simulated executor: owns executor (evidence: `README.md`)
- Risk guard → Risk rules: evaluates limits (evidence: `crates/trade-risk/src/guard.rs`)
- Risk guard → Kill switch: checks switch (evidence: `crates/trade-risk/src/guard.rs`)
- Backtest engine → Backtest outcome: returns outcome (evidence: `crates/trade-backtest/src/engine.rs`)
- Reporting application → Run queries: calls queries (evidence: `crates/trade-serve/src/app.rs`)
- Reporting application → Report responses: builds responses (evidence: `crates/trade-serve/src/app.rs`)
- Reporting application → Run repository: reads run data (evidence: `crates/trade-serve/src/app.rs`)
- Run repository → SQLite access: uses SQLite (evidence: `crates/trade-storage/src/runs_repo.rs`)
- Session loop → Risk guard: dispatches orders
- Risk guard → Paper executor: may wrap executor
