# race-engineering-center/ksana architecture

> Architecture diagram of the GitHub repository race-engineering-center/ksana, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/race-engineering-center/ksana
- Repository: https://github.com/race-engineering-center/ksana

## Overview

ksana is a Windows CLI for recording, replaying, and inspecting racing-simulator telemetry. Its main workflow detects a supported simulator, samples telemetry into compressed recording files, then replays those frames through simulator-compatible shared memory for downstream tools. The graph also shows inspection, simulator-specific adapters, and the shared-memory and file-format layers. Relationships for unsampled modules are included only where documented or named by the SOURCE INDEX; uncertain wiring is omitted.

Main entry points: [`src/commands/record.rs`](https://github.com/race-engineering-center/ksana/blob/main/src/commands/record.rs) (Recording command), [`src/commands/play.rs`](https://github.com/race-engineering-center/ksana/blob/main/src/commands/play.rs) (Playback command), [`src/sims/assettocorsa/connector.rs`](https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/connector.rs) (Assetto Corsa adapter), [`src/main.rs`](https://github.com/race-engineering-center/ksana/blob/main/src/main.rs) (CLI dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_cli["CLI dispatcher<br/>[main.rs]"]
  node_record["Recording command<br/>[record.rs]"]
  node_play["Playback command<br/>[play.rs]"]
  node_inspect["Inspect command<br/>[inspect.rs]"]
end

subgraph group_recording["Recording and format"]
  node_recording_file["Recording file"]
  node_file_format["Compressed frame format<br/>[io.rs]"]
end

subgraph group_simulators["Simulator adapters"]
  node_iracing_connector["iRacing connector<br/>[connector.rs]"]
  node_iracing_data["iRacing frame data<br/>[data.rs]"]
  node_iracing_player["iRacing player<br/>[player.rs]"]
  node_ac_connector["AC connector<br/>[connector.rs]"]
  node_ac_data["AC frame data<br/>[data.rs]"]
  node_assetto_adapter["Assetto Corsa adapter<br/>[connector.rs]"]
  node_assetto_data["Assetto Corsa data<br/>[data.rs]"]
  node_assetto_player["Assetto Corsa player<br/>[player.rs]"]
end

subgraph group_runtime["Shared-memory runtime"]
  node_ac_shmio["AC shared-memory I/O<br/>[shmio.rs]"]
  node_shared_memory["Windows shared memory<br/>[shm.rs]"]
  node_sleeper["Adaptive timing<br/>[sleeper.rs]"]
end

node_developer(("Developer"))
node_iracing_sim(("iRacing"))
node_assetto_sim(("Assetto Corsa / ACC"))
node_consumer(("Telemetry consumer"))

node_developer -->|"runs"| node_cli
node_cli -->|"dispatches"| node_record
node_cli -->|"dispatches"| node_play
node_cli -->|"dispatches"| node_inspect
node_record -->|"probes"| node_iracing_connector
node_record -->|"probes"| node_assetto_adapter
node_record -->|"saves frames"| node_file_format
node_record -->|"paces sampling"| node_sleeper
node_record -->|"writes"| node_recording_file
node_iracing_connector -->|"uses format"| node_iracing_data
node_iracing_connector -->|"reads"| node_shared_memory
node_iracing_sim -->|"exposes telemetry"| node_iracing_connector
node_assetto_adapter -->|"delegates"| node_ac_connector
node_assetto_adapter -->|"uses types"| node_assetto_data
node_assetto_adapter -->|"uses"| node_ac_shmio
node_ac_connector -->|"uses types"| node_ac_data
node_ac_connector -->|"reads pages"| node_ac_shmio
node_ac_shmio -->|"maps pages"| node_shared_memory
node_assetto_sim -->|"exposes telemetry"| node_assetto_adapter
node_play -->|"loads frames"| node_file_format
node_play -->|"selects by ID"| node_iracing_player
node_play -->|"selects by ID"| node_assetto_player
node_play -->|"paces playback"| node_sleeper
node_play -->|"reads"| node_recording_file
node_iracing_player -->|"decodes frames"| node_iracing_data
node_iracing_player -->|"writes telemetry"| node_shared_memory
node_assetto_player -->|"uses types"| node_assetto_data
node_assetto_player -->|"writes frames"| node_ac_shmio
node_consumer -->|"reads telemetry"| node_shared_memory
node_inspect -->|"reads metadata"| node_file_format
node_inspect -->|"reads"| node_recording_file

click node_cli "https://github.com/race-engineering-center/ksana/blob/main/src/main.rs"
click node_record "https://github.com/race-engineering-center/ksana/blob/main/src/commands/record.rs"
click node_play "https://github.com/race-engineering-center/ksana/blob/main/src/commands/play.rs"
click node_inspect "https://github.com/race-engineering-center/ksana/blob/main/src/commands/inspect.rs"
click node_file_format "https://github.com/race-engineering-center/ksana/blob/main/src/io.rs"
click node_iracing_connector "https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/connector.rs"
click node_iracing_data "https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/data.rs"
click node_iracing_player "https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/player.rs"
click node_ac_connector "https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/connector.rs"
click node_ac_data "https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/data.rs"
click node_ac_shmio "https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/shmio.rs"
click node_assetto_adapter "https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/connector.rs"
click node_assetto_data "https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/data.rs"
click node_assetto_player "https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/player.rs"
click node_shared_memory "https://github.com/race-engineering-center/ksana/blob/main/src/shm.rs"
click node_sleeper "https://github.com/race-engineering-center/ksana/blob/main/src/sleeper.rs"

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_record,node_play,node_inspect toneBlue
class node_recording_file,node_file_format toneAmber
class node_iracing_connector,node_iracing_data,node_iracing_player,node_ac_connector,node_ac_data,node_assetto_adapter,node_assetto_data,node_assetto_player toneMint
class node_ac_shmio,node_shared_memory,node_sleeper toneRose
class node_developer,node_iracing_sim,node_assetto_sim,node_consumer toneIndigo
```

## Components

### CLI workflows

- [CLI dispatcher](https://github.com/race-engineering-center/ksana/blob/main/src/main.rs): `src/main.rs`
- [Recording command](https://github.com/race-engineering-center/ksana/blob/main/src/commands/record.rs): `src/commands/record.rs`
- [Playback command](https://github.com/race-engineering-center/ksana/blob/main/src/commands/play.rs): `src/commands/play.rs`
- [Inspect command](https://github.com/race-engineering-center/ksana/blob/main/src/commands/inspect.rs): `src/commands/inspect.rs`

### Recording and format

- **Recording file**
- [Compressed frame format](https://github.com/race-engineering-center/ksana/blob/main/src/io.rs): `src/io.rs`

### Simulator adapters

- [iRacing connector](https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/connector.rs): `src/sims/iracing/connector.rs`
- [iRacing frame data](https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/data.rs): `src/sims/iracing/data.rs`
- [iRacing player](https://github.com/race-engineering-center/ksana/blob/main/src/sims/iracing/player.rs): `src/sims/iracing/player.rs`
- [AC connector](https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/connector.rs): `src/sims/ac/connector.rs`
- [AC frame data](https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/data.rs): `src/sims/ac/data.rs`
- [Assetto Corsa adapter](https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/connector.rs): `src/sims/assettocorsa/connector.rs`
- [Assetto Corsa data](https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/data.rs): `src/sims/assettocorsa/data.rs`
- [Assetto Corsa player](https://github.com/race-engineering-center/ksana/blob/main/src/sims/assettocorsa/player.rs): `src/sims/assettocorsa/player.rs`

### Shared-memory runtime

- [AC shared-memory I/O](https://github.com/race-engineering-center/ksana/blob/main/src/sims/ac/shmio.rs): `src/sims/ac/shmio.rs`
- [Windows shared memory](https://github.com/race-engineering-center/ksana/blob/main/src/shm.rs): `src/shm.rs`
- [Adaptive timing](https://github.com/race-engineering-center/ksana/blob/main/src/sleeper.rs): `src/sleeper.rs`

### Other components

- **Developer**
- **iRacing**
- **Assetto Corsa / ACC**
- **Telemetry consumer**

## Connections

- Developer → CLI dispatcher: runs (evidence: `README.md`)
- CLI dispatcher → Recording command: dispatches (evidence: `src/main.rs`)
- CLI dispatcher → Playback command: dispatches (evidence: `src/main.rs`)
- CLI dispatcher → Inspect command: dispatches (evidence: `src/main.rs`)
- Recording command → iRacing connector: probes (evidence: `src/commands/record.rs`)
- Recording command → Assetto Corsa adapter: probes (evidence: `src/commands/record.rs`)
- Recording command → Compressed frame format: saves frames (evidence: `src/commands/record.rs`)
- Recording command → Adaptive timing: paces sampling (evidence: `src/commands/record.rs`)
- Recording command → Recording file: writes (evidence: `README.md`)
- iRacing connector → iRacing frame data: uses format (evidence: `src/sims/iracing/connector.rs`)
- iRacing connector → Windows shared memory: reads (evidence: `src/sims/iracing/connector.rs`)
- iRacing → iRacing connector: exposes telemetry (evidence: `README.md`)
- Assetto Corsa adapter → AC connector: delegates (evidence: `src/sims/assettocorsa/connector.rs`)
- Assetto Corsa adapter → Assetto Corsa data: uses types (evidence: `src/sims/assettocorsa/connector.rs`)
- Assetto Corsa adapter → AC shared-memory I/O: uses (evidence: `src/sims/assettocorsa/connector.rs`)
- AC connector → AC frame data: uses types (evidence: `src/sims/ac/connector.rs`)
- AC connector → AC shared-memory I/O: reads pages (evidence: `src/sims/ac/connector.rs`)
- AC shared-memory I/O → Windows shared memory: maps pages (evidence: `src/sims/ac/shmio.rs`)
- Assetto Corsa / ACC → Assetto Corsa adapter: exposes telemetry (evidence: `README.md`)
- Playback command → Compressed frame format: loads frames (evidence: `src/commands/play.rs`)
- Playback command → iRacing player: selects by ID (evidence: `src/commands/play.rs`)
- Playback command → Assetto Corsa player: selects by ID (evidence: `src/commands/play.rs`)
- Playback command → Adaptive timing: paces playback (evidence: `src/commands/play.rs`)
- Playback command → Recording file: reads (evidence: `README.md`)
- iRacing player → iRacing frame data: decodes frames (evidence: `src/sims/iracing/player.rs`)
- iRacing player → Windows shared memory: writes telemetry (evidence: `src/sims/iracing/player.rs`)
- Assetto Corsa player → Assetto Corsa data: uses types (evidence: `src/sims/assettocorsa/player.rs`)
- Assetto Corsa player → AC shared-memory I/O: writes frames (evidence: `src/sims/assettocorsa/player.rs`)
- Telemetry consumer → Windows shared memory: reads telemetry (evidence: `README.md`)
- Inspect command → Compressed frame format: reads metadata (evidence: `src/commands/inspect.rs`)
- Inspect command → Recording file: reads (evidence: `README.md`)
