# minculusofia-wq/ironvault architecture

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

- Interactive diagram: https://gitdiagram.com/minculusofia-wq/ironvault
- Repository: https://github.com/minculusofia-wq/ironvault

## Overview

IRONVAULT is a Polymarket trading bot with a PySide6 operator interface. The main workflow is operator controls → orchestration and risk/capital checks → market signals and strategy decisions → order execution and position/PnL tracking, with audit and performance data surfaced to the UI. Strategy A reacts to triggers; Strategy B provides multi-market liquidity and manages exits. The graph reflects the README and shown excerpts plus SOURCE INDEX references; unsampled implementation details and some wiring remain unverified.

Main entry points: [`backend/orchestrator.py`](https://github.com/minculusofia-wq/ironvault/blob/main/backend/orchestrator.py) (Bot orchestrator), [`backend/strategies/strategy_b_market_making.py`](https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_b_market_making.py) (Market-making strategy), [`frontend/main_window.py`](https://github.com/minculusofia-wq/ironvault/blob/main/frontend/main_window.py) (Application window), [`backend/strategies/strategy_a_front_running.py`](https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_a_front_running.py) (Front-running strategy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator interface"]
  node_main["Application window<br/>[main_window.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_controls["Controls and config<br/>[controls.py]"]
  node_optimizer["Auto optimizer"]
end

subgraph group_coordination["Bot coordination"]
  node_orchestrator["Bot orchestrator<br/>[orchestrator.py]"]
  node_config["Configuration loader<br/>[config_loader.py]"]
end

subgraph group_signals["Market signals"]
  node_strategy_a["Front-running strategy"]
  node_strategy_b["Market-making strategy"]
  node_feed["Polymarket price feed<br/>[polymarket_feed.py]"]
  node_scoreboard["Scoreboard monitor"]
  node_scanner["Market scanner<br/>[market_scanner.py]"]
  node_market_data["Market data<br/>[market_data.py]"]
  node_clob["CLOB adapter<br/>[clob_adapter.py]"]
  node_websocket["WebSocket client"]
end

subgraph group_trading["Trading and risk"]
  node_execution["Execution engine"]
  node_capital["Capital manager<br/>[capital_manager.py]"]
  node_policy["Policy layer<br/>[policy_layer.py]"]
  node_volatility["Volatility filter"]
  node_kill["Kill switch<br/>[kill_switch.py]"]
  node_vault["Secure vault<br/>[secure_vault.py]"]
end

subgraph group_observability["Audit and metrics"]
  node_audit[("Audit logger<br/>[audit_logger.py]")]
  node_performance[("Performance tracker")]
  node_analytics["Analytics engine"]
end

node_operator(("Operator"))
node_polymarket(("Polymarket<br/>external system"))

node_operator -->|"operates"| node_main
node_main -->|"controls bot"| node_orchestrator
node_main -->|"displays"| node_dashboard
node_main -->|"hosts controls"| node_controls
node_main -->|"hosts optimizer"| node_optimizer
node_orchestrator -->|"loads config"| node_config
node_orchestrator -->|"dispatches ticks"| node_strategy_a
node_orchestrator -->|"dispatches ticks"| node_strategy_b
node_orchestrator -->|"manages execution"| node_execution
node_orchestrator -->|"allocates capital"| node_capital
node_orchestrator -->|"checks policy"| node_policy
node_orchestrator -->|"manages safety"| node_kill
node_orchestrator -->|"coordinates monitor"| node_scoreboard
node_orchestrator -->|"manages connection"| node_websocket
node_orchestrator -->|"records trades"| node_performance
node_orchestrator -->|"logs events"| node_audit
node_strategy_a -->|"submits orders"| node_execution
node_strategy_a -->|"fetches books"| node_clob
node_strategy_a -->|"uses triggers"| node_scoreboard
node_strategy_a -->|"checks volatility"| node_volatility
node_strategy_b -->|"submits orders"| node_execution
node_strategy_b -->|"receives updates"| node_websocket
node_strategy_b -->|"checks volatility"| node_volatility
node_strategy_b -->|"uses market data"| node_market_data
node_strategy_b -->|"tracks positions"| node_performance
node_feed -->|"fetches books"| node_clob
node_feed -->|"gets markets"| node_scanner
node_scanner -->|"reads market data"| node_market_data
node_scanner -->|"fetches books"| node_clob
node_execution -->|"logs trades"| node_audit
node_clob -->|"requests book data"| node_polymarket
node_websocket -->|"connects stream"| node_polymarket
node_analytics -->|"reads audit data"| node_audit
node_orchestrator -.->|"updates metrics"| node_analytics
node_orchestrator -.->|"handles credentials"| node_vault

click node_main "https://github.com/minculusofia-wq/ironvault/blob/main/frontend/main_window.py"
click node_dashboard "https://github.com/minculusofia-wq/ironvault/blob/main/frontend/dashboard.py"
click node_controls "https://github.com/minculusofia-wq/ironvault/blob/main/frontend/controls.py"
click node_optimizer "https://github.com/minculusofia-wq/ironvault/blob/main/frontend/auto_optimizer_tab.py"
click node_orchestrator "https://github.com/minculusofia-wq/ironvault/blob/main/backend/orchestrator.py"
click node_config "https://github.com/minculusofia-wq/ironvault/blob/main/backend/config_loader.py"
click node_strategy_a "https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_a_front_running.py"
click node_strategy_b "https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_b_market_making.py"
click node_feed "https://github.com/minculusofia-wq/ironvault/blob/main/backend/data_feeds/polymarket_feed.py"
click node_scoreboard "https://github.com/minculusofia-wq/ironvault/blob/main/backend/scoreboard_monitor.py"
click node_scanner "https://github.com/minculusofia-wq/ironvault/blob/main/backend/market_scanner.py"
click node_market_data "https://github.com/minculusofia-wq/ironvault/blob/main/backend/market_data.py"
click node_clob "https://github.com/minculusofia-wq/ironvault/blob/main/backend/clob_adapter.py"
click node_websocket "https://github.com/minculusofia-wq/ironvault/blob/main/backend/websocket_client.py"
click node_execution "https://github.com/minculusofia-wq/ironvault/blob/main/backend/execution_engine.py"
click node_capital "https://github.com/minculusofia-wq/ironvault/blob/main/backend/capital_manager.py"
click node_policy "https://github.com/minculusofia-wq/ironvault/blob/main/backend/policy_layer.py"
click node_volatility "https://github.com/minculusofia-wq/ironvault/blob/main/backend/volatility_filter.py"
click node_kill "https://github.com/minculusofia-wq/ironvault/blob/main/backend/kill_switch.py"
click node_vault "https://github.com/minculusofia-wq/ironvault/blob/main/backend/secure_vault.py"
click node_audit "https://github.com/minculusofia-wq/ironvault/blob/main/backend/audit_logger.py"
click node_performance "https://github.com/minculusofia-wq/ironvault/blob/main/backend/performance_tracker.py"
click node_analytics "https://github.com/minculusofia-wq/ironvault/blob/main/backend/analytics_engine.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_main,node_dashboard,node_controls,node_optimizer toneBlue
class node_orchestrator,node_config toneAmber
class node_strategy_a,node_strategy_b,node_feed,node_scoreboard,node_scanner,node_market_data,node_clob,node_websocket toneMint
class node_execution,node_capital,node_policy,node_volatility,node_kill,node_vault toneRose
class node_audit,node_performance,node_analytics,node_operator,node_polymarket toneIndigo
```

## Components

### Operator interface

- [Application window](https://github.com/minculusofia-wq/ironvault/blob/main/frontend/main_window.py): `frontend/main_window.py`
- [Dashboard](https://github.com/minculusofia-wq/ironvault/blob/main/frontend/dashboard.py): `frontend/dashboard.py`
- [Controls and config](https://github.com/minculusofia-wq/ironvault/blob/main/frontend/controls.py): `frontend/controls.py`
- [Auto optimizer](https://github.com/minculusofia-wq/ironvault/blob/main/frontend/auto_optimizer_tab.py): `frontend/auto_optimizer_tab.py`

### Bot coordination

- [Bot orchestrator](https://github.com/minculusofia-wq/ironvault/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Configuration loader](https://github.com/minculusofia-wq/ironvault/blob/main/backend/config_loader.py): `backend/config_loader.py`

### Market signals

- [Front-running strategy](https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_a_front_running.py): `backend/strategies/strategy_a_front_running.py`
- [Market-making strategy](https://github.com/minculusofia-wq/ironvault/blob/main/backend/strategies/strategy_b_market_making.py): `backend/strategies/strategy_b_market_making.py`
- [Polymarket price feed](https://github.com/minculusofia-wq/ironvault/blob/main/backend/data_feeds/polymarket_feed.py): `backend/data_feeds/polymarket_feed.py`
- [Scoreboard monitor](https://github.com/minculusofia-wq/ironvault/blob/main/backend/scoreboard_monitor.py): `backend/scoreboard_monitor.py`
- [Market scanner](https://github.com/minculusofia-wq/ironvault/blob/main/backend/market_scanner.py): `backend/market_scanner.py`
- [Market data](https://github.com/minculusofia-wq/ironvault/blob/main/backend/market_data.py): `backend/market_data.py`
- [CLOB adapter](https://github.com/minculusofia-wq/ironvault/blob/main/backend/clob_adapter.py): `backend/clob_adapter.py`
- [WebSocket client](https://github.com/minculusofia-wq/ironvault/blob/main/backend/websocket_client.py): `backend/websocket_client.py`

### Trading and risk

- [Execution engine](https://github.com/minculusofia-wq/ironvault/blob/main/backend/execution_engine.py): `backend/execution_engine.py`
- [Capital manager](https://github.com/minculusofia-wq/ironvault/blob/main/backend/capital_manager.py): `backend/capital_manager.py`
- [Policy layer](https://github.com/minculusofia-wq/ironvault/blob/main/backend/policy_layer.py): `backend/policy_layer.py`
- [Volatility filter](https://github.com/minculusofia-wq/ironvault/blob/main/backend/volatility_filter.py): `backend/volatility_filter.py`
- [Kill switch](https://github.com/minculusofia-wq/ironvault/blob/main/backend/kill_switch.py): `backend/kill_switch.py`
- [Secure vault](https://github.com/minculusofia-wq/ironvault/blob/main/backend/secure_vault.py): `backend/secure_vault.py`

### Audit and metrics

- [Audit logger](https://github.com/minculusofia-wq/ironvault/blob/main/backend/audit_logger.py): `backend/audit_logger.py`
- [Performance tracker](https://github.com/minculusofia-wq/ironvault/blob/main/backend/performance_tracker.py): `backend/performance_tracker.py`
- [Analytics engine](https://github.com/minculusofia-wq/ironvault/blob/main/backend/analytics_engine.py): `backend/analytics_engine.py`

### Other components

- **Operator**
- **Polymarket**: external system

## Connections

- Operator → Application window: operates
- Application window → Bot orchestrator: controls bot (evidence: `frontend/main_window.py`)
- Application window → Dashboard: displays (evidence: `frontend/main_window.py`)
- Application window → Controls and config: hosts controls (evidence: `frontend/main_window.py`)
- Application window → Auto optimizer: hosts optimizer (evidence: `frontend/main_window.py`)
- Bot orchestrator → Configuration loader: loads config (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Front-running strategy: dispatches ticks (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Market-making strategy: dispatches ticks (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Execution engine: manages execution (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Capital manager: allocates capital (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Policy layer: checks policy (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Kill switch: manages safety (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Scoreboard monitor: coordinates monitor (evidence: `backend/orchestrator.py`)
- Bot orchestrator → WebSocket client: manages connection (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Performance tracker: records trades (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Audit logger: logs events (evidence: `backend/orchestrator.py`)
- Front-running strategy → Execution engine: submits orders (evidence: `backend/strategies/strategy_a_front_running.py`)
- Front-running strategy → CLOB adapter: fetches books (evidence: `backend/strategies/strategy_a_front_running.py`)
- Front-running strategy → Scoreboard monitor: uses triggers (evidence: `backend/strategies/strategy_a_front_running.py`)
- Front-running strategy → Volatility filter: checks volatility (evidence: `backend/strategies/strategy_a_front_running.py`)
- Market-making strategy → Execution engine: submits orders (evidence: `backend/strategies/strategy_b_market_making.py`)
- Market-making strategy → WebSocket client: receives updates (evidence: `backend/strategies/strategy_b_market_making.py`)
- Market-making strategy → Volatility filter: checks volatility (evidence: `backend/strategies/strategy_b_market_making.py`)
- Market-making strategy → Market data: uses market data (evidence: `backend/strategies/strategy_b_market_making.py`)
- Market-making strategy → Performance tracker: tracks positions (evidence: `backend/strategies/strategy_b_market_making.py`)
- Polymarket price feed → CLOB adapter: fetches books (evidence: `backend/data_feeds/polymarket_feed.py`)
- Polymarket price feed → Market scanner: gets markets (evidence: `backend/data_feeds/polymarket_feed.py`)
- Market scanner → Market data: reads market data (evidence: `backend/market_scanner.py`)
- Market scanner → CLOB adapter: fetches books (evidence: `backend/market_scanner.py`)
- Execution engine → Audit logger: logs trades (evidence: `backend/execution_engine.py`)
- CLOB adapter → Polymarket: requests book data (evidence: `backend/clob_adapter.py`)
- WebSocket client → Polymarket: connects stream (evidence: `backend/websocket_client.py`)
- Analytics engine → Audit logger: reads audit data (evidence: `backend/analytics_engine.py`)
- Bot orchestrator → Analytics engine: updates metrics (evidence: `backend/orchestrator.py`)
- Bot orchestrator → Secure vault: handles credentials