# asmodeus14/chronostack architecture

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

- Interactive diagram: https://gitdiagram.com/asmodeus14/chronostack
- Repository: https://github.com/asmodeus14/chronostack

## Overview

ChronoStack is a Docker Compose test-clock system. A user starts an isolated copy of a Compose project, advances its shared virtual clock, and verifies time-dependent behavior through service probes, job triggers and barriers; YAML scenarios can add faults and assertions and produce reports. The controller writes the shared clock page, which virtualized processes read, while the CLI coordinates the run. The README documents additional simulated-user, MCP and host-native Node capabilities. Some subsystem internals were not sampled, so links for those branches rely on README statements.

Main entry points: [`crates/cli/src/main.rs`](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/main.rs) (ChronoStack CLI), [`crates/users/src/engine.rs`](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/engine.rs) (Simulated users), [`crates/cli/src/engine.rs`](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/engine.rs) (Advance engine), [`crates/cli/src/scenario.rs`](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/scenario.rs) (Scenario runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_cli["ChronoStack CLI<br/>[main.rs]"]
  node_compose["Compose copy<br/>[compose.rs]"]
  node_session["Session state<br/>[session.rs]"]
  node_config["Run configuration<br/>[config.rs]"]
  node_engine["Advance engine<br/>[engine.rs]"]
  node_client["Controller client<br/>[client.rs]"]
end

subgraph group_clock["Virtual clock"]
  node_clockd["Clock controller<br/>[server.rs]"]
  node_clockpage[("Shared clock page<br/>[clock.rs]")]
  node_events[("Event log<br/>[events.rs]")]
  node_clockshim["Clock virtualization<br/>[chronoclock.c]"]
end

subgraph group_verify["Jobs and verification"]
  node_jobactions["Triggers and barriers<br/>[engine.rs]"]
  node_probes["Clock probes<br/>[probe.rs]"]
end

subgraph group_scenario["Scenarios and faults"]
  node_faults["Fault control<br/>[faults.rs]"]
  node_proxy["HTTP fault proxy<br/>[proxy.rs]"]
  node_scenario["Scenario runner<br/>[scenario.rs]"]
  node_reports["Run reports<br/>[report.rs]"]
end

subgraph group_extensions["Testing extensions"]
  node_users["Simulated users<br/>[engine.rs]"]
  node_journey["Journey validation<br/>[model.rs]"]
  node_arrival["Cohort arrivals<br/>[arrival.rs]"]
  node_templates["Journey templates<br/>[template.rs]"]
  node_rng["Seeded randomness<br/>[rng.rs]"]
  node_histogram["Latency metrics<br/>[histogram.rs]"]
  node_mcp["MCP tools<br/>[mcp.rs]"]
  node_node["Host-native Node<br/>[index.js]"]
end

node_user(("Engineer"))
node_services["Compose services"]

node_user -->|"runs commands"| node_cli
node_cli -->|"creates isolated copy"| node_compose
node_cli -->|"stores session"| node_session
node_cli -->|"loads settings"| node_config
node_cli -->|"invokes advance"| node_engine
node_engine -->|"controls clock"| node_client
node_client -->|"calls API"| node_clockd
node_clockd -->|"writes clock"| node_clockpage
node_clockd -->|"records changes"| node_events
node_clockpage -->|"shares virtual time"| node_clockshim
node_clockshim -->|"virtualizes wall time"| node_services
node_engine -->|"runs due work"| node_jobactions
node_jobactions -->|"triggers and waits"| node_services
node_engine -->|"probes services"| node_probes
node_probes -->|"checks virtual time"| node_services
node_cli -->|"runs scenarios"| node_scenario
node_scenario -->|"advances time"| node_engine
node_scenario -->|"sets scheduled faults"| node_faults
node_faults -->|"controls outages"| node_proxy
node_proxy -->|"intercepts HTTP"| node_services
node_scenario -->|"produces reports"| node_reports
node_cli -->|"runs cohorts"| node_users
node_users -->|"validates journeys"| node_journey
node_users -->|"schedules arrivals"| node_arrival
node_users -->|"renders steps"| node_templates
node_users -->|"draws seeded choices"| node_rng
node_users -->|"records latency"| node_histogram
node_cli -->|"serves tools"| node_mcp
node_node -->|"reads shared clock"| node_clockpage

click node_cli "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/main.rs"
click node_compose "https://github.com/asmodeus14/chronostack/blob/main/crates/core/src/compose.rs"
click node_session "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/session.rs"
click node_config "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/config.rs"
click node_engine "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/engine.rs"
click node_client "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/client.rs"
click node_clockd "https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/server.rs"
click node_clockpage "https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/clock.rs"
click node_events "https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/events.rs"
click node_clockshim "https://github.com/asmodeus14/chronostack/blob/main/shim/chronoclock.c"
click node_jobactions "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/engine.rs"
click node_probes "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/probe.rs"
click node_faults "https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/faults.rs"
click node_proxy "https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/proxy.rs"
click node_scenario "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/scenario.rs"
click node_reports "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/report.rs"
click node_users "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/engine.rs"
click node_journey "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/model.rs"
click node_arrival "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/arrival.rs"
click node_templates "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/template.rs"
click node_rng "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/rng.rs"
click node_histogram "https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/histogram.rs"
click node_mcp "https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/mcp.rs"
click node_node "https://github.com/asmodeus14/chronostack/blob/main/sdk/node/index.js"

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_cli,node_compose,node_session,node_config,node_engine,node_client toneBlue
class node_clockd,node_clockpage,node_events,node_clockshim toneAmber
class node_jobactions,node_probes toneMint
class node_faults,node_proxy,node_scenario,node_reports toneRose
class node_users,node_journey,node_arrival,node_templates,node_rng,node_histogram,node_mcp,node_node,node_user,node_services toneIndigo
```

## Components

### CLI orchestration

- [ChronoStack CLI](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Compose copy](https://github.com/asmodeus14/chronostack/blob/main/crates/core/src/compose.rs): `crates/core/src/compose.rs`
- [Session state](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/session.rs): `crates/cli/src/session.rs`
- [Run configuration](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/config.rs): `crates/cli/src/config.rs`
- [Advance engine](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/engine.rs): `crates/cli/src/engine.rs`
- [Controller client](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/client.rs): `crates/cli/src/client.rs`

### Virtual clock

- [Clock controller](https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/server.rs): `crates/clockd/src/server.rs`
- [Shared clock page](https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/clock.rs): `crates/clockd/src/clock.rs`
- [Event log](https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/events.rs): `crates/clockd/src/events.rs`
- [Clock virtualization](https://github.com/asmodeus14/chronostack/blob/main/shim/chronoclock.c): `shim/chronoclock.c`

### Jobs and verification

- [Triggers and barriers](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/engine.rs): `crates/cli/src/engine.rs`
- [Clock probes](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/probe.rs): `crates/cli/src/probe.rs`

### Scenarios and faults

- [Fault control](https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/faults.rs): `crates/clockd/src/faults.rs`
- [HTTP fault proxy](https://github.com/asmodeus14/chronostack/blob/main/crates/clockd/src/proxy.rs): `crates/clockd/src/proxy.rs`
- [Scenario runner](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/scenario.rs): `crates/cli/src/scenario.rs`
- [Run reports](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/report.rs): `crates/cli/src/report.rs`

### Testing extensions

- [Simulated users](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/engine.rs): `crates/users/src/engine.rs`
- [Journey validation](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/model.rs): `crates/users/src/model.rs`
- [Cohort arrivals](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/arrival.rs): `crates/users/src/arrival.rs`
- [Journey templates](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/template.rs): `crates/users/src/template.rs`
- [Seeded randomness](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/rng.rs): `crates/users/src/rng.rs`
- [Latency metrics](https://github.com/asmodeus14/chronostack/blob/main/crates/users/src/histogram.rs): `crates/users/src/histogram.rs`
- [MCP tools](https://github.com/asmodeus14/chronostack/blob/main/crates/cli/src/mcp.rs): `crates/cli/src/mcp.rs`
- [Host-native Node](https://github.com/asmodeus14/chronostack/blob/main/sdk/node/index.js): `sdk/node/index.js`

### Other components

- **Engineer**
- **Compose services**

## Connections

- Engineer → ChronoStack CLI: runs commands
- ChronoStack CLI → Compose copy: creates isolated copy
- ChronoStack CLI → Session state: stores session (evidence: `crates/cli/src/main.rs`)
- ChronoStack CLI → Run configuration: loads settings (evidence: `crates/cli/src/main.rs`)
- ChronoStack CLI → Advance engine: invokes advance (evidence: `crates/cli/src/main.rs`)
- Advance engine → Controller client: controls clock (evidence: `crates/cli/src/engine.rs`)
- Controller client → Clock controller: calls API (evidence: `crates/cli/src/client.rs`)
- Clock controller → Shared clock page: writes clock (evidence: `crates/clockd/src/server.rs`)
- Clock controller → Event log: records changes (evidence: `crates/clockd/src/server.rs`)
- Shared clock page → Clock virtualization: shares virtual time
- Clock virtualization → Compose services: virtualizes wall time
- Advance engine → Triggers and barriers: runs due work (evidence: `crates/cli/src/engine.rs`)
- Triggers and barriers → Compose services: triggers and waits
- Advance engine → Clock probes: probes services (evidence: `crates/cli/src/engine.rs`)
- Clock probes → Compose services: checks virtual time
- ChronoStack CLI → Scenario runner: runs scenarios (evidence: `crates/cli/src/main.rs`)
- Scenario runner → Advance engine: advances time (evidence: `crates/cli/src/scenario.rs`)
- Scenario runner → Fault control: sets scheduled faults (evidence: `crates/cli/src/scenario.rs`)
- Fault control → HTTP fault proxy: controls outages (evidence: `crates/clockd/src/server.rs`)
- HTTP fault proxy → Compose services: intercepts HTTP
- Scenario runner → Run reports: produces reports (evidence: `crates/cli/src/scenario.rs`)
- ChronoStack CLI → Simulated users: runs cohorts
- Simulated users → Journey validation: validates journeys (evidence: `crates/users/src/engine.rs`)
- Simulated users → Cohort arrivals: schedules arrivals (evidence: `crates/users/src/engine.rs`)
- Simulated users → Journey templates: renders steps (evidence: `crates/users/src/engine.rs`)
- Simulated users → Seeded randomness: draws seeded choices (evidence: `crates/users/src/engine.rs`)
- Simulated users → Latency metrics: records latency (evidence: `crates/users/src/engine.rs`)
- ChronoStack CLI → MCP tools: serves tools (evidence: `crates/cli/src/main.rs`)
- Host-native Node → Shared clock page: reads shared clock
