# binqqarenyu/kalshi-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/binqqarenyu/kalshi-simulator
- Repository: https://github.com/binqqarenyu/kalshi-simulator

## Overview

This is a multi-asset Kalshi prediction-market trading terminal and quantitative bot platform. The principal workflow runs from live market feeds through strategy evaluation and risk authorization to paper or live order execution, followed by settlement and analytics. The README also documents a paper-trading incubator, sealed live-bot authorization, presets, and a unified terminal. Some subsystem paths and calls are supported only by the source index or README; unsampled implementation details are not inferred.

Main entry points: [`app_2_execution_bot/server.py`](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/server.py) (API Server), [`frontend/src/App.tsx`](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/App.tsx) (Terminal UI), [`src/kalshi_sim/ingestion_agent.py`](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ingestion_agent.py) (Market Ingestion), [`src/kalshi_sim/ml/bot1_v4_engine.py`](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ml/bot1_v4_engine.py) (Strategy Bots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Unified Terminal"]
  node_ui["Terminal UI<br/>[App.tsx]"]
  node_baby["Baby Bot Console<br/>[BabyBotConsole.tsx]"]
  node_hub["Parent Hub<br/>[ParentHub.tsx]"]
  node_server["API Server<br/>[server.py]"]
end

subgraph group_market["Market Data"]
  node_ingest["Market Ingestion<br/>[ingestion_agent.py]"]
  node_discovery["Market Discovery"]
  node_book["Order Book State<br/>[schemas.py]"]
end

subgraph group_strategy["Strategy and Simulation"]
  node_strategy["Strategy Bots<br/>[bot1_v4_engine.py]"]
  node_ev["EV Evaluation"]
  node_simulation["Paper Incubator"]
end

subgraph group_execution["Trade Execution"]
  node_orders["Order API<br/>[orders.py]"]
  node_live["Live Coordination"]
  node_exchange["Exchange Client<br/>[order_client.py]"]
end

subgraph group_governance["Governance and Incubation"]
  node_auditor["Deployment Auditor"]
  node_guardrails["Trade Guardrails"]
  node_presets["Preset Vault<br/>[preset_manager.py]"]
end

subgraph group_state["State and Analytics"]
  node_db[("Trading Database<br/>[writer.py]")]
  node_analytics["Analytics API<br/>[analytics.py]"]
  node_settlement["Settlement<br/>[settlement.py]"]
end

node_trader(("Trader"))

node_trader -->|"uses"| node_ui
node_ui -->|"renders"| node_hub
node_ui -->|"renders"| node_baby
node_ui -.->|"connects to"| node_server
node_server -->|"starts"| node_ingest
node_ingest -->|"uses"| node_discovery
node_ingest -->|"uses"| node_simulation
node_server -->|"serves"| node_book
node_server -.->|"coordinates"| node_strategy
node_strategy -->|"evaluates with"| node_ev
node_server -.->|"routes"| node_orders
node_orders -.->|"coordinates"| node_live
node_live -.->|"submits orders"| node_exchange
node_server -->|"checks deployment"| node_auditor
node_auditor -->|"audits"| node_guardrails
node_server -->|"manages presets"| node_presets
node_simulation -.->|"records trades"| node_db
node_server -.->|"serves"| node_analytics
node_server -.->|"syncs settlements"| node_settlement

click node_ui "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/App.tsx"
click node_baby "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/components/BabyBotConsole.tsx"
click node_hub "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/components/ParentHub.tsx"
click node_server "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/server.py"
click node_ingest "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ingestion_agent.py"
click node_discovery "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/market_discovery.py"
click node_book "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/shared/schemas.py"
click node_strategy "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ml/bot1_v4_engine.py"
click node_ev "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ml/statistical_ev_engine.py"
click node_simulation "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/simulation_agent.py"
click node_orders "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/routers/orders.py"
click node_live "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/live_coordinator.py"
click node_exchange "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/order_client.py"
click node_auditor "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_3_autonomous_chef/bot_deployment_auditor.py"
click node_guardrails "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/agent_guardrails.py"
click node_presets "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/preset_manager.py"
click node_db "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/db/writer.py"
click node_analytics "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/routers/analytics.py"
click node_settlement "https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/settlement.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_ui,node_baby,node_hub,node_server toneBlue
class node_ingest,node_discovery,node_book toneAmber
class node_strategy,node_ev,node_simulation toneMint
class node_orders,node_live,node_exchange toneRose
class node_auditor,node_guardrails,node_presets,node_trader toneIndigo
class node_db,node_analytics,node_settlement toneTeal
```

## Components

### Unified Terminal

- [Terminal UI](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Baby Bot Console](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/components/BabyBotConsole.tsx): `frontend/src/components/BabyBotConsole.tsx`
- [Parent Hub](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/frontend/src/components/ParentHub.tsx): `frontend/src/components/ParentHub.tsx`
- [API Server](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/server.py): `app_2_execution_bot/server.py`

### Market Data

- [Market Ingestion](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ingestion_agent.py): `src/kalshi_sim/ingestion_agent.py`
- [Market Discovery](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/market_discovery.py): `src/kalshi_sim/market_discovery.py`
- [Order Book State](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/shared/schemas.py): `shared/schemas.py`

### Strategy and Simulation

- [Strategy Bots](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ml/bot1_v4_engine.py): `src/kalshi_sim/ml/bot1_v4_engine.py`
- [EV Evaluation](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/ml/statistical_ev_engine.py): `src/kalshi_sim/ml/statistical_ev_engine.py`
- [Paper Incubator](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/simulation_agent.py): `src/kalshi_sim/simulation_agent.py`

### Trade Execution

- [Order API](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/routers/orders.py): `src/kalshi_sim/routers/orders.py`
- [Live Coordination](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/live_coordinator.py): `app_2_execution_bot/live_coordinator.py`
- [Exchange Client](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_2_execution_bot/order_client.py): `app_2_execution_bot/order_client.py`

### Governance and Incubation

- [Deployment Auditor](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/app_3_autonomous_chef/bot_deployment_auditor.py): `app_3_autonomous_chef/bot_deployment_auditor.py`
- [Trade Guardrails](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/agent_guardrails.py): `src/kalshi_sim/agent_guardrails.py`
- [Preset Vault](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/preset_manager.py): `src/kalshi_sim/preset_manager.py`

### State and Analytics

- [Trading Database](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/db/writer.py): `src/kalshi_sim/db/writer.py`
- [Analytics API](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/routers/analytics.py): `src/kalshi_sim/routers/analytics.py`
- [Settlement](https://github.com/binqqarenyu/kalshi-simulator/blob/refactor/3-pillar-monorepo/src/kalshi_sim/settlement.py): `src/kalshi_sim/settlement.py`

### Other components

- **Trader**

## Connections

- Trader → Terminal UI: uses (evidence: `README.md`)
- Terminal UI → Parent Hub: renders (evidence: `frontend/src/App.tsx`)
- Terminal UI → Baby Bot Console: renders (evidence: `frontend/src/App.tsx`)
- Terminal UI → API Server: connects to (evidence: `README.md`)
- API Server → Market Ingestion: starts (evidence: `app_2_execution_bot/server.py`)
- Market Ingestion → Market Discovery: uses (evidence: `src/kalshi_sim/ingestion_agent.py`)
- Market Ingestion → Paper Incubator: uses (evidence: `src/kalshi_sim/ingestion_agent.py`)
- API Server → Order Book State: serves (evidence: `README.md`)
- API Server → Strategy Bots: coordinates (evidence: `README.md`)
- Strategy Bots → EV Evaluation: evaluates with (evidence: `src/kalshi_sim/ml/bot1_v4_engine.py`)
- API Server → Order API: routes (evidence: `app_2_execution_bot/server.py`)
- Order API → Live Coordination: coordinates (evidence: `README.md`)
- Live Coordination → Exchange Client: submits orders (evidence: `README.md`)
- API Server → Deployment Auditor: checks deployment (evidence: `app_2_execution_bot/server.py`)
- Deployment Auditor → Trade Guardrails: audits (evidence: `app_3_autonomous_chef/bot_deployment_auditor.py`)
- API Server → Preset Vault: manages presets (evidence: `app_2_execution_bot/server.py`)
- Paper Incubator → Trading Database: records trades
- API Server → Analytics API: serves (evidence: `app_2_execution_bot/server.py`)
- API Server → Settlement: syncs settlements (evidence: `README.md`)
