# the-steelix-flame/chronos architecture

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

- Interactive diagram: https://gitdiagram.com/the-steelix-flame/chronos
- Repository: https://github.com/the-steelix-flame/chronos

## Overview

Chronos simulates an impact-aware market: a user starts a run or submits a strategy, agents and strategies trade against a live matching engine, and market data and outcomes return to the dashboard. The graph reflects README-described integrations where their implementation was not sampled; those subsystem links use only documented paths. The separate Vite frontend is documented as an older, unwired interface.

Main entry points: [`swarm_orchestrator/engine/server.py`](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/server.py) (Engine Transport), [`swarm_orchestrator/bridge.py`](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/bridge.py) (HTTP / WS Bridge), [`swarm_orchestrator/engine/matching_engine.py`](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/matching_engine.py) (Matching Engine), [`swarm_orchestrator/oracle.py`](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/oracle.py) (Macro Oracle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interfaces"]
  node_terminal["Chronos Dashboard<br/>[app.js]"]
  node_legacy_frontend["Legacy Frontend<br/>[App.jsx]"]
  node_bridge["HTTP / WS Bridge<br/>[bridge.py]"]
end

subgraph group_market["Market Runtime"]
  node_engine["Matching Engine<br/>[matching_engine.py]"]
  node_transport["Engine Transport<br/>[server.py]"]
  node_persistence["Run Persistence<br/>[persistence.py]"]
end

subgraph group_participants["Trading Participants"]
  node_swarm["Swarm Orchestrator<br/>[loop_manager.py]"]
  node_engine_client["Engine Client<br/>[engine_client.py]"]
  node_agents["Agent Population"]
  node_oracle["Macro Oracle<br/>[oracle.py]"]
end

subgraph group_strategies["Strategy Execution"]
  node_scripts_api["Script API<br/>[routes_scripts.py]"]
  node_script_store[("Script Library<br/>[script_store.py]")]
  node_sandbox["Strategy Sandbox<br/>[sandbox.py]"]
  node_sdk["Strategy SDK<br/>[sdk.py]"]
  node_fix["FIX Gateway<br/>[fix_gateway.py]"]
end

subgraph group_insights["Features And Results"]
  node_feature_api["Feature API<br/>[routes_features.py]"]
  node_feature_modules["Market Features"]
  node_results_api["Results API<br/>[routes_results.py]"]
  node_results_store[("Results Store<br/>[results.py]")]
end

node_user(("User"))
node_sqlite[("SQLite")]
node_gemini["Gemini Service"]

node_user -->|"uses"| node_terminal
node_user -->|"controls"| node_bridge
node_terminal -->|"REST / WS"| node_bridge
node_legacy_frontend -.->|"legacy WS"| node_bridge
node_bridge -->|"control requests"| node_transport
node_transport -->|"dispatches"| node_engine
node_engine -->|"publications"| node_transport
node_transport -->|"market data"| node_bridge
node_engine -->|"writes run data"| node_persistence
node_persistence -->|"stores"| node_sqlite
node_swarm -->|"drives"| node_agents
node_swarm -->|"uses"| node_engine_client
node_engine_client -->|"orders / control"| node_transport
node_transport -->|"market feed / acks"| node_engine_client
node_bridge -->|"scores news"| node_oracle
node_oracle -.->|"requests scoring"| node_gemini
node_oracle -->|"submits orders"| node_transport
node_bridge -->|"script endpoints"| node_scripts_api
node_scripts_api -->|"reads / writes"| node_script_store
node_scripts_api -->|"launches script"| node_sandbox
node_sandbox -->|"runs strategy"| node_sdk
node_sdk -->|"submits orders"| node_transport
node_fix -.->|"FIX orders"| node_transport
node_bridge -->|"feature endpoints"| node_feature_api
node_feature_api -->|"invokes features"| node_feature_modules
node_feature_api -->|"starts replay"| node_transport
node_bridge -->|"results endpoints"| node_results_api
node_results_api -->|"queries results"| node_results_store

click node_terminal "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/dashboard/app.js"
click node_legacy_frontend "https://github.com/the-steelix-flame/chronos/blob/main/frontend/src/App.jsx"
click node_bridge "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/bridge.py"
click node_engine "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/matching_engine.py"
click node_transport "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/server.py"
click node_persistence "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/persistence.py"
click node_swarm "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/core/loop_manager.py"
click node_engine_client "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/core/engine_client.py"
click node_agents "https://github.com/the-steelix-flame/chronos/tree/main/swarm_orchestrator/agents"
click node_oracle "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/oracle.py"
click node_scripts_api "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/routes_scripts.py"
click node_script_store "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/script_store.py"
click node_sandbox "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/sandbox.py"
click node_sdk "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/sdk.py"
click node_fix "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/fix_gateway.py"
click node_feature_api "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/features/routes_features.py"
click node_feature_modules "https://github.com/the-steelix-flame/chronos/tree/main/swarm_orchestrator/features"
click node_results_api "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/routes_results.py"
click node_results_store "https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/results.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_terminal,node_legacy_frontend,node_bridge,node_user toneBlue
class node_engine,node_transport,node_persistence,node_sqlite toneAmber
class node_swarm,node_engine_client,node_agents,node_oracle toneMint
class node_scripts_api,node_script_store,node_sandbox,node_sdk,node_fix toneRose
class node_feature_api,node_feature_modules,node_results_api,node_results_store,node_gemini toneIndigo
```

## Components

### User Interfaces

- [Chronos Dashboard](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/dashboard/app.js): `swarm_orchestrator/dashboard/app.js`
- [Legacy Frontend](https://github.com/the-steelix-flame/chronos/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [HTTP / WS Bridge](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/bridge.py): `swarm_orchestrator/bridge.py`

### Market Runtime

- [Matching Engine](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/matching_engine.py): `swarm_orchestrator/engine/matching_engine.py`
- [Engine Transport](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/server.py): `swarm_orchestrator/engine/server.py`
- [Run Persistence](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/engine/persistence.py): `swarm_orchestrator/engine/persistence.py`

### Trading Participants

- [Swarm Orchestrator](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/core/loop_manager.py): `swarm_orchestrator/core/loop_manager.py`
- [Engine Client](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/core/engine_client.py): `swarm_orchestrator/core/engine_client.py`
- [Agent Population](https://github.com/the-steelix-flame/chronos/tree/main/swarm_orchestrator/agents): `swarm_orchestrator/agents`
- [Macro Oracle](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/oracle.py): `swarm_orchestrator/oracle.py`

### Strategy Execution

- [Script API](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/routes_scripts.py): `swarm_orchestrator/analytics/routes_scripts.py`
- [Script Library](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/script_store.py): `swarm_orchestrator/runner/script_store.py`
- [Strategy Sandbox](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/sandbox.py): `swarm_orchestrator/runner/sandbox.py`
- [Strategy SDK](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/sdk.py): `swarm_orchestrator/runner/sdk.py`
- [FIX Gateway](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/runner/fix_gateway.py): `swarm_orchestrator/runner/fix_gateway.py`

### Features And Results

- [Feature API](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/features/routes_features.py): `swarm_orchestrator/features/routes_features.py`
- [Market Features](https://github.com/the-steelix-flame/chronos/tree/main/swarm_orchestrator/features): `swarm_orchestrator/features`
- [Results API](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/routes_results.py): `swarm_orchestrator/analytics/routes_results.py`
- [Results Store](https://github.com/the-steelix-flame/chronos/blob/main/swarm_orchestrator/analytics/results.py): `swarm_orchestrator/analytics/results.py`

### Other components

- **User**
- **SQLite**
- **Gemini Service**

## Connections

- User → Chronos Dashboard: uses
- User → HTTP / WS Bridge: controls
- Chronos Dashboard → HTTP / WS Bridge: REST / WS
- Legacy Frontend → HTTP / WS Bridge: legacy WS
- HTTP / WS Bridge → Engine Transport: control requests
- Engine Transport → Matching Engine: dispatches
- Matching Engine → Engine Transport: publications
- Engine Transport → HTTP / WS Bridge: market data
- Matching Engine → Run Persistence: writes run data
- Run Persistence → SQLite: stores
- Swarm Orchestrator → Agent Population: drives
- Swarm Orchestrator → Engine Client: uses
- Engine Client → Engine Transport: orders / control
- Engine Transport → Engine Client: market feed / acks
- HTTP / WS Bridge → Macro Oracle: scores news
- Macro Oracle → Gemini Service: requests scoring
- Macro Oracle → Engine Transport: submits orders
- HTTP / WS Bridge → Script API: script endpoints
- Script API → Script Library: reads / writes
- Script API → Strategy Sandbox: launches script
- Strategy Sandbox → Strategy SDK: runs strategy
- Strategy SDK → Engine Transport: submits orders
- FIX Gateway → Engine Transport: FIX orders
- HTTP / WS Bridge → Feature API: feature endpoints
- Feature API → Market Features: invokes features
- Feature API → Engine Transport: starts replay
- HTTP / WS Bridge → Results API: results endpoints
- Results API → Results Store: queries results