# andrevazao/vazaosovereigntrader architecture

> Architecture diagram of the GitHub repository andrevazao/vazaosovereigntrader, 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/andrevazao/vazaosovereigntrader
- Repository: https://github.com/andrevazao/vazaosovereigntrader

## Overview

VazaoSovereignTrader is a local-first automated trading system: the PC engine gathers market data, forms PAPER signals, applies risk and execution controls, and exposes a local API; the Android app is its remote cockpit. Separate observation, research, evidence-learning, readiness, and shared-intelligence capabilities support that core. The graph follows documented workflows and sampled imports/calls; some subsystem links are omitted where implementation wiring was not shown.

Main entry points: [`PC_ENGINE/core/engine.py`](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/engine.py) (Trading engine), [`PC_ENGINE/services/paper_market_collector.py`](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/services/paper_market_collector.py) (PAPER collector), [`PC_ENGINE/radar/evidence_ledger.py`](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/radar/evidence_ledger.py) (Evidence ledger), [`PC_ENGINE/main.py`](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/main.py) (PC startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator control"]
  node_mobile["Mobile cockpit<br/>[main.py]"]
  node_local_api["Local control API<br/>[server.py]"]
  node_pc_entry["PC startup<br/>[main.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_trading["Trading runtime"]
  node_engine["Trading engine<br/>[engine.py]"]
  node_strategy["Strategy signals<br/>[strategy.py]"]
  node_patterns["Candlestick features"]
  node_confluence["PAPER confluence"]
  node_risk["Risk controls<br/>[risk.py]"]
  node_order_manager["Order management<br/>[order_manager.py]"]
  node_paper_broker["PAPER broker<br/>[paper_broker.py]"]
  node_exchange["Exchange clients<br/>[ccxt_client.py]"]
  node_ledger[("Audit ledger<br/>[ledger.py]")]
end

subgraph group_market["Market observation"]
  node_collector["PAPER collector"]
  node_radar["Market Radar<br/>[market_radar.py]"]
  node_websocket["Market streams"]
  node_opportunity["Capital opportunities"]
end

subgraph group_learning["Evidence and learning"]
  node_research_inbox["Research inbox<br/>[inbox.py]"]
  node_research_worker["Research worker<br/>[worker.py]"]
  node_evidence[("Evidence ledger<br/>[evidence_ledger.py]")]
  node_learning_loop["Evidence learning"]
  node_readiness["REAL readiness"]
end

subgraph group_services["Supporting services"]
  node_shared_api["Shared intelligence API<br/>[_lib.ts]"]
  node_blob_store[("Private artifact storage")]
end

node_operator(("Operator"))

node_operator -->|"controls"| node_mobile
node_mobile -->|"controls remotely"| node_local_api
node_pc_entry -->|"loads"| node_config
node_pc_entry -->|"starts"| node_engine
node_pc_entry -->|"serves"| node_local_api
node_local_api -->|"controls and reports"| node_engine
node_engine -->|"requests signals"| node_strategy
node_strategy -->|"uses features"| node_patterns
node_engine -->|"adds PAPER gates"| node_confluence
node_engine -.->|"checks risk"| node_risk
node_engine -->|"submits orders"| node_order_manager
node_order_manager -->|"simulates fills"| node_paper_broker
node_order_manager -.->|"places live orders"| node_exchange
node_engine -.->|"records activity"| node_ledger
node_engine -.->|"starts observation"| node_collector
node_collector -->|"collects observations"| node_radar
node_collector -->|"evaluates state"| node_confluence
node_collector -->|"records evidence"| node_evidence
node_websocket -.->|"feeds streams"| node_radar
node_radar -.->|"informs candidates"| node_opportunity
node_operator -->|"submits questions"| node_research_inbox
node_research_inbox -->|"queues requests"| node_research_worker
node_research_worker -.->|"evaluates own data"| node_evidence
node_learning_loop -->|"reads evidence"| node_evidence
node_readiness -->|"reviews evidence"| node_evidence
node_learning_loop -.->|"syncs artifacts"| node_shared_api
node_shared_api -->|"reads and writes"| node_blob_store

click node_mobile "https://github.com/andrevazao/vazaosovereigntrader/blob/main/MOBILE_APP/main.py"
click node_local_api "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/api/server.py"
click node_pc_entry "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/main.py"
click node_config "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/config.py"
click node_engine "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/engine.py"
click node_strategy "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/strategy.py"
click node_patterns "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/candlestick_patterns.py"
click node_confluence "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/paper_confluence_engine.py"
click node_risk "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/risk.py"
click node_order_manager "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/order_manager.py"
click node_paper_broker "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/paper_broker.py"
click node_exchange "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/exchanges/ccxt_client.py"
click node_ledger "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/storage/ledger.py"
click node_collector "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/services/paper_market_collector.py"
click node_radar "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/radar/market_radar.py"
click node_websocket "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/market_events/websocket_collectors.py"
click node_opportunity "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/opportunity/capital_opportunity.py"
click node_research_inbox "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/research/inbox.py"
click node_research_worker "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/research/worker.py"
click node_evidence "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/radar/evidence_ledger.py"
click node_learning_loop "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/learning/evidence_learning_loop.py"
click node_readiness "https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/real_readiness_service.py"
click node_shared_api "https://github.com/andrevazao/vazaosovereigntrader/blob/main/services/shared-intelligence-api/app/api/v1/intelligence/_lib.ts"

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_mobile,node_local_api,node_pc_entry,node_config toneBlue
class node_engine,node_strategy,node_patterns,node_confluence,node_risk,node_order_manager,node_paper_broker,node_exchange,node_ledger toneAmber
class node_collector,node_radar,node_websocket,node_opportunity toneMint
class node_research_inbox,node_research_worker,node_evidence,node_learning_loop,node_readiness toneRose
class node_shared_api,node_blob_store,node_operator toneIndigo
```

## Components

### Operator control

- [Mobile cockpit](https://github.com/andrevazao/vazaosovereigntrader/blob/main/MOBILE_APP/main.py): `MOBILE_APP/main.py`
- [Local control API](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/api/server.py): `PC_ENGINE/api/server.py`
- [PC startup](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/main.py): `PC_ENGINE/main.py`
- [Runtime config](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/config.py): `PC_ENGINE/core/config.py`

### Trading runtime

- [Trading engine](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/engine.py): `PC_ENGINE/core/engine.py`
- [Strategy signals](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/strategy.py): `PC_ENGINE/core/strategy.py`
- [Candlestick features](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/candlestick_patterns.py): `PC_ENGINE/core/candlestick_patterns.py`
- [PAPER confluence](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/paper_confluence_engine.py): `PC_ENGINE/core/paper_confluence_engine.py`
- [Risk controls](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/risk.py): `PC_ENGINE/core/risk.py`
- [Order management](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/order_manager.py): `PC_ENGINE/core/order_manager.py`
- [PAPER broker](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/paper_broker.py): `PC_ENGINE/core/paper_broker.py`
- [Exchange clients](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/exchanges/ccxt_client.py): `PC_ENGINE/exchanges/ccxt_client.py`
- [Audit ledger](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/storage/ledger.py): `PC_ENGINE/storage/ledger.py`

### Market observation

- [PAPER collector](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/services/paper_market_collector.py): `PC_ENGINE/services/paper_market_collector.py`
- [Market Radar](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/radar/market_radar.py): `PC_ENGINE/radar/market_radar.py`
- [Market streams](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/market_events/websocket_collectors.py): `PC_ENGINE/market_events/websocket_collectors.py`
- [Capital opportunities](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/opportunity/capital_opportunity.py): `PC_ENGINE/opportunity/capital_opportunity.py`

### Evidence and learning

- [Research inbox](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/research/inbox.py): `PC_ENGINE/research/inbox.py`
- [Research worker](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/research/worker.py): `PC_ENGINE/research/worker.py`
- [Evidence ledger](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/radar/evidence_ledger.py): `PC_ENGINE/radar/evidence_ledger.py`
- [Evidence learning](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/learning/evidence_learning_loop.py): `PC_ENGINE/learning/evidence_learning_loop.py`
- [REAL readiness](https://github.com/andrevazao/vazaosovereigntrader/blob/main/PC_ENGINE/core/real_readiness_service.py): `PC_ENGINE/core/real_readiness_service.py`

### Supporting services

- [Shared intelligence API](https://github.com/andrevazao/vazaosovereigntrader/blob/main/services/shared-intelligence-api/app/api/v1/intelligence/_lib.ts): `services/shared-intelligence-api/app/api/v1/intelligence/_lib.ts`
- **Private artifact storage**

### Other components

- **Operator**

## Connections

- Operator → Mobile cockpit: controls (evidence: `README.md`)
- Mobile cockpit → Local control API: controls remotely (evidence: `README.md`)
- PC startup → Runtime config: loads (evidence: `PC_ENGINE/main.py`)
- PC startup → Trading engine: starts (evidence: `PC_ENGINE/main.py`)
- PC startup → Local control API: serves (evidence: `PC_ENGINE/main.py`)
- Local control API → Trading engine: controls and reports (evidence: `PC_ENGINE/api/server.py`)
- Trading engine → Strategy signals: requests signals (evidence: `PC_ENGINE/core/engine.py`)
- Strategy signals → Candlestick features: uses features (evidence: `PC_ENGINE/core/strategy.py`)
- Trading engine → PAPER confluence: adds PAPER gates (evidence: `PC_ENGINE/core/paper_confluence_engine.py`)
- Trading engine → Risk controls: checks risk (evidence: `PC_ENGINE/core/engine.py`)
- Trading engine → Order management: submits orders (evidence: `PC_ENGINE/core/engine.py`)
- Order management → PAPER broker: simulates fills (evidence: `PC_ENGINE/core/order_manager.py`)
- Order management → Exchange clients: places live orders (evidence: `PC_ENGINE/core/order_manager.py`)
- Trading engine → Audit ledger: records activity (evidence: `PC_ENGINE/core/engine.py`)
- Trading engine → PAPER collector: starts observation (evidence: `PC_ENGINE/core/engine.py`)
- PAPER collector → Market Radar: collects observations (evidence: `PC_ENGINE/services/paper_market_collector.py`)
- PAPER collector → PAPER confluence: evaluates state (evidence: `PC_ENGINE/services/paper_market_collector.py`)
- PAPER collector → Evidence ledger: records evidence (evidence: `PC_ENGINE/services/paper_market_collector.py`)
- Market streams → Market Radar: feeds streams (evidence: `README.md`)
- Market Radar → Capital opportunities: informs candidates (evidence: `README.md`)
- Operator → Research inbox: submits questions (evidence: `README.md`)
- Research inbox → Research worker: queues requests (evidence: `PC_ENGINE/research/worker.py`)
- Research worker → Evidence ledger: evaluates own data (evidence: `README.md`)
- Evidence learning → Evidence ledger: reads evidence (evidence: `PC_ENGINE/learning/evidence_learning_loop.py`)
- REAL readiness → Evidence ledger: reviews evidence (evidence: `PC_ENGINE/core/real_readiness_service.py`)
- Evidence learning → Shared intelligence API: syncs artifacts (evidence: `README.md`)
- Shared intelligence API → Private artifact storage: reads and writes (evidence: `services/shared-intelligence-api/app/api/v1/intelligence/_lib.ts`)
