# amruth-143/aegis-alpha architecture

> Architecture diagram of the GitHub repository amruth-143/aegis-alpha, 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/amruth-143/aegis-alpha
- Repository: https://github.com/amruth-143/aegis-alpha

## Overview

Aegis Alpha is a paper-trading research system: a bounded invocation reads market/account evidence, proposes defined-risk options spreads, subjects them to adversarial committee review and deterministic risk veto, and permits only a dry-run preview. Monitoring, durable provenance/replay, optional read-only MCP diagnostics, and the read-only Judge Mode dashboard are important supporting capabilities. Edges use README statements and shown callers/import references; several subsystem internals are unsampled, so uncertain wiring is omitted.

Main entry points: [`app/orchestration/coordinator.py`](https://github.com/amruth-143/aegis-alpha/blob/main/app/orchestration/coordinator.py) (Cycle coordinator), [`app/alpaca`](https://github.com/amruth-143/aegis-alpha/tree/main/app/alpaca) (Paper account and data), [`app/committee/engine.py`](https://github.com/amruth-143/aegis-alpha/blob/main/app/committee/engine.py) (Investment committee), [`app/strategies/strategy_engine.py`](https://github.com/amruth-143/aegis-alpha/blob/main/app/strategies/strategy_engine.py) (Spread proposals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market evidence"]
  node_alpaca["Paper account and data"]
  node_scanner["Options scanner<br/>[options_scanner.py]"]
  node_signals["Market signals<br/>[signal_engine.py]"]
end

subgraph group_decision["Trade decisions"]
  node_strategies["Spread proposals<br/>[strategy_engine.py]"]
  node_committee["Investment committee<br/>[engine.py]"]
  node_risk["Deterministic risk<br/>[risk_engine.py]"]
  node_ai["Optional AI advice"]
end

subgraph group_operations["Safe operations"]
  node_orchestrator["Cycle coordinator<br/>[coordinator.py]"]
  node_execution["Dry-run preview<br/>[executor.py]"]
  node_runtime["Bounded runtime<br/>[runtime.py]"]
  node_monitoring["Account monitoring<br/>[monitor_engine.py]"]
  node_mcp["Read-only MCP<br/>[service.py]"]
end

subgraph group_visibility["Audit and visibility"]
  node_database[("SQLite journal<br/>[state_store.py]")]
  node_certificates["Certificates and replay"]
  node_dashboard["Judge dashboard<br/>[streamlit_app.py]"]
end

node_operator(("Operator"))
node_market_service["Alpaca market service"]
node_mcp_service["Official MCP server"]

node_operator -->|"starts cycle"| node_orchestrator
node_orchestrator -->|"reads account"| node_alpaca
node_orchestrator -.->|"requests scan"| node_scanner
node_orchestrator -.->|"requests signal"| node_signals
node_orchestrator -.->|"requests proposals"| node_strategies
node_signals -->|"fetches bars"| node_alpaca
node_scanner -->|"reads options"| node_alpaca
node_strategies -->|"scans contracts"| node_scanner
node_strategies -->|"uses direction"| node_signals
node_orchestrator -->|"evaluates proposal"| node_committee
node_orchestrator -.->|"requests approval"| node_risk
node_committee -->|"reviews risk decision"| node_risk
node_committee -.->|"may request advocates"| node_ai
node_orchestrator -->|"requests preview"| node_execution
node_execution -->|"checks account"| node_alpaca
node_orchestrator -->|"builds snapshot"| node_monitoring
node_monitoring -->|"reads positions"| node_alpaca
node_runtime -->|"delegates cycles"| node_orchestrator
node_orchestrator -->|"may query diagnostics"| node_mcp
node_mcp -->|"opens stdio session"| node_mcp_service
node_alpaca -.->|"requests market data"| node_market_service
node_orchestrator -.->|"persists outcomes"| node_database
node_committee -.->|"records provenance"| node_certificates
node_certificates -.->|"stores certificates"| node_database
node_dashboard -.->|"reads evidence"| node_database
node_operator -->|"starts runtime"| node_runtime
node_operator -->|"opens views"| node_dashboard

click node_orchestrator "https://github.com/amruth-143/aegis-alpha/blob/main/app/orchestration/coordinator.py"
click node_alpaca "https://github.com/amruth-143/aegis-alpha/tree/main/app/alpaca"
click node_scanner "https://github.com/amruth-143/aegis-alpha/blob/main/app/scanner/options_scanner.py"
click node_signals "https://github.com/amruth-143/aegis-alpha/blob/main/app/signals/signal_engine.py"
click node_strategies "https://github.com/amruth-143/aegis-alpha/blob/main/app/strategies/strategy_engine.py"
click node_committee "https://github.com/amruth-143/aegis-alpha/blob/main/app/committee/engine.py"
click node_risk "https://github.com/amruth-143/aegis-alpha/blob/main/app/risk/risk_engine.py"
click node_execution "https://github.com/amruth-143/aegis-alpha/blob/main/app/execution/executor.py"
click node_runtime "https://github.com/amruth-143/aegis-alpha/blob/main/app/runtime/runtime.py"
click node_monitoring "https://github.com/amruth-143/aegis-alpha/blob/main/app/monitoring/monitor_engine.py"
click node_mcp "https://github.com/amruth-143/aegis-alpha/blob/main/app/mcp/service.py"
click node_ai "https://github.com/amruth-143/aegis-alpha/blob/main/app/ai/reasoning_engine.py"
click node_database "https://github.com/amruth-143/aegis-alpha/blob/main/app/database/state_store.py"
click node_certificates "https://github.com/amruth-143/aegis-alpha/tree/main/app/committee"
click node_dashboard "https://github.com/amruth-143/aegis-alpha/blob/main/dashboard/streamlit_app.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_alpaca,node_scanner,node_signals toneBlue
class node_strategies,node_committee,node_risk,node_ai toneAmber
class node_orchestrator,node_execution,node_runtime,node_monitoring,node_mcp,node_mcp_service toneMint
class node_database,node_certificates,node_dashboard toneRose
class node_operator,node_market_service toneIndigo
```

## Components

### Market evidence

- [Paper account and data](https://github.com/amruth-143/aegis-alpha/tree/main/app/alpaca): `app/alpaca`
- [Options scanner](https://github.com/amruth-143/aegis-alpha/blob/main/app/scanner/options_scanner.py): `app/scanner/options_scanner.py`
- [Market signals](https://github.com/amruth-143/aegis-alpha/blob/main/app/signals/signal_engine.py): `app/signals/signal_engine.py`

### Trade decisions

- [Spread proposals](https://github.com/amruth-143/aegis-alpha/blob/main/app/strategies/strategy_engine.py): `app/strategies/strategy_engine.py`
- [Investment committee](https://github.com/amruth-143/aegis-alpha/blob/main/app/committee/engine.py): `app/committee/engine.py`
- [Deterministic risk](https://github.com/amruth-143/aegis-alpha/blob/main/app/risk/risk_engine.py): `app/risk/risk_engine.py`
- [Optional AI advice](https://github.com/amruth-143/aegis-alpha/blob/main/app/ai/reasoning_engine.py): `app/ai/reasoning_engine.py`

### Safe operations

- [Cycle coordinator](https://github.com/amruth-143/aegis-alpha/blob/main/app/orchestration/coordinator.py): `app/orchestration/coordinator.py`
- [Dry-run preview](https://github.com/amruth-143/aegis-alpha/blob/main/app/execution/executor.py): `app/execution/executor.py`
- [Bounded runtime](https://github.com/amruth-143/aegis-alpha/blob/main/app/runtime/runtime.py): `app/runtime/runtime.py`
- [Account monitoring](https://github.com/amruth-143/aegis-alpha/blob/main/app/monitoring/monitor_engine.py): `app/monitoring/monitor_engine.py`
- [Read-only MCP](https://github.com/amruth-143/aegis-alpha/blob/main/app/mcp/service.py): `app/mcp/service.py`

### Audit and visibility

- [SQLite journal](https://github.com/amruth-143/aegis-alpha/blob/main/app/database/state_store.py): `app/database/state_store.py`
- [Certificates and replay](https://github.com/amruth-143/aegis-alpha/tree/main/app/committee): `app/committee`
- [Judge dashboard](https://github.com/amruth-143/aegis-alpha/blob/main/dashboard/streamlit_app.py): `dashboard/streamlit_app.py`

### Other components

- **Operator**
- **Alpaca market service**
- **Official MCP server**

## Connections

- Operator → Cycle coordinator: starts cycle
- Cycle coordinator → Paper account and data: reads account (evidence: `app/orchestration/coordinator.py`)
- Cycle coordinator → Options scanner: requests scan
- Cycle coordinator → Market signals: requests signal (evidence: `app/orchestration/coordinator.py`)
- Cycle coordinator → Spread proposals: requests proposals (evidence: `app/orchestration/coordinator.py`)
- Market signals → Paper account and data: fetches bars (evidence: `app/signals/signal_engine.py`)
- Options scanner → Paper account and data: reads options (evidence: `app/scanner/options_scanner.py`)
- Spread proposals → Options scanner: scans contracts (evidence: `app/strategies/strategy_engine.py`)
- Spread proposals → Market signals: uses direction (evidence: `app/strategies/strategy_engine.py`)
- Cycle coordinator → Investment committee: evaluates proposal (evidence: `app/orchestration/coordinator.py`)
- Cycle coordinator → Deterministic risk: requests approval (evidence: `app/orchestration/coordinator.py`)
- Investment committee → Deterministic risk: reviews risk decision (evidence: `app/committee/engine.py`)
- Investment committee → Optional AI advice: may request advocates
- Cycle coordinator → Dry-run preview: requests preview (evidence: `app/orchestration/coordinator.py`)
- Dry-run preview → Paper account and data: checks account (evidence: `app/execution/executor.py`)
- Cycle coordinator → Account monitoring: builds snapshot (evidence: `app/orchestration/coordinator.py`)
- Account monitoring → Paper account and data: reads positions (evidence: `app/monitoring/monitor_engine.py`)
- Bounded runtime → Cycle coordinator: delegates cycles (evidence: `app/runtime/runtime.py`)
- Cycle coordinator → Read-only MCP: may query diagnostics (evidence: `app/orchestration/coordinator.py`)
- Read-only MCP → Official MCP server: opens stdio session (evidence: `app/mcp/service.py`)
- Paper account and data → Alpaca market service: requests market data
- Cycle coordinator → SQLite journal: persists outcomes (evidence: `app/orchestration/coordinator.py`)
- Investment committee → Certificates and replay: records provenance (evidence: `app/committee/engine.py`)
- Certificates and replay → SQLite journal: stores certificates
- Judge dashboard → SQLite journal: reads evidence
- Operator → Bounded runtime: starts runtime
- Operator → Judge dashboard: opens views
