# andydoc/prediction-trading architecture

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

- Interactive diagram: https://gitdiagram.com/andydoc/prediction-trading
- Repository: https://github.com/andydoc/prediction-trading

## Overview

##### Project type & purpose (from file tree + README)
This is a **Python-based prediction-market trading system** that appears to support **multiple platforms/strategies** and at least two operating modes:
- **Live trading** (`live_trading.py`)
- **Paper trading** (`paper_trading.py`)

The architecture is explicitly **layered/pipelined**:
- `layer1_market_data/` → ingest/normalize market data
- `layer2_constraint_detection/` → validate feasibility / detect constraints
- `layer3_arbitrage_math/` → compute opportunities / sizing via an arbitrage engine
- Runners (`layer1_runner.py`, `layer2_runner.py`, `layer3_runner.py`, `layer4_runner.py`) → orchestration across layers

There is also clear infrastructure for:
- **WebSocket connectivity** (`websocket_manager.py`, `test_clob_connect.py`)
- **Execution control & coordination** (`execution_control.py`, `execution_control_client.py`)
- **Trading engine orchestration** (`trading_engine.py`, `main.py`)
- **Dashboard/monitoring server** (`dashboard_server.py`)
- **Config-driven runtime** (`config/config.yaml`)
- **Ops scripts** for starting/stopping, VPS setup, health checks, etc. (`scripts/`, `start_all.sh`, `setup.ps1`)

##### Trading Orchestrator
- `main.py` (entrypoint)
- `trading_engine.py` (core coordinator)
- Mode selectors:
- `live_trading.py`
- `paper_trading.py`

##### Market Data Ingestion Container
- `websocket_manager.py` (WS connectivity lifecycle)
- `layer1_market_data/market_data.py`
- `orderbook_depth.py` (order book depth handling)
- `resolution_validator.py` (data sanity / resolution checks)

##### Strategy / Decision Pipeline
This explicitly as a pipeline of containers or as one container with internal components:
- Layer 1 Runner: `layer1_runner.py`
- Layer 2 Runner: `layer2_runner.py`
- Layer 3 Runner: `layer3_runner.py`

##### Constraint & Opportunity Engines
- `layer2_constraint_detection/constraint_detector.py`
- `layer3_arbitrage_math/arbitrage_engine.py`

##### Execution Control Plane
- `execution_control.py` (server/controller)
- `execution_control_client.py` (client used by engine or tools)

##### Observability / UI
- `dashboard_server.py` (monitoring/ops UI service)

##### Configuration
- `config/config.yaml` (runtime config)
- `config/` (config package)

##### Ops / Lifecycle Scripts (non-runtime, but important)
- `start_all.sh`, `setup.ps1`
- `scripts/START_TRADER*.bat`, `scripts/STOP_TRADER.bat`, `scripts/status.sh`, etc.
- VPS/bootstrap: `scripts/setup_vps.sh`, `scripts/cloud_init_oracle*.sh`

- Market Data Ingestion → Strategy Pipeline (normalized market snapshots/events)
- Strategy Pipeline → Execution (orders/cancels)
- Execution Control ↔ Trading Orchestrator (pause/resume/kill-switch, mode changes)
- Trading Orchestrator → Dashboard Server (metrics/events), or Dashboard pulls from it (pick one and label “push” vs “pull”)
- Config → all runtime containers (read at startup; some may reload)

Goal: reflect the repo’s most distinctive structure: the layered runners + engines.

**Layer 1: Market Data**
- `WebsocketManager` (`websocket_manager.py`)
- `MarketData` (`layer1_market_data/market_data.py`)
- `OrderbookDepth` (`orderbook_depth.py`)
- Outputs: “Orderbook snapshots”, “Trades”, “Market state events”

**Layer 2: Constraint Detection**
- `ConstraintDetector` (`layer2_constraint_detection/constraint_detector.py`)
- Inputs: market state
- Outputs: “Feasible set”, “Filtered opportunities”, “Constraint violations”

**Layer 3: Arbitrage Math**
- `ArbitrageEngine` (`layer3_arbitrage_math/arbitrage_engine.py`)
- Inputs: feasible/filtered state
- Outputs: “Candidate trades”, “Sizing”, “Expected value/edge”

**Layer 4: (Execution / Portfolio / Risk)**
- `layer4_runner.py` as:
- “Execution + risk checks + order management” (until you confirm actual contents)
- Outputs: orders to external venue OR simulated fills in paper mode

**Cross-cutting**
- `resolution_validator.py` as a validator stage (either between L1→L2 or as part of L1)
- `execution_control_client.py` as a control input into runners (“pause”, “throttle”, “shutdown”)

- “WS event” → “normalized tick/orderbook”
- “constraints” → “trade candidates”
- “trade candidates” → “orders”

##### Relationships & interactions to highlight (what matters architecturally)
For accuracy, emphasize these interaction categories:

##### Data plane (high-throughput)
- WebSocket feeds → parsing → order book state → analytics
- Usually asynchronous/event-driven; represent this with:

##### Control plane (safety & operations)
- `execution_control.py` / `execution_control_client.py`
- Start/stop scripts
- Dashboard server
This is often overlooked; in trading systems it’s critical—show it explicitly separate from the data plane.

##### Mode switching
- Live vs paper trading: show a branch:
- Live path → external venue execution
- Paper path → simulated fills + PnL/accounting (you have `scripts/accounting.py` which hints at accounting workflows)

- **Python runtime** (entire repo)
- **WebSockets** (`websocket_manager.py`, `check_ws_*.sh`, `test_ws_import.sh`)
- **YAML configuration** (`config/config.yaml`)
- **OS scripting / deployment tooling**
- Bash (`*.sh`)
- Windows scripts (`*.bat`, `*.vbs`)
- PowerShell (`setup.ps1`)
- **Cloud/VPS bootstrapping** (Oracle hinted by `cloud_init_oracle*.sh`)

##### Container: “Processes/services/modules and how they connect”
3) **Component (Pipeline)**: “Layer1→Layer4 detailed flow, including validators and control hooks”

## Diagram (Mermaid)

```mermaid
flowchart TD

%% ==========================================================
%% System Context + Container + Component (Pipeline) in one
%% Oriented vertically (top-down) with grouped subgraphs
%% ==========================================================

%% ----------------------------
%% External Actors / Systems
%% ----------------------------
Operator(["Operator / Trader"]):::actor
subgraph "External Prediction Market Platform(s)" 
  ExtWS["CLOB WebSocket Feed"]:::external
  ExtAPI["Order API (place/cancel)"]:::external
end

Hosting["Hosting Environment\n(Local / VPS / Oracle Cloud)"]:::external

%% ----------------------------
%% System Boundary
%% ----------------------------
subgraph "Prediction Trading System (Python)" 
  direction TB

  %% ---------- Control Plane ----------
  subgraph "Control Plane (Ops & Safety)"
    direction TB
    ExecCtl["Execution Control Server\n(kill-switch / pause / throttle)"]:::control
    ExecCtlClient["Execution Control Client"]:::control
    Dashboard["Dashboard Server\n(monitoring / ops UI)"]:::control

    subgraph "Ops / Lifecycle Tooling (non-runtime)"
      direction TB
      StartAll["start_all.sh\n(start/stop orchestration)"]:::ops
      ScriptsDir["scripts/ (bash/bat/vbs tooling)"]:::ops
      SetupPS["setup.ps1\n(Windows setup)"]:::ops
      SetupVPS["setup_remote_vps.sh\n(VPS bootstrap)"]:::ops
      CloudInit1["cloud_init_oracle.sh\n(Oracle init)"]:::ops
      CloudInit2["cloud_init_oracle_v2.sh\n(Oracle init v2)"]:::ops
      Accounting["accounting.py\n(paper/ops support)"]:::ops
    end
  end

  %% ---------- Config ----------
  subgraph "Configuration"
    direction TB
    ConfigYaml["config.yaml (YAML runtime config)"]:::config
    ConfigPkg["config/ (config package)"]:::config
  end

  %% ---------- Trading Orchestrator ----------
  subgraph "Trading Orchestrator"
    direction TB
    Main["main.py (Entrypoint)"]:::core
    Engine["trading_engine.py\n(Core coordinator)"]:::core
    LiveMode["live_trading.py\n(Live mode)"]:::core
    PaperMode["paper_trading.py\n(Paper mode)"]:::core
  end

  %% ---------- Data Plane ----------
  subgraph "Data Plane (Layered Strategy Pipeline)"
    direction TB

    %% Market data ingestion
    subgraph "Layer 1: Market Data Ingestion & Normalization"
      direction TB
      WSMan["websocket_manager.py\n(WS lifecycle: reconnect)"]:::data
      TestCLOB["test_clob_connect.py\n(connectivity test)"]:::data
      MarketData["layer1_market_data/market_data.py\n(normalize market data)"]:::data
      OrderbookDepth["orderbook_depth.py\n(order book depth)"]:::data
      ResVal["resolution_validator.py\n(stale/invalid resolution checks)"]:::data
      L1Runner["layer1_runner.py\n(L1 orchestration)"]:::runner
    end

    %% Constraint detection
    subgraph "Layer 2: Constraint Detection"
      direction TB
      ConstraintDet["layer2_constraint_detection/constraint_detector.py"]:::data
      L2Runner["layer2_runner.py\n(L2 orchestration)"]:::runner
    end

    %% Arbitrage math
    subgraph "Layer 3: Arbitrage / Opportunity Math"
      direction TB
      ArbEngine["layer3_arbitrage_math/arbitrage_engine.py"]:::data
      L3Runner["layer3_runner.py\n(L3 orchestration)"]:::runner
    end

    %% Execution/risk stage
    subgraph "Layer 4: Execution / Portfolio / Risk (assumed)"
      direction TB
      L4Runner["layer4_runner.py\n(orders + risk checks)"]:::runner
    end
  end

end

%% ==========================================================
%% Connections (Context)
%% ==========================================================
Operator -->|"start/stop/configure"| StartAll
Operator -->|"use tooling"| ScriptsDir
Operator -->|"monitor"| Dashboard
Operator -->|"safety commands"| ExecCtl

Hosting -->|"runs on"| Main

ExtWS -.->|"market data (WS stream)"| WSMan
WSMan -.->|"WS disconnect/reconnect handling"| ExtWS
L4Runner -->|"orders/cancels"| ExtAPI

%% ==========================================================
%% Connections (Orchestrator <-> Control)
%% ==========================================================
ExecCtlClient -->|"control commands (pause/throttle/shutdown)"| ExecCtl
Engine <-->|"control channel"| ExecCtlClient
Dashboard <-->|"status/metrics (push/pull)"| Engine

%% ==========================================================
%% Connections (Config)
%% ==========================================================
ConfigYaml -->|"read at startup"| Main
ConfigYaml -->|"read at startup"| Engine
ConfigYaml -->|"params"| WSMan
ConfigYaml -->|"params"| L1Runner
ConfigYaml -->|"params"| L2Runner
ConfigYaml -->|"params"| L3Runner
ConfigYaml -->|"params"| L4Runner
ConfigPkg -->|"loads"| ConfigYaml

%% ==========================================================
%% Connections (Data Plane Pipeline)
%% ==========================================================
Main -->|"boot"| Engine
Engine -->|"select mode"| LiveMode
Engine -->|"select mode"| PaperMode

WSMan -.->|"WS event"| MarketData
MarketData -->|"normalized tick/orderbook"| OrderbookDepth
OrderbookDepth -->|"orderbook snapshot"| ResVal
ResVal -->|"validated market state"| L1Runner

L1Runner -->|"market snapshots/events"| L2Runner
L2Runner -->|"invoke"| ConstraintDet
ConstraintDet -->|"constraints/feasible set"| L2Runner

L2Runner -->|"filtered state"| L3Runner
L3Runner -->|"invoke"| ArbEngine
ArbEngine -->|"trade candidates + sizing/edge"| L3Runner

L3Runner -->|"candidate trades"| L4Runner
L4Runner -->|"live execution path"| LiveMode
L4Runner -->|"paper fills + PnL (assumed)"| PaperMode
PaperMode -->|"accounting workflow"| Accounting

%% Failure-mode callouts (notes)
WSMan -.->|"note:WS reconnects"| MarketData
ResVal -.->|"note:stale/invalid book detection"| L2Runner
ExecCtl -.->|"note:kill-switch/pause"| L4Runner

%% ==========================================================
%% Click Events (from component mapping)
%% ==========================================================
click Main "https://github.com/andydoc/prediction-trading/blob/main/main.py"
click Engine "https://github.com/andydoc/prediction-trading/blob/main/trading_engine.py"
click LiveMode "https://github.com/andydoc/prediction-trading/blob/main/live_trading.py"
click PaperMode "https://github.com/andydoc/prediction-trading/blob/main/paper_trading.py"

click WSMan "https://github.com/andydoc/prediction-trading/blob/main/websocket_manager.py"
click TestCLOB "https://github.com/andydoc/prediction-trading/blob/main/test_clob_connect.py"

click MarketData "https://github.com/andydoc/prediction-trading/blob/main/layer1_market_data/market_data.py"
click L1Runner "https://github.com/andydoc/prediction-trading/blob/main/layer1_runner.py"
click OrderbookDepth "https://github.com/andydoc/prediction-trading/blob/main/orderbook_depth.py"
click ResVal "https://github.com/andydoc/prediction-trading/blob/main/resolution_validator.py"

click ConstraintDet "https://github.com/andydoc/prediction-trading/blob/main/layer2_constraint_detection/constraint_detector.py"
click L2Runner "https://github.com/andydoc/prediction-trading/blob/main/layer2_runner.py"

click ArbEngine "https://github.com/andydoc/prediction-trading/blob/main/layer3_arbitrage_math/arbitrage_engine.py"
click L3Runner "https://github.com/andydoc/prediction-trading/blob/main/layer3_runner.py"

click L4Runner "https://github.com/andydoc/prediction-trading/blob/main/layer4_runner.py"

click ExecCtl "https://github.com/andydoc/prediction-trading/blob/main/execution_control.py"
click ExecCtlClient "https://github.com/andydoc/prediction-trading/blob/main/execution_control_client.py"

click Dashboard "https://github.com/andydoc/prediction-trading/blob/main/dashboard_server.py"

click ConfigYaml "https://github.com/andydoc/prediction-trading/blob/main/config/config.yaml"
click ConfigPkg "https://github.com/andydoc/prediction-trading/tree/main/config/"

click StartAll "https://github.com/andydoc/prediction-trading/blob/main/start_all.sh"
click ScriptsDir "https://github.com/andydoc/prediction-trading/tree/main/scripts/"
click SetupVPS "https://github.com/andydoc/prediction-trading/blob/main/scripts/setup_remote_vps.sh"
click CloudInit1 "https://github.com/andydoc/prediction-trading/blob/main/scripts/cloud_init_oracle.sh"
click CloudInit2 "https://github.com/andydoc/prediction-trading/blob/main/scripts/cloud_init_oracle_v2.sh"
click Accounting "https://github.com/andydoc/prediction-trading/blob/main/scripts/accounting.py"
click SetupPS "https://github.com/andydoc/prediction-trading/blob/main/setup.ps1"

%% ==========================================================
%% Styles
%% ==========================================================
classDef external fill:#E5E7EB,stroke:#6B7280,color:#111827,stroke-width:1px
classDef actor fill:#F3F4F6,stroke:#111827,color:#111827,stroke-width:1px
classDef core fill:#DBEAFE,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1px
classDef data fill:#BFDBFE,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1px
classDef runner fill:#93C5FD,stroke:#1E40AF,color:#0B1B3A,stroke-width:1px
classDef control fill:#FED7AA,stroke:#C2410C,color:#3B1A00,stroke-width:1px
classDef ops fill:#FDE68A,stroke:#B45309,color:#3B1A00,stroke-width:1px
classDef config fill:#E9D5FF,stroke:#7C3AED,color:#2E1065,stroke-width:1px
```
