# xenon110/katanaquant architecture

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

- Interactive diagram: https://gitdiagram.com/xenon110/katanaquant
- Repository: https://github.com/xenon110/katanaquant

## Overview

KatanaQuant is an automated stock-and-ETF trading system whose principal workflow turns market bars into a proposed trade, subjects it to a deterministic safety gate, and routes approved orders to a broker before reconciling and recording execution. It also provides historical backtesting, a dashboard/API, scheduling, and optional notifications. The README documents the major pipeline stages; source-index references and excerpts support the central orchestration and execution links. Some integrations and web routes were not fully sampled, so uncertain connections are omitted or marked unverified.

Main entry points: [`src/web/app.py`](https://github.com/xenon110/katanaquant/blob/main/src/web/app.py) (Dashboard API), [`src/main.py`](https://github.com/xenon110/katanaquant/blob/main/src/main.py) (CLI Entry Point), [`src/execution/broker_client.py`](https://github.com/xenon110/katanaquant/blob/main/src/execution/broker_client.py) (Broker Interface), [`src/orchestrator/pipeline.py`](https://github.com/xenon110/katanaquant/blob/main/src/orchestrator/pipeline.py) (Trade Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market Inputs"]
  node_market_data["Market Data<br/>[market_data.py]"]
  node_stream["Live Bar Stream<br/>[alpaca_stream.py]"]
  node_indicators["Technical Indicators<br/>[indicators.py]"]
end

subgraph group_analysis["Trade Analysis"]
  node_rules["Quantitative Rules<br/>[rules.py]"]
  node_advisor["AI Advisor<br/>[ai_advisor.py]"]
  node_agents["Specialist Agents"]
  node_agent_framework["Agent Framework<br/>[base.py]"]
  node_orchestrator["Trade Orchestrator<br/>[pipeline.py]"]
end

subgraph group_safety["Safety and Execution"]
  node_risk_gate["Deterministic Risk Gate<br/>[gate.py]"]
  node_reconciliation["T+1 / PDT Reconciliation<br/>[service.py]"]
  node_broker_interface["Broker Interface<br/>[broker_client.py]"]
  node_alpaca["Alpaca Broker<br/>[alpaca_broker.py]"]
  node_dry_run["Dry-Run Broker<br/>[dry_run_broker.py]"]
  node_autonomous["Autonomous Trading"]
end

subgraph group_state["Records and Operations"]
  node_database[("SQLite Audit Store<br/>[database.py]")]
  node_supabase[("Supabase Storage<br/>[supabase_client.py]")]
  node_backtest["Backtesting Engine<br/>[engine.py]"]
  node_scheduler["Market Scheduler"]
end

subgraph group_interfaces["User Interfaces"]
  node_web["Dashboard API<br/>[app.py]"]
  node_cli["CLI Entry Point<br/>[main.py]"]
  node_telegram["Telegram Alerts<br/>[telegram.py]"]
end

node_trader(("Trader / Operator"))
node_broker_service["Broker Service"]
node_llm["LLM Provider"]

node_trader -->|"runs commands"| node_cli
node_trader -->|"uses dashboard"| node_web
node_cli -->|"fetches bars"| node_market_data
node_market_data -.->|"streams bars"| node_stream
node_market_data -->|"supplies bars"| node_rules
node_rules -->|"uses indicators"| node_indicators
node_rules -->|"provides signal"| node_orchestrator
node_orchestrator -->|"invokes agents"| node_agents
node_agents -->|"uses framework"| node_agent_framework
node_agent_framework -->|"requests analysis"| node_llm
node_orchestrator -->|"routes proposal"| node_risk_gate
node_cli -->|"runs pipeline"| node_orchestrator
node_risk_gate -->|"authorizes order"| node_broker_interface
node_broker_interface -->|"implements interface"| node_alpaca
node_broker_interface -->|"implements interface"| node_dry_run
node_alpaca -.->|"submits orders"| node_broker_service
node_dry_run -.->|"simulates orders"| node_broker_service
node_cli -->|"routes approved orders"| node_broker_interface
node_web -->|"validates orders"| node_risk_gate
node_web -->|"submits orders"| node_broker_interface
node_autonomous -.->|"controls trading"| node_broker_interface
node_broker_interface -.->|"provides fills"| node_reconciliation
node_reconciliation -.->|"supplies account state"| node_risk_gate
node_cli -->|"reconciles account"| node_reconciliation
node_cli -->|"records orders"| node_database
node_web -->|"uses audit store"| node_database
node_web -.->|"uses cloud storage"| node_supabase
node_cli -->|"runs backtest"| node_backtest
node_web -->|"runs backtest"| node_backtest
node_scheduler -.->|"supports scheduling"| node_web
node_web -->|"sends alerts"| node_telegram

click node_market_data "https://github.com/xenon110/katanaquant/blob/main/src/data/market_data.py"
click node_stream "https://github.com/xenon110/katanaquant/blob/main/src/data/alpaca_stream.py"
click node_indicators "https://github.com/xenon110/katanaquant/blob/main/src/data/indicators.py"
click node_rules "https://github.com/xenon110/katanaquant/blob/main/src/strategy/rules.py"
click node_advisor "https://github.com/xenon110/katanaquant/blob/main/src/strategy/ai_advisor.py"
click node_agents "https://github.com/xenon110/katanaquant/tree/main/src/agents"
click node_agent_framework "https://github.com/xenon110/katanaquant/blob/main/src/agents/base.py"
click node_orchestrator "https://github.com/xenon110/katanaquant/blob/main/src/orchestrator/pipeline.py"
click node_risk_gate "https://github.com/xenon110/katanaquant/blob/main/src/risk/gate.py"
click node_reconciliation "https://github.com/xenon110/katanaquant/blob/main/src/reconciliation/service.py"
click node_broker_interface "https://github.com/xenon110/katanaquant/blob/main/src/execution/broker_client.py"
click node_alpaca "https://github.com/xenon110/katanaquant/blob/main/src/execution/alpaca_broker.py"
click node_dry_run "https://github.com/xenon110/katanaquant/blob/main/src/execution/dry_run_broker.py"
click node_autonomous "https://github.com/xenon110/katanaquant/blob/main/src/execution/autonomous_trader.py"
click node_database "https://github.com/xenon110/katanaquant/blob/main/src/storage/database.py"
click node_supabase "https://github.com/xenon110/katanaquant/blob/main/src/storage/supabase_client.py"
click node_backtest "https://github.com/xenon110/katanaquant/blob/main/src/backtesting/engine.py"
click node_scheduler "https://github.com/xenon110/katanaquant/blob/main/src/scheduling/market_scheduler.py"
click node_web "https://github.com/xenon110/katanaquant/blob/main/src/web/app.py"
click node_cli "https://github.com/xenon110/katanaquant/blob/main/src/main.py"
click node_telegram "https://github.com/xenon110/katanaquant/blob/main/src/notifications/telegram.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_market_data,node_stream,node_indicators toneBlue
class node_rules,node_advisor,node_agents,node_agent_framework,node_orchestrator toneAmber
class node_risk_gate,node_reconciliation,node_broker_interface,node_alpaca,node_dry_run,node_autonomous toneMint
class node_database,node_supabase,node_backtest,node_scheduler toneRose
class node_web,node_cli,node_telegram,node_trader,node_broker_service,node_llm toneIndigo
```

## Components

### Market Inputs

- [Market Data](https://github.com/xenon110/katanaquant/blob/main/src/data/market_data.py): `src/data/market_data.py`
- [Live Bar Stream](https://github.com/xenon110/katanaquant/blob/main/src/data/alpaca_stream.py): `src/data/alpaca_stream.py`
- [Technical Indicators](https://github.com/xenon110/katanaquant/blob/main/src/data/indicators.py): `src/data/indicators.py`

### Trade Analysis

- [Quantitative Rules](https://github.com/xenon110/katanaquant/blob/main/src/strategy/rules.py): `src/strategy/rules.py`
- [AI Advisor](https://github.com/xenon110/katanaquant/blob/main/src/strategy/ai_advisor.py): `src/strategy/ai_advisor.py`
- [Specialist Agents](https://github.com/xenon110/katanaquant/tree/main/src/agents): `src/agents`
- [Agent Framework](https://github.com/xenon110/katanaquant/blob/main/src/agents/base.py): `src/agents/base.py`
- [Trade Orchestrator](https://github.com/xenon110/katanaquant/blob/main/src/orchestrator/pipeline.py): `src/orchestrator/pipeline.py`

### Safety and Execution

- [Deterministic Risk Gate](https://github.com/xenon110/katanaquant/blob/main/src/risk/gate.py): `src/risk/gate.py`
- [T+1 / PDT Reconciliation](https://github.com/xenon110/katanaquant/blob/main/src/reconciliation/service.py): `src/reconciliation/service.py`
- [Broker Interface](https://github.com/xenon110/katanaquant/blob/main/src/execution/broker_client.py): `src/execution/broker_client.py`
- [Alpaca Broker](https://github.com/xenon110/katanaquant/blob/main/src/execution/alpaca_broker.py): `src/execution/alpaca_broker.py`
- [Dry-Run Broker](https://github.com/xenon110/katanaquant/blob/main/src/execution/dry_run_broker.py): `src/execution/dry_run_broker.py`
- [Autonomous Trading](https://github.com/xenon110/katanaquant/blob/main/src/execution/autonomous_trader.py): `src/execution/autonomous_trader.py`

### Records and Operations

- [SQLite Audit Store](https://github.com/xenon110/katanaquant/blob/main/src/storage/database.py): `src/storage/database.py`
- [Supabase Storage](https://github.com/xenon110/katanaquant/blob/main/src/storage/supabase_client.py): `src/storage/supabase_client.py`
- [Backtesting Engine](https://github.com/xenon110/katanaquant/blob/main/src/backtesting/engine.py): `src/backtesting/engine.py`
- [Market Scheduler](https://github.com/xenon110/katanaquant/blob/main/src/scheduling/market_scheduler.py): `src/scheduling/market_scheduler.py`

### User Interfaces

- [Dashboard API](https://github.com/xenon110/katanaquant/blob/main/src/web/app.py): `src/web/app.py`
- [CLI Entry Point](https://github.com/xenon110/katanaquant/blob/main/src/main.py): `src/main.py`
- [Telegram Alerts](https://github.com/xenon110/katanaquant/blob/main/src/notifications/telegram.py): `src/notifications/telegram.py`

### Other components

- **Trader / Operator**
- **Broker Service**
- **LLM Provider**

## Connections

- Trader / Operator → CLI Entry Point: runs commands (evidence: `README.md`)
- Trader / Operator → Dashboard API: uses dashboard (evidence: `src/web/app.py`)
- CLI Entry Point → Market Data: fetches bars (evidence: `src/main.py`)
- Market Data → Live Bar Stream: streams bars
- Market Data → Quantitative Rules: supplies bars (evidence: `README.md`)
- Quantitative Rules → Technical Indicators: uses indicators (evidence: `src/strategy/rules.py`)
- Quantitative Rules → Trade Orchestrator: provides signal (evidence: `src/orchestrator/pipeline.py`)
- Trade Orchestrator → Specialist Agents: invokes agents (evidence: `src/orchestrator/pipeline.py`)
- Specialist Agents → Agent Framework: uses framework (evidence: `src/agents/base.py`)
- Agent Framework → LLM Provider: requests analysis (evidence: `src/agents/base.py`)
- Trade Orchestrator → Deterministic Risk Gate: routes proposal (evidence: `src/orchestrator/pipeline.py`)
- CLI Entry Point → Trade Orchestrator: runs pipeline (evidence: `src/main.py`)
- Deterministic Risk Gate → Broker Interface: authorizes order (evidence: `README.md`)
- Broker Interface → Alpaca Broker: implements interface (evidence: `src/execution/alpaca_broker.py`)
- Broker Interface → Dry-Run Broker: implements interface (evidence: `src/execution/dry_run_broker.py`)
- Alpaca Broker → Broker Service: submits orders
- Dry-Run Broker → Broker Service: simulates orders
- CLI Entry Point → Broker Interface: routes approved orders (evidence: `src/main.py`)
- Dashboard API → Deterministic Risk Gate: validates orders (evidence: `src/web/app.py`)
- Dashboard API → Broker Interface: submits orders (evidence: `src/web/app.py`)
- Autonomous Trading → Broker Interface: controls trading
- Broker Interface → T+1 / PDT Reconciliation: provides fills
- T+1 / PDT Reconciliation → Deterministic Risk Gate: supplies account state
- CLI Entry Point → T+1 / PDT Reconciliation: reconciles account (evidence: `src/main.py`)
- CLI Entry Point → SQLite Audit Store: records orders (evidence: `src/main.py`)
- Dashboard API → SQLite Audit Store: uses audit store (evidence: `src/web/app.py`)
- Dashboard API → Supabase Storage: uses cloud storage (evidence: `src/web/app.py`)
- CLI Entry Point → Backtesting Engine: runs backtest (evidence: `src/main.py`)
- Dashboard API → Backtesting Engine: runs backtest (evidence: `src/web/app.py`)
- Market Scheduler → Dashboard API: supports scheduling (evidence: `src/web/app.py`)
- Dashboard API → Telegram Alerts: sends alerts (evidence: `src/web/app.py`)
