# justfixcode/asai architecture

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

- Interactive diagram: https://gitdiagram.com/justfixcode/asai
- Repository: https://github.com/justfixcode/asai

## Overview

ASAI is an explicitly unfinished, offline-first trading and research foundation—not a deployable trading system. Its main user workflow is supplying local evidence to the paper-control app, which loads a constrained manifest and produces an offline diagnostic; the separate research CLI validates local historical input, captures optional untrusted research text, and runs an SMA backtest. Risk and reconciliation are diagnostic components, not a verified broker execution boundary. Broker and quote adapters are independent, read-only integrations. The README documents additional SQL state and audit-history capabilities; unsampled wiring is omitted rather than inferred.

Main entry points: [`app/main.py`](https://github.com/justfixcode/asai/blob/main/app/main.py) (Paper orchestration), [`app/research_cli.py`](https://github.com/justfixcode/asai/blob/main/app/research_cli.py) (Research CLI), [`control/preflight.py`](https://github.com/justfixcode/asai/blob/main/control/preflight.py) (Control preflight), [`broker/alpaca_paper.py`](https://github.com/justfixcode/asai/blob/main/broker/alpaca_paper.py) (Alpaca paper adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Offline paper app"]
  node_paper_app["Paper orchestration<br/>[main.py]"]
  node_manifest["Manifest loader<br/>[manifest.py]"]
end

subgraph group_research["Offline research"]
  node_research_cli["Research CLI<br/>[research_cli.py]"]
  node_ingestion["Evidence capture<br/>[ingestion.py]"]
  node_backtest["SMA backtest<br/>[backtest.py]"]
  node_walk_forward["Walk-forward analysis<br/>[walk_forward.py]"]
  node_role_analysis["Offline role analysis"]
end

subgraph group_controls["Safety diagnostics"]
  node_preflight["Control preflight<br/>[preflight.py]"]
  node_risk["Risk evaluator<br/>[policy.py]"]
  node_reconciliation["Snapshot reconciliation<br/>[checker.py]"]
  node_paper_boundary["Paper order boundary"]
end

subgraph group_integrations["External evidence"]
  node_broker["Alpaca paper adapter<br/>[alpaca_paper.py]"]
  node_market_data["Latest quote adapter"]
end

subgraph group_state["Local state"]
  node_sqlite[("Local order journal<br/>[main.py]")]
  node_audit_store[("Review history<br/>[audit_store.py]")]
  node_postgres[("PostgreSQL research state")]
end

node_operator(("Operator"))
node_alpaca_paper(("Alpaca paper API"))
node_alpaca_data(("Alpaca market data"))

node_operator -->|"supplies evidence"| node_paper_app
node_paper_app -->|"loads settings"| node_manifest
node_paper_app -->|"records locally"| node_sqlite
node_operator -->|"supplies fixture"| node_research_cli
node_research_cli -->|"captures text"| node_ingestion
node_research_cli -->|"runs simulation"| node_backtest
node_preflight -->|"reconciles snapshots"| node_reconciliation
node_preflight -->|"evaluates risk"| node_risk
node_broker -->|"reads evidence"| node_alpaca_paper
node_market_data -->|"fetches quote"| node_alpaca_data

click node_paper_app "https://github.com/justfixcode/asai/blob/main/app/main.py"
click node_manifest "https://github.com/justfixcode/asai/blob/main/config/manifest.py"
click node_research_cli "https://github.com/justfixcode/asai/blob/main/app/research_cli.py"
click node_ingestion "https://github.com/justfixcode/asai/blob/main/research/ingestion.py"
click node_backtest "https://github.com/justfixcode/asai/blob/main/strategy/backtest.py"
click node_walk_forward "https://github.com/justfixcode/asai/blob/main/research/walk_forward.py"
click node_role_analysis "https://github.com/justfixcode/asai/blob/main/research/offline_role_analysis.py"
click node_preflight "https://github.com/justfixcode/asai/blob/main/control/preflight.py"
click node_risk "https://github.com/justfixcode/asai/blob/main/risk/policy.py"
click node_reconciliation "https://github.com/justfixcode/asai/blob/main/reconciliation/checker.py"
click node_paper_boundary "https://github.com/justfixcode/asai/blob/main/control/paper_order_boundary.py"
click node_broker "https://github.com/justfixcode/asai/blob/main/broker/alpaca_paper.py"
click node_market_data "https://github.com/justfixcode/asai/blob/main/market_data/alpaca_latest_quote.py"
click node_sqlite "https://github.com/justfixcode/asai/blob/main/app/main.py"
click node_audit_store "https://github.com/justfixcode/asai/blob/main/memory/audit_store.py"
click node_postgres "https://github.com/justfixcode/asai/tree/main/db"

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_paper_app,node_manifest toneBlue
class node_research_cli,node_ingestion,node_backtest,node_walk_forward,node_role_analysis toneAmber
class node_preflight,node_risk,node_reconciliation,node_paper_boundary,node_alpaca_paper toneMint
class node_broker,node_market_data toneRose
class node_sqlite,node_audit_store,node_postgres,node_operator,node_alpaca_data toneIndigo
```

## Components

### Offline paper app

- [Paper orchestration](https://github.com/justfixcode/asai/blob/main/app/main.py): `app/main.py`
- [Manifest loader](https://github.com/justfixcode/asai/blob/main/config/manifest.py): `config/manifest.py`

### Offline research

- [Research CLI](https://github.com/justfixcode/asai/blob/main/app/research_cli.py): `app/research_cli.py`
- [Evidence capture](https://github.com/justfixcode/asai/blob/main/research/ingestion.py): `research/ingestion.py`
- [SMA backtest](https://github.com/justfixcode/asai/blob/main/strategy/backtest.py): `strategy/backtest.py`
- [Walk-forward analysis](https://github.com/justfixcode/asai/blob/main/research/walk_forward.py): `research/walk_forward.py`
- [Offline role analysis](https://github.com/justfixcode/asai/blob/main/research/offline_role_analysis.py): `research/offline_role_analysis.py`

### Safety diagnostics

- [Control preflight](https://github.com/justfixcode/asai/blob/main/control/preflight.py): `control/preflight.py`
- [Risk evaluator](https://github.com/justfixcode/asai/blob/main/risk/policy.py): `risk/policy.py`
- [Snapshot reconciliation](https://github.com/justfixcode/asai/blob/main/reconciliation/checker.py): `reconciliation/checker.py`
- [Paper order boundary](https://github.com/justfixcode/asai/blob/main/control/paper_order_boundary.py): `control/paper_order_boundary.py`

### External evidence

- [Alpaca paper adapter](https://github.com/justfixcode/asai/blob/main/broker/alpaca_paper.py): `broker/alpaca_paper.py`
- [Latest quote adapter](https://github.com/justfixcode/asai/blob/main/market_data/alpaca_latest_quote.py): `market_data/alpaca_latest_quote.py`

### Local state

- [Local order journal](https://github.com/justfixcode/asai/blob/main/app/main.py): `app/main.py`
- [Review history](https://github.com/justfixcode/asai/blob/main/memory/audit_store.py): `memory/audit_store.py`
- [PostgreSQL research state](https://github.com/justfixcode/asai/tree/main/db): `db`

### Other components

- **Operator**
- **Alpaca paper API**
- **Alpaca market data**

## Connections

- Operator → Paper orchestration: supplies evidence (evidence: `app/main.py`)
- Paper orchestration → Manifest loader: loads settings (evidence: `app/main.py`)
- Paper orchestration → Local order journal: records locally (evidence: `app/main.py`)
- Operator → Research CLI: supplies fixture (evidence: `app/research_cli.py`)
- Research CLI → Evidence capture: captures text (evidence: `app/research_cli.py`)
- Research CLI → SMA backtest: runs simulation (evidence: `app/research_cli.py`)
- Control preflight → Snapshot reconciliation: reconciles snapshots (evidence: `control/preflight.py`)
- Control preflight → Risk evaluator: evaluates risk (evidence: `control/preflight.py`)
- Alpaca paper adapter → Alpaca paper API: reads evidence (evidence: `broker/alpaca_paper.py`)
- Latest quote adapter → Alpaca market data: fetches quote (evidence: `market_data/alpaca_latest_quote.py`)