# anabol21/arb_bots architecture

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

- Interactive diagram: https://gitdiagram.com/anabol21/arb_bots
- Repository: https://github.com/anabol21/arb_bots

## Overview

The repository spans three documented tracks: public market-data collection and storage (D), historical strategy research and simulation (M), and bot decision-making with a stub-first/private execution path (B). D collects public exchange data, validates and publishes it locally, then compacts and backs it up. M analyzes historical ticks and runs frozen gear-2.2 simulations. B turns market signals into would_send records by default; gated private WebSocket execution is a separate path. The graph preserves major documented capabilities, but several unsampled modules are represented only at directory level; their internal calls are not inferred.

Main entry points: [`app/bot/private/ws_private.py`](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_private.py) (Private WebSocket flow), [`app/screaner_b_o.py`](https://github.com/anabol21/arb_bots/blob/main/app/screaner_b_o.py) (Spread collector), [`app/bot/theta_trade_manager.py`](https://github.com/anabol21/arb_bots/blob/main/app/bot/theta_trade_manager.py) (Theta trade manager), [`app/storage/writer.py`](https://github.com/anabol21/arb_bots/blob/main/app/storage/writer.py) (Parquet publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["D · Collection"]
  node_collector["Spread collector<br/>[screaner_b_o.py]"]
  node_hlruntime["HL v2 runtime<br/>[runtime.py]"]
  node_hllisteners["Market listeners<br/>[listeners_hl.py]"]
  node_lean_schema["Lean event schema<br/>[lean_event.py]"]
  node_discovery["Universe intersection<br/>[intersection.py]"]
  node_reconnect["Reconnect policy<br/>[ws_reconnect.py]"]
end

subgraph group_storage["D · Storage"]
  node_publisher["Parquet publisher<br/>[writer.py]"]
  node_spool["Durable spool<br/>[spool.py]"]
  node_mount["Mount state<br/>[mount_state.py]"]
  node_compactor["Dataset compactor<br/>[compactor.py]"]
  node_backup["Backup transfer<br/>[backup_transfer.py]"]
end

subgraph group_model["M · Research"]
  node_tick_reader["Historical tick reader<br/>[lean_ticks_io.py]"]
  node_gear22_policy["Frozen gear-2.2 policy<br/>[policy.py]"]
  node_gear22_params["Frozen parameters<br/>[params_frozen.py]"]
  node_gear22_ledger["Observation ledger<br/>[venue_ledger.py]"]
  node_gear22_sweep["Parameter-space analysis"]
  node_gear2_analysis["Gear-2 research"]
end

subgraph group_bot["B · Bot"]
  node_bot_runtime["Bot runtime<br/>[runtime.py]"]
  node_theta_manager["Theta trade manager"]
  node_trade_policy["Trade policy<br/>[trade_manager.py]"]
  node_stub_broker["Would-send broker<br/>[stub_broker.py]"]
end

subgraph group_private["B · Private"]
  node_private_ws["Private WebSocket flow<br/>[ws_private.py]"]
  node_warm_session["Warm session supervisor<br/>[ws_warm_session.py]"]
  node_ws_gates["Send gates<br/>[ws_gates.py]"]
  node_order_plan["Order planning<br/>[order_plan.py]"]
  node_order_sign["Order signing<br/>[order_sign.py]"]
  node_venue["Venue configuration<br/>[venue.py]"]
  node_journal[("Private journal<br/>[journal_v1.py]")]
  node_socket["WebSocket transport<br/>[ws_socket.py]"]
end

node_researcher(("Research user"))
node_operator(("Bot operator"))
node_exchanges["Public exchanges"]
node_private_venues["Private venues"]
node_backup_service[("Backup destination")]

node_exchanges -->|"send quotes"| node_collector
node_collector -->|"uses schema"| node_lean_schema
node_collector -->|"publishes records"| node_publisher
node_collector -->|"plans reconnects"| node_reconnect
node_hlruntime -->|"starts listeners"| node_hllisteners
node_hlruntime -->|"builds publisher"| node_publisher
node_hlruntime -->|"configures spool"| node_spool
node_hllisteners -->|"uses reconnect"| node_reconnect
node_publisher -->|"spools failures"| node_spool
node_publisher -->|"checks mount"| node_mount
node_compactor -.->|"feeds backup"| node_backup
node_backup -.->|"transfers copy"| node_backup_service
node_researcher -->|"analyzes ticks"| node_tick_reader
node_tick_reader -->|"supplies tick data"| node_gear2_analysis
node_tick_reader -->|"reads ticks"| node_gear22_ledger
node_gear22_params -->|"sets frozen rules"| node_gear22_policy
node_gear22_policy -.->|"guides replay"| node_gear22_ledger
node_gear22_policy -->|"evaluates frozen rules"| node_gear22_sweep
node_operator -.->|"starts bot"| node_bot_runtime
node_bot_runtime -->|"drives signals"| node_theta_manager
node_theta_manager -->|"requests decision"| node_trade_policy
node_theta_manager -.->|"records would-send"| node_stub_broker
node_theta_manager -.->|"optional live send"| node_private_ws
node_private_ws -->|"checks gates"| node_ws_gates
node_private_ws -->|"builds order plan"| node_order_plan
node_private_ws -->|"signs order"| node_order_sign
node_private_ws -->|"uses venue config"| node_venue
node_private_ws -->|"writes events"| node_journal
node_private_ws -->|"sends messages"| node_socket
node_warm_session -->|"supervises session"| node_private_ws
node_private_ws -.->|"trades gated"| node_private_venues

click node_collector "https://github.com/anabol21/arb_bots/blob/main/app/screaner_b_o.py"
click node_hlruntime "https://github.com/anabol21/arb_bots/blob/main/app/hl_v2/runtime.py"
click node_hllisteners "https://github.com/anabol21/arb_bots/blob/main/app/hl_v2/listeners_hl.py"
click node_lean_schema "https://github.com/anabol21/arb_bots/blob/main/app/schema/lean_event.py"
click node_publisher "https://github.com/anabol21/arb_bots/blob/main/app/storage/writer.py"
click node_spool "https://github.com/anabol21/arb_bots/blob/main/app/storage/spool.py"
click node_mount "https://github.com/anabol21/arb_bots/blob/main/app/storage/mount_state.py"
click node_compactor "https://github.com/anabol21/arb_bots/blob/main/app/storage/compactor.py"
click node_backup "https://github.com/anabol21/arb_bots/blob/main/app/storage/backup_transfer.py"
click node_discovery "https://github.com/anabol21/arb_bots/blob/main/app/discovery/intersection.py"
click node_tick_reader "https://github.com/anabol21/arb_bots/blob/main/research/lean_ticks_io.py"
click node_gear22_policy "https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/policy.py"
click node_gear22_params "https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/params_frozen.py"
click node_gear22_ledger "https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/venue_ledger.py"
click node_gear22_sweep "https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/venue_param_space.py"
click node_gear2_analysis "https://github.com/anabol21/arb_bots/blob/main/research/gear2_coin_overview_html.py"
click node_bot_runtime "https://github.com/anabol21/arb_bots/blob/main/app/bot/runtime.py"
click node_theta_manager "https://github.com/anabol21/arb_bots/blob/main/app/bot/theta_trade_manager.py"
click node_trade_policy "https://github.com/anabol21/arb_bots/blob/main/app/policy/trade_manager.py"
click node_stub_broker "https://github.com/anabol21/arb_bots/blob/main/app/bot/stub_broker.py"
click node_private_ws "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_private.py"
click node_warm_session "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_warm_session.py"
click node_ws_gates "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_gates.py"
click node_order_plan "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/order_plan.py"
click node_order_sign "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/order_sign.py"
click node_venue "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/venue.py"
click node_journal "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/journal_v1.py"
click node_socket "https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_socket.py"
click node_reconnect "https://github.com/anabol21/arb_bots/blob/main/app/utils/ws_reconnect.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_collector,node_hlruntime,node_hllisteners,node_lean_schema,node_discovery,node_reconnect,node_researcher toneBlue
class node_publisher,node_spool,node_mount,node_compactor,node_backup,node_backup_service toneAmber
class node_tick_reader,node_gear22_policy,node_gear22_params,node_gear22_ledger,node_gear22_sweep,node_gear2_analysis toneMint
class node_bot_runtime,node_theta_manager,node_trade_policy,node_stub_broker toneRose
class node_private_ws,node_warm_session,node_ws_gates,node_order_plan,node_order_sign,node_venue,node_journal,node_socket,node_operator,node_exchanges,node_private_venues toneIndigo
```

## Components

### D · Collection

- [Spread collector](https://github.com/anabol21/arb_bots/blob/main/app/screaner_b_o.py): `app/screaner_b_o.py`
- [HL v2 runtime](https://github.com/anabol21/arb_bots/blob/main/app/hl_v2/runtime.py): `app/hl_v2/runtime.py`
- [Market listeners](https://github.com/anabol21/arb_bots/blob/main/app/hl_v2/listeners_hl.py): `app/hl_v2/listeners_hl.py`
- [Lean event schema](https://github.com/anabol21/arb_bots/blob/main/app/schema/lean_event.py): `app/schema/lean_event.py`
- [Universe intersection](https://github.com/anabol21/arb_bots/blob/main/app/discovery/intersection.py): `app/discovery/intersection.py`
- [Reconnect policy](https://github.com/anabol21/arb_bots/blob/main/app/utils/ws_reconnect.py): `app/utils/ws_reconnect.py`

### D · Storage

- [Parquet publisher](https://github.com/anabol21/arb_bots/blob/main/app/storage/writer.py): `app/storage/writer.py`
- [Durable spool](https://github.com/anabol21/arb_bots/blob/main/app/storage/spool.py): `app/storage/spool.py`
- [Mount state](https://github.com/anabol21/arb_bots/blob/main/app/storage/mount_state.py): `app/storage/mount_state.py`
- [Dataset compactor](https://github.com/anabol21/arb_bots/blob/main/app/storage/compactor.py): `app/storage/compactor.py`
- [Backup transfer](https://github.com/anabol21/arb_bots/blob/main/app/storage/backup_transfer.py): `app/storage/backup_transfer.py`

### M · Research

- [Historical tick reader](https://github.com/anabol21/arb_bots/blob/main/research/lean_ticks_io.py): `research/lean_ticks_io.py`
- [Frozen gear-2.2 policy](https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/policy.py): `research/gear22_backtest/policy.py`
- [Frozen parameters](https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/params_frozen.py): `research/gear22_backtest/params_frozen.py`
- [Observation ledger](https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/venue_ledger.py): `research/gear22_backtest/venue_ledger.py`
- [Parameter-space analysis](https://github.com/anabol21/arb_bots/blob/main/research/gear22_backtest/venue_param_space.py): `research/gear22_backtest/venue_param_space.py`
- [Gear-2 research](https://github.com/anabol21/arb_bots/blob/main/research/gear2_coin_overview_html.py): `research/gear2_coin_overview_html.py`

### B · Bot

- [Bot runtime](https://github.com/anabol21/arb_bots/blob/main/app/bot/runtime.py): `app/bot/runtime.py`
- [Theta trade manager](https://github.com/anabol21/arb_bots/blob/main/app/bot/theta_trade_manager.py): `app/bot/theta_trade_manager.py`
- [Trade policy](https://github.com/anabol21/arb_bots/blob/main/app/policy/trade_manager.py): `app/policy/trade_manager.py`
- [Would-send broker](https://github.com/anabol21/arb_bots/blob/main/app/bot/stub_broker.py): `app/bot/stub_broker.py`

### B · Private

- [Private WebSocket flow](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_private.py): `app/bot/private/ws_private.py`
- [Warm session supervisor](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_warm_session.py): `app/bot/private/ws_warm_session.py`
- [Send gates](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_gates.py): `app/bot/private/ws_gates.py`
- [Order planning](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/order_plan.py): `app/bot/private/order_plan.py`
- [Order signing](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/order_sign.py): `app/bot/private/order_sign.py`
- [Venue configuration](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/venue.py): `app/bot/private/venue.py`
- [Private journal](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/journal_v1.py): `app/bot/private/journal_v1.py`
- [WebSocket transport](https://github.com/anabol21/arb_bots/blob/main/app/bot/private/ws_socket.py): `app/bot/private/ws_socket.py`

### Other components

- **Research user**
- **Bot operator**
- **Public exchanges**
- **Private venues**
- **Backup destination**

## Connections

- Public exchanges → Spread collector: send quotes
- Spread collector → Lean event schema: uses schema (evidence: `app/screaner_b_o.py`)
- Spread collector → Parquet publisher: publishes records (evidence: `app/screaner_b_o.py`)
- Spread collector → Reconnect policy: plans reconnects (evidence: `app/screaner_b_o.py`)
- HL v2 runtime → Market listeners: starts listeners (evidence: `app/hl_v2/runtime.py`)
- HL v2 runtime → Parquet publisher: builds publisher (evidence: `app/hl_v2/runtime.py`)
- HL v2 runtime → Durable spool: configures spool (evidence: `app/hl_v2/runtime.py`)
- Market listeners → Reconnect policy: uses reconnect (evidence: `app/hl_v2/listeners_hl.py`)
- Parquet publisher → Durable spool: spools failures (evidence: `app/storage/writer.py`)
- Parquet publisher → Mount state: checks mount (evidence: `app/storage/writer.py`)
- Dataset compactor → Backup transfer: feeds backup
- Backup transfer → Backup destination: transfers copy
- Research user → Historical tick reader: analyzes ticks (evidence: `research/lean_ticks_io.py`)
- Historical tick reader → Gear-2 research: supplies tick data (evidence: `research/gear2_coin_overview_html.py`)
- Historical tick reader → Observation ledger: reads ticks (evidence: `research/gear22_backtest/venue_ledger.py`)
- Frozen parameters → Frozen gear-2.2 policy: sets frozen rules (evidence: `research/gear22_backtest/params_frozen.py`)
- Frozen gear-2.2 policy → Observation ledger: guides replay (evidence: `research/gear22_backtest/venue_ledger.py`)
- Frozen gear-2.2 policy → Parameter-space analysis: evaluates frozen rules (evidence: `research/gear22_backtest/venue_param_space.py`)
- Bot operator → Bot runtime: starts bot
- Bot runtime → Theta trade manager: drives signals (evidence: `app/bot/theta_trade_manager.py`)
- Theta trade manager → Trade policy: requests decision (evidence: `app/bot/theta_trade_manager.py`)
- Theta trade manager → Would-send broker: records would-send (evidence: `app/bot/theta_trade_manager.py`)
- Theta trade manager → Private WebSocket flow: optional live send
- Private WebSocket flow → Send gates: checks gates (evidence: `app/bot/private/ws_private.py`)
- Private WebSocket flow → Order planning: builds order plan (evidence: `app/bot/private/ws_private.py`)
- Private WebSocket flow → Order signing: signs order (evidence: `app/bot/private/ws_private.py`)
- Private WebSocket flow → Venue configuration: uses venue config (evidence: `app/bot/private/ws_private.py`)
- Private WebSocket flow → Private journal: writes events (evidence: `app/bot/private/ws_private.py`)
- Private WebSocket flow → WebSocket transport: sends messages (evidence: `app/bot/private/ws_private.py`)
- Warm session supervisor → Private WebSocket flow: supervises session (evidence: `app/bot/private/ws_warm_session.py`)
- Private WebSocket flow → Private venues: trades gated
