# olaxbt/ai-market-maker architecture

> Architecture diagram of the GitHub repository olaxbt/ai-market-maker, 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/olaxbt/ai-market-maker
- Repository: https://github.com/olaxbt/ai-market-maker

## Overview

AI Market Maker is a crypto hedge-fund-style trading stack with a web dashboard, paper-trading runtime, and research backtester. In the principal trading workflow, market data feeds specialist desks; their signals go through debate/arbitration and portfolio proposal, then Risk Guard can veto before execution. Separate dashboard/API surfaces support paper operations, backtests, and published results. The graph reflects README-described flow and source-index references; several subsystems are represented by their known entry modules because their implementations were not sampled.

Main entry points: [`src/main.py`](https://github.com/olaxbt/ai-market-maker/blob/main/src/main.py) (Trading workflow), [`src/backtest/engine.py`](https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/engine.py) (Backtest engine), [`src/api/backtest_routes.py`](https://github.com/olaxbt/ai-market-maker/blob/main/src/api/backtest_routes.py) (Backtest API), [`src/adapters/nexus_adapter.py`](https://github.com/olaxbt/ai-market-maker/blob/main/src/adapters/nexus_adapter.py) (Execution adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["Product surfaces"]
  node_dashboard["Web dashboard<br/>[page.tsx]"]
  node_api["Trading API<br/>[main.py]"]
  node_paper_control["Paper controls<br/>[engine_routes.py]"]
  node_backtest_api["Backtest API<br/>[backtest_routes.py]"]
  node_leaderboard["Results publishing<br/>[leadpage_routes.py]"]
end

subgraph group_trading["Trading workflow"]
  node_runtime_flow["Trading workflow<br/>[main.py]"]
  node_specialist_desks["Specialist desks"]
  node_desk_debate["Desk debate<br/>[desk_debate.py]"]
  node_arbitration["Signal arbitration"]
  node_portfolio["Portfolio proposal"]
  node_risk_guard{{"Risk Guard<br/>[risk_guard.py]"}}
end

subgraph group_data["Market and configuration"]
  node_market_data["Market data providers<br/>[provider.py]"]
  node_llm["LLM inference"]
  node_settings["Policy and settings<br/>[app_settings.py]"]
end

subgraph group_research["Backtest and results"]
  node_backtest_engine["Backtest engine<br/>[engine.py]"]
  node_perp_engine["Perpetual simulator<br/>[perp.py]"]
  node_historical_data["Historical data<br/>[registry.py]"]
end

subgraph group_runtime["Execution and records"]
  node_execution["Execution adapter<br/>[nexus_adapter.py]"]
  node_oms["Order management<br/>[oms.py]"]
  node_paper_account[("Paper account<br/>[paper_account.py]")]
  node_flow_log[("Trace and event log<br/>[flow_log.py]")]
  node_results_store[("Leaderboard storage<br/>[leadpage_db.py]")]
end

node_operator(("Trader / operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -.->|"requests"| node_api
node_operator -->|"runs"| node_runtime_flow
node_market_data -->|"feeds market data"| node_runtime_flow
node_runtime_flow -->|"runs desks"| node_specialist_desks
node_runtime_flow -->|"coordinates debate"| node_desk_debate
node_runtime_flow -->|"invokes arbitration"| node_arbitration
node_runtime_flow -->|"builds proposal"| node_portfolio
node_runtime_flow -->|"checks risk"| node_risk_guard
node_runtime_flow -->|"executes approved trade"| node_execution
node_specialist_desks -.->|"uses inference"| node_llm
node_settings -.->|"configures"| node_runtime_flow
node_operator -->|"controls paper loop"| node_paper_control
node_paper_control -->|"reads and resets"| node_paper_account
node_execution -->|"uses paper state"| node_paper_account
node_execution -->|"routes optionally"| node_oms
node_runtime_flow -->|"records events"| node_flow_log
node_operator -->|"starts research run"| node_backtest_api
node_backtest_api -->|"runs backtest"| node_backtest_engine
node_backtest_engine -->|"delegates simulation"| node_perp_engine
node_backtest_engine -.->|"loads bars"| node_historical_data
node_backtest_engine -->|"invokes workflow"| node_runtime_flow
node_backtest_api -.->|"publishes results"| node_leaderboard
node_leaderboard -->|"reads and writes"| node_results_store

click node_dashboard "https://github.com/olaxbt/ai-market-maker/blob/main/web/src/app/console/page.tsx"
click node_api "https://github.com/olaxbt/ai-market-maker/blob/main/src/api/main.py"
click node_paper_control "https://github.com/olaxbt/ai-market-maker/blob/main/src/api/engine_routes.py"
click node_backtest_api "https://github.com/olaxbt/ai-market-maker/blob/main/src/api/backtest_routes.py"
click node_leaderboard "https://github.com/olaxbt/ai-market-maker/blob/main/src/api/leadpage_routes.py"
click node_runtime_flow "https://github.com/olaxbt/ai-market-maker/blob/main/src/main.py"
click node_specialist_desks "https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/technical_ta_engine.py"
click node_desk_debate "https://github.com/olaxbt/ai-market-maker/blob/main/src/workflow/desk_debate.py"
click node_arbitration "https://github.com/olaxbt/ai-market-maker/blob/main/src/workflow/weighted_arbitrator.py"
click node_portfolio "https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/portfolio_management.py"
click node_risk_guard "https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/governance/risk_guard.py"
click node_market_data "https://github.com/olaxbt/ai-market-maker/blob/main/src/nexus_data/provider.py"
click node_llm "https://github.com/olaxbt/ai-market-maker/blob/main/src/llm/agent_llm_client.py"
click node_settings "https://github.com/olaxbt/ai-market-maker/blob/main/src/config/app_settings.py"
click node_backtest_engine "https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/engine.py"
click node_perp_engine "https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/engines/perp.py"
click node_historical_data "https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/loaders/registry.py"
click node_execution "https://github.com/olaxbt/ai-market-maker/blob/main/src/adapters/nexus_adapter.py"
click node_oms "https://github.com/olaxbt/ai-market-maker/blob/main/src/oms/oms.py"
click node_paper_account "https://github.com/olaxbt/ai-market-maker/blob/main/src/paper_account.py"
click node_flow_log "https://github.com/olaxbt/ai-market-maker/blob/main/src/flow_log.py"
click node_results_store "https://github.com/olaxbt/ai-market-maker/blob/main/src/storage/leadpage_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_dashboard,node_api,node_paper_control,node_backtest_api,node_leaderboard toneBlue
class node_runtime_flow,node_specialist_desks,node_desk_debate,node_arbitration,node_portfolio,node_risk_guard toneAmber
class node_market_data,node_llm,node_settings toneMint
class node_backtest_engine,node_perp_engine,node_historical_data toneRose
class node_execution,node_oms,node_paper_account,node_flow_log,node_results_store,node_operator toneIndigo
```

## Components

### Product surfaces

- [Web dashboard](https://github.com/olaxbt/ai-market-maker/blob/main/web/src/app/console/page.tsx): `web/src/app/console/page.tsx`
- [Trading API](https://github.com/olaxbt/ai-market-maker/blob/main/src/api/main.py): `src/api/main.py`
- [Paper controls](https://github.com/olaxbt/ai-market-maker/blob/main/src/api/engine_routes.py): `src/api/engine_routes.py`
- [Backtest API](https://github.com/olaxbt/ai-market-maker/blob/main/src/api/backtest_routes.py): `src/api/backtest_routes.py`
- [Results publishing](https://github.com/olaxbt/ai-market-maker/blob/main/src/api/leadpage_routes.py): `src/api/leadpage_routes.py`

### Trading workflow

- [Trading workflow](https://github.com/olaxbt/ai-market-maker/blob/main/src/main.py): `src/main.py`
- [Specialist desks](https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/technical_ta_engine.py): `src/agents/technical_ta_engine.py`
- [Desk debate](https://github.com/olaxbt/ai-market-maker/blob/main/src/workflow/desk_debate.py): `src/workflow/desk_debate.py`
- [Signal arbitration](https://github.com/olaxbt/ai-market-maker/blob/main/src/workflow/weighted_arbitrator.py): `src/workflow/weighted_arbitrator.py`
- [Portfolio proposal](https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/portfolio_management.py): `src/agents/portfolio_management.py`
- [Risk Guard](https://github.com/olaxbt/ai-market-maker/blob/main/src/agents/governance/risk_guard.py): `src/agents/governance/risk_guard.py`

### Market and configuration

- [Market data providers](https://github.com/olaxbt/ai-market-maker/blob/main/src/nexus_data/provider.py): `src/nexus_data/provider.py`
- [LLM inference](https://github.com/olaxbt/ai-market-maker/blob/main/src/llm/agent_llm_client.py): `src/llm/agent_llm_client.py`
- [Policy and settings](https://github.com/olaxbt/ai-market-maker/blob/main/src/config/app_settings.py): `src/config/app_settings.py`

### Backtest and results

- [Backtest engine](https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/engine.py): `src/backtest/engine.py`
- [Perpetual simulator](https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/engines/perp.py): `src/backtest/engines/perp.py`
- [Historical data](https://github.com/olaxbt/ai-market-maker/blob/main/src/backtest/loaders/registry.py): `src/backtest/loaders/registry.py`

### Execution and records

- [Execution adapter](https://github.com/olaxbt/ai-market-maker/blob/main/src/adapters/nexus_adapter.py): `src/adapters/nexus_adapter.py`
- [Order management](https://github.com/olaxbt/ai-market-maker/blob/main/src/oms/oms.py): `src/oms/oms.py`
- [Paper account](https://github.com/olaxbt/ai-market-maker/blob/main/src/paper_account.py): `src/paper_account.py`
- [Trace and event log](https://github.com/olaxbt/ai-market-maker/blob/main/src/flow_log.py): `src/flow_log.py`
- [Leaderboard storage](https://github.com/olaxbt/ai-market-maker/blob/main/src/storage/leadpage_db.py): `src/storage/leadpage_db.py`

### Other components

- **Trader / operator**

## Connections

- Trader / operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → Trading API: requests
- Trader / operator → Trading workflow: runs (evidence: `README.md`)
- Market data providers → Trading workflow: feeds market data (evidence: `README.md`)
- Trading workflow → Specialist desks: runs desks (evidence: `src/main.py`)
- Trading workflow → Desk debate: coordinates debate (evidence: `README.md`)
- Trading workflow → Signal arbitration: invokes arbitration (evidence: `README.md`)
- Trading workflow → Portfolio proposal: builds proposal (evidence: `src/main.py`)
- Trading workflow → Risk Guard: checks risk (evidence: `README.md`)
- Trading workflow → Execution adapter: executes approved trade (evidence: `README.md`)
- Specialist desks → LLM inference: uses inference
- Policy and settings → Trading workflow: configures (evidence: `src/main.py`)
- Trader / operator → Paper controls: controls paper loop (evidence: `src/api/engine_routes.py`)
- Paper controls → Paper account: reads and resets (evidence: `src/api/engine_routes.py`)
- Execution adapter → Paper account: uses paper state (evidence: `src/adapters/nexus_adapter.py`)
- Execution adapter → Order management: routes optionally (evidence: `src/adapters/nexus_adapter.py`)
- Trading workflow → Trace and event log: records events (evidence: `src/flow_log.py`)
- Trader / operator → Backtest API: starts research run (evidence: `README.md`)
- Backtest API → Backtest engine: runs backtest (evidence: `src/api/backtest_routes.py`)
- Backtest engine → Perpetual simulator: delegates simulation (evidence: `src/backtest/engine.py`)
- Backtest engine → Historical data: loads bars
- Backtest engine → Trading workflow: invokes workflow (evidence: `src/backtest/engine.py`)
- Backtest API → Results publishing: publishes results
- Results publishing → Leaderboard storage: reads and writes (evidence: `src/api/leadpage_routes.py`)
