# 0xethanq/astra-quant-agent architecture

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

- Interactive diagram: https://gitdiagram.com/0xethanq/astra-quant-agent
- Repository: https://github.com/0xethanq/astra-quant-agent

## Overview

AstraQuant is an autonomous quant-trading system with a web control plane and a scheduled trading runtime. Its documented trading cycle turns market and derivative data into a multi-model committee proposal, applies deterministic fail-closed risk checks, then executes and protects orders through OKX. Separate product branches provide the admin/dashboard interface, policy and strategy evolution, and gateway notification delivery. The README documents the trading stages; several runtime links below are documented rather than verified in sampled implementation excerpts.

Main entry points: [`scripts/ai_brain_trader.py`](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/ai_brain_trader.py) (Trading brain), [`astra_gateway/scheduler.py`](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/scheduler.py) (Cycle scheduler), [`astra_backend/app.py`](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/app.py) (Backend API), [`astra_gateway/worker.py`](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/worker.py) (Gateway worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading runtime"]
  node_scheduler["Cycle scheduler<br/>[scheduler.py]"]
  node_worker["Gateway worker<br/>[worker.py]"]
  node_brain["Trading brain<br/>[ai_brain_trader.py]"]
end

subgraph group_analysis["Analysis and policy"]
  node_market["Market data"]
  node_universe["Instrument universe<br/>[instrument_pool.py]"]
  node_factors["Factor calculus"]
  node_prompts["Prompt library<br/>[prompt_library.py]"]
  node_council["Model committee<br/>[debate.py]"]
  node_llm["LLM runtime<br/>[llm_manager.py]"]
  node_evolution["Strategy evolution"]
  node_policy["Policy snapshots"]
end

subgraph group_execution["Risk and execution"]
  node_risk["Risk gates<br/>[risk_gates.py]"]
  node_breaker["Circuit breaker<br/>[circuit_breaker.py]"]
  node_trader["Order lifecycle"]
  node_okx["OKX exchange<br/>[okx.py]"]
end

subgraph group_control["Web control plane"]
  node_frontend["Trading workstation<br/>[App.vue]"]
  node_api["Backend API<br/>[app.py]"]
  node_dashboard["Dashboard data"]
  node_admin["Admin routes"]
end

subgraph group_gateway["Gateway and delivery"]
  node_gateway_store[("Delivery queue<br/>[store.py]")]
  node_publisher["Event publisher<br/>[publisher.py]"]
  node_channel["Notification channels<br/>[channels.py]"]
end

node_user(("Operator"))
node_external["OKX service"]

node_scheduler -.->|"schedules"| node_market
node_scheduler -.->|"schedules"| node_brain
node_scheduler -.->|"schedules"| node_evolution
node_market -.->|"feeds"| node_factors
node_universe -.->|"constrains"| node_factors
node_brain -.->|"requests debate"| node_council
node_brain -.->|"uses prompts"| node_prompts
node_council -.->|"calls models"| node_llm
node_brain -.->|"submits intent"| node_risk
node_risk -.->|"checks exposure"| node_breaker
node_brain -.->|"dispatches intent"| node_trader
node_trader -.->|"submits orders"| node_okx
node_okx -.->|"executes on"| node_external
node_evolution -.->|"updates policy"| node_policy
node_user -.->|"uses"| node_frontend
node_frontend -.->|"requests data"| node_api
node_api -.->|"serves"| node_dashboard
node_api -->|"mounts routes"| node_admin
node_publisher -->|"enqueues events"| node_gateway_store
node_worker -.->|"claims deliveries"| node_gateway_store
node_worker -->|"sends delivery"| node_channel

click node_scheduler "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/scheduler.py"
click node_worker "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/worker.py"
click node_market "https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/market_data_service.py"
click node_universe "https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/instrument_pool.py"
click node_factors "https://github.com/0xethanq/astra-quant-agent/tree/main/scripts/factors"
click node_brain "https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/ai_brain_trader.py"
click node_prompts "https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/prompt_library.py"
click node_council "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/council/debate.py"
click node_llm "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/llm_manager.py"
click node_risk "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/execution/risk_gates.py"
click node_breaker "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/execution/circuit_breaker.py"
click node_trader "https://github.com/0xethanq/astra-quant-agent/tree/main/scripts/trader"
click node_okx "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/exchanges/okx.py"
click node_evolution "https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/self_improvement_engine.py"
click node_policy "https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/policy"
click node_frontend "https://github.com/0xethanq/astra-quant-agent/blob/main/frontend/src/App.vue"
click node_api "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/app.py"
click node_dashboard "https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/dashboard_payload"
click node_admin "https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/routers"
click node_gateway_store "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/store.py"
click node_publisher "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/publisher.py"
click node_channel "https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/channels.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_scheduler,node_worker,node_brain toneBlue
class node_market,node_universe,node_factors,node_prompts,node_council,node_llm,node_evolution,node_policy toneAmber
class node_risk,node_breaker,node_trader,node_okx toneMint
class node_frontend,node_api,node_dashboard,node_admin toneRose
class node_gateway_store,node_publisher,node_channel,node_user,node_external toneIndigo
```

## Components

### Trading runtime

- [Cycle scheduler](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/scheduler.py): `astra_gateway/scheduler.py`
- [Gateway worker](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/worker.py): `astra_gateway/worker.py`
- [Trading brain](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/ai_brain_trader.py): `scripts/ai_brain_trader.py`

### Analysis and policy

- [Market data](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/market_data_service.py): `scripts/market_data_service.py`
- [Instrument universe](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/instrument_pool.py): `scripts/instrument_pool.py`
- [Factor calculus](https://github.com/0xethanq/astra-quant-agent/tree/main/scripts/factors): `scripts/factors`
- [Prompt library](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/prompt_library.py): `scripts/prompt_library.py`
- [Model committee](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/council/debate.py): `astra_backend/council/debate.py`
- [LLM runtime](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/llm_manager.py): `astra_backend/llm_manager.py`
- [Strategy evolution](https://github.com/0xethanq/astra-quant-agent/blob/main/scripts/self_improvement_engine.py): `scripts/self_improvement_engine.py`
- [Policy snapshots](https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/policy): `astra_backend/policy`

### Risk and execution

- [Risk gates](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/execution/risk_gates.py): `astra_backend/execution/risk_gates.py`
- [Circuit breaker](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/execution/circuit_breaker.py): `astra_backend/execution/circuit_breaker.py`
- [Order lifecycle](https://github.com/0xethanq/astra-quant-agent/tree/main/scripts/trader): `scripts/trader`
- [OKX exchange](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/exchanges/okx.py): `astra_backend/exchanges/okx.py`

### Web control plane

- [Trading workstation](https://github.com/0xethanq/astra-quant-agent/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Backend API](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_backend/app.py): `astra_backend/app.py`
- [Dashboard data](https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/dashboard_payload): `astra_backend/dashboard_payload`
- [Admin routes](https://github.com/0xethanq/astra-quant-agent/tree/main/astra_backend/routers): `astra_backend/routers`

### Gateway and delivery

- [Delivery queue](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/store.py): `astra_gateway/store.py`
- [Event publisher](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/publisher.py): `astra_gateway/publisher.py`
- [Notification channels](https://github.com/0xethanq/astra-quant-agent/blob/main/astra_gateway/channels.py): `astra_gateway/channels.py`

### Other components

- **Operator**
- **OKX service**

## Connections

- Cycle scheduler → Market data: schedules (evidence: `README.md`)
- Cycle scheduler → Trading brain: schedules (evidence: `README.md`)
- Cycle scheduler → Strategy evolution: schedules (evidence: `README.md`)
- Market data → Factor calculus: feeds (evidence: `README.md`)
- Instrument universe → Factor calculus: constrains (evidence: `README.md`)
- Trading brain → Model committee: requests debate (evidence: `README.md`)
- Trading brain → Prompt library: uses prompts (evidence: `README.md`)
- Model committee → LLM runtime: calls models (evidence: `README.md`)
- Trading brain → Risk gates: submits intent (evidence: `README.md`)
- Risk gates → Circuit breaker: checks exposure (evidence: `README.md`)
- Trading brain → Order lifecycle: dispatches intent (evidence: `README.md`)
- Order lifecycle → OKX exchange: submits orders (evidence: `README.md`)
- OKX exchange → OKX service: executes on (evidence: `README.md`)
- Strategy evolution → Policy snapshots: updates policy (evidence: `README.md`)
- Operator → Trading workstation: uses
- Trading workstation → Backend API: requests data
- Backend API → Dashboard data: serves (evidence: `astra_backend/app.py`)
- Backend API → Admin routes: mounts routes (evidence: `astra_backend/app.py`)
- Event publisher → Delivery queue: enqueues events (evidence: `astra_gateway/publisher.py`)
- Gateway worker → Delivery queue: claims deliveries (evidence: `astra_gateway/worker.py`)
- Gateway worker → Notification channels: sends delivery (evidence: `astra_gateway/worker.py`)
