# zadescoxp/calibrain-harness architecture

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

- Interactive diagram: https://gitdiagram.com/zadescoxp/calibrain-harness
- Repository: https://github.com/zadescoxp/calibrain-harness

## Overview

Calibrain Harness is a testnet-only trading and model-evaluation system. A closed-bar decision is orchestrated by the engine: it builds market state, requests model forecasts, applies calibration and policy, optionally executes a trade, then labels and evaluates every forecast. The terminal exposes monitoring, controls, reports, validation and trade history. Major evaluation and news capabilities are included from the README and source index; unsampled implementation details are not expanded into speculative call chains.

Main entry points: [`ctb/engine.py`](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/engine.py) (Decision orchestrator), [`ctb/server.py`](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/server.py) (HTTP and WebSocket API), [`ctb/db.py`](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/db.py) (SQLite records), [`ctb/broker/executor.py`](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/executor.py) (Testnet executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market data"]
  node_market_feeds["Market feed clients<br/>[bybit_public.py]"]
  node_market_store["Market state<br/>[store.py]"]
  node_news["News forecasts<br/>[news.py]"]
end

subgraph group_decision["Forecast and policy"]
  node_engine["Decision orchestrator<br/>[engine.py]"]
  node_feature_state["Feature state builder<br/>[features.py]"]
  node_questions["Forecast questions<br/>[questions.py]"]
  node_model_clients["Model clients<br/>[client.py]"]
  node_calibration["Probability calibration<br/>[calibration.py]"]
  node_policy["Trade policy<br/>[policy.py]"]
end

subgraph group_trading["Execution and records"]
  node_executor["Testnet executor<br/>[executor.py]"]
  node_bybit_rest["Bybit testnet REST<br/>[bybit_rest.py]"]
  node_private_ws["Account WebSocket"]
  node_db[("SQLite records<br/>[db.py]")]
end

subgraph group_evaluation["Evaluation"]
  node_labeler["Outcome labeler<br/>[labeler.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_validation["Independent validation<br/>[validation.py]"]
  node_report["Evaluation report<br/>[report.py]"]
end

subgraph group_interface["Terminal and API"]
  node_terminal["Trading terminal<br/>[Terminal.tsx]"]
  node_views["Terminal views<br/>[Views.tsx]"]
  node_monitor["Market monitor<br/>[Monitor.tsx]"]
  node_ui_data["UI data client<br/>[data.ts]"]
  node_server["HTTP and WebSocket API<br/>[server.py]"]
end

node_operator(("Operator"))
node_model_providers{{"Kairos and Jev APIs"}}

node_operator -->|"uses"| node_terminal
node_terminal -->|"selects views"| node_views
node_views -->|"renders"| node_monitor
node_terminal -.->|"loads data"| node_ui_data
node_ui_data -.->|"requests API"| node_server
node_server -->|"controls and streams"| node_engine
node_engine -->|"reads market state"| node_market_store
node_market_feeds -->|"feeds updates"| node_market_store
node_engine -->|"builds forecast state"| node_feature_state
node_feature_state -->|"reads bars and context"| node_market_store
node_engine -->|"asks questions"| node_questions
node_engine -->|"requests forecasts"| node_model_clients
node_model_clients -->|"calls model API"| node_model_providers
node_engine -->|"refits weights"| node_calibration
node_engine -->|"evaluates forecasts"| node_policy
node_engine -->|"submits eligible trades"| node_executor
node_executor -->|"places and reconciles orders"| node_bybit_rest
node_executor -.->|"uses account stream"| node_private_ws
node_engine -->|"records decisions"| node_db
node_executor -->|"records trades"| node_db
node_engine -->|"labels forecasts"| node_labeler
node_labeler -->|"reads and updates outcomes"| node_db
node_server -->|"computes evaluation"| node_metrics
node_server -->|"computes validation"| node_validation
node_server -->|"renders report"| node_report
node_metrics -->|"reads records"| node_db
node_validation -->|"reads records"| node_db
node_engine -->|"uses news forecasts"| node_news
node_news -.->|"adds news context"| node_market_store

click node_terminal "https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Terminal.tsx"
click node_views "https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Views.tsx"
click node_monitor "https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Monitor.tsx"
click node_ui_data "https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/lib/data.ts"
click node_server "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/server.py"
click node_engine "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/engine.py"
click node_market_feeds "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/market/bybit_public.py"
click node_market_store "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/market/store.py"
click node_feature_state "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/features.py"
click node_questions "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/questions.py"
click node_model_clients "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/client.py"
click node_calibration "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/calibration.py"
click node_policy "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/policy.py"
click node_executor "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/executor.py"
click node_bybit_rest "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/bybit_rest.py"
click node_private_ws "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/bybit_private_ws.py"
click node_db "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/db.py"
click node_labeler "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/labeler.py"
click node_metrics "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/metrics.py"
click node_validation "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/validation.py"
click node_report "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/report.py"
click node_news "https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/news.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_feeds,node_market_store,node_news toneBlue
class node_engine,node_feature_state,node_questions,node_model_clients,node_calibration,node_policy toneAmber
class node_executor,node_bybit_rest,node_private_ws,node_db,node_model_providers toneMint
class node_labeler,node_metrics,node_validation,node_report toneRose
class node_terminal,node_views,node_monitor,node_ui_data,node_server,node_operator toneIndigo
```

## Components

### Market data

- [Market feed clients](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/market/bybit_public.py): `ctb/market/bybit_public.py`
- [Market state](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/market/store.py): `ctb/market/store.py`
- [News forecasts](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/news.py): `ctb/kairos/news.py`

### Forecast and policy

- [Decision orchestrator](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/engine.py): `ctb/engine.py`
- [Feature state builder](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/features.py): `ctb/features.py`
- [Forecast questions](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/questions.py): `ctb/kairos/questions.py`
- [Model clients](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/kairos/client.py): `ctb/kairos/client.py`
- [Probability calibration](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/calibration.py): `ctb/calibration.py`
- [Trade policy](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/policy.py): `ctb/policy.py`

### Execution and records

- [Testnet executor](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/executor.py): `ctb/broker/executor.py`
- [Bybit testnet REST](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/bybit_rest.py): `ctb/broker/bybit_rest.py`
- [Account WebSocket](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/broker/bybit_private_ws.py): `ctb/broker/bybit_private_ws.py`
- [SQLite records](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/db.py): `ctb/db.py`

### Evaluation

- [Outcome labeler](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/labeler.py): `ctb/evaluation/labeler.py`
- [Evaluation metrics](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/metrics.py): `ctb/evaluation/metrics.py`
- [Independent validation](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/validation.py): `ctb/evaluation/validation.py`
- [Evaluation report](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/evaluation/report.py): `ctb/evaluation/report.py`

### Terminal and API

- [Trading terminal](https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Terminal.tsx): `web-next/components/Terminal.tsx`
- [Terminal views](https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Views.tsx): `web-next/components/Views.tsx`
- [Market monitor](https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/components/Monitor.tsx): `web-next/components/Monitor.tsx`
- [UI data client](https://github.com/zadescoxp/calibrain-harness/blob/master/web-next/lib/data.ts): `web-next/lib/data.ts`
- [HTTP and WebSocket API](https://github.com/zadescoxp/calibrain-harness/blob/master/ctb/server.py): `ctb/server.py`

### Other components

- **Operator**
- **Kairos and Jev APIs**

## Connections

- Operator → Trading terminal: uses (evidence: `README.md`)
- Trading terminal → Terminal views: selects views (evidence: `web-next/components/Views.tsx`)
- Terminal views → Market monitor: renders (evidence: `web-next/components/Views.tsx`)
- Trading terminal → UI data client: loads data
- UI data client → HTTP and WebSocket API: requests API
- HTTP and WebSocket API → Decision orchestrator: controls and streams (evidence: `ctb/server.py`)
- Decision orchestrator → Market state: reads market state (evidence: `ctb/engine.py`)
- Market feed clients → Market state: feeds updates (evidence: `ctb/market/store.py`)
- Decision orchestrator → Feature state builder: builds forecast state (evidence: `ctb/engine.py`)
- Feature state builder → Market state: reads bars and context (evidence: `ctb/features.py`)
- Decision orchestrator → Forecast questions: asks questions (evidence: `ctb/engine.py`)
- Decision orchestrator → Model clients: requests forecasts (evidence: `ctb/engine.py`)
- Model clients → Kairos and Jev APIs: calls model API (evidence: `README.md`)
- Decision orchestrator → Probability calibration: refits weights (evidence: `ctb/engine.py`)
- Decision orchestrator → Trade policy: evaluates forecasts (evidence: `ctb/policy.py`)
- Decision orchestrator → Testnet executor: submits eligible trades (evidence: `ctb/engine.py`)
- Testnet executor → Bybit testnet REST: places and reconciles orders (evidence: `ctb/broker/executor.py`)
- Testnet executor → Account WebSocket: uses account stream
- Decision orchestrator → SQLite records: records decisions (evidence: `ctb/engine.py`)
- Testnet executor → SQLite records: records trades (evidence: `ctb/broker/executor.py`)
- Decision orchestrator → Outcome labeler: labels forecasts (evidence: `ctb/engine.py`)
- Outcome labeler → SQLite records: reads and updates outcomes (evidence: `ctb/evaluation/labeler.py`)
- HTTP and WebSocket API → Evaluation metrics: computes evaluation (evidence: `ctb/server.py`)
- HTTP and WebSocket API → Independent validation: computes validation (evidence: `ctb/server.py`)
- HTTP and WebSocket API → Evaluation report: renders report (evidence: `ctb/server.py`)
- Evaluation metrics → SQLite records: reads records (evidence: `ctb/evaluation/metrics.py`)
- Independent validation → SQLite records: reads records (evidence: `ctb/evaluation/validation.py`)
- Decision orchestrator → News forecasts: uses news forecasts (evidence: `ctb/engine.py`)
- News forecasts → Market state: adds news context
