# s-ajensen/cask architecture

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

- Interactive diagram: https://gitdiagram.com/s-ajensen/cask
- Repository: https://github.com/s-ajensen/cask

## Overview

Cask is a modular Rust engine for running plugin-based interactive applications, including the museum example documented in the README. Its principal workflow is to discover and load plugins, initialize a shared world, and run their systems on a fixed-tick engine loop until shutdown. Foundation crates cover world simulation, content and rendering; tracing can be written to a file or streamed to the separate collector. The runner and engine flow are supported by sampled source; several foundation capabilities are represented from the tree and crate names, whose internal wiring was not sampled.

Main entry points: [`crates/engine/cask-run/src/main.rs`](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-run/src/main.rs) (Application runner), [`crates/engine/cask-engine/src/engine.rs`](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/engine.rs) (Tick engine), [`crates/engine/cask-engine/src/registry.rs`](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/registry.rs) (Plugin registry), [`crates/engine/cask-collect/src/main.rs`](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-collect/src/main.rs) (Trace collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_runner["Application runner<br/>[main.rs]"]
  node_registry["Plugin registry<br/>[registry.rs]"]
  node_plugin_system["Plugin systems<br/>[plugin_system.rs]"]
  node_engine["Tick engine<br/>[engine.rs]"]
  node_world["Shared world<br/>[world.rs]"]
end

subgraph group_simulation["World simulation"]
  node_ecs["Entity components<br/>[lib.rs]"]
  node_behavior["Behavior runtime<br/>[driver.rs]"]
  node_events["Event channels<br/>[event_channel.rs]"]
  node_input["Input handling<br/>[lib.rs]"]
  node_transform["Transforms"]
  node_physics["Physics simulation<br/>[simulation.rs]"]
  node_animation["Animation<br/>[lib.rs]"]
end

subgraph group_content["Content and assets"]
  node_resources["Resource loading<br/>[lib.rs]"]
  node_gltf["glTF import<br/>[lib.rs]"]
  node_obj["OBJ import<br/>[lib.rs]"]
  node_assembly["Scene assembly<br/>[lib.rs]"]
end

subgraph group_graphics["Rendering"]
  node_scenery["Scene data<br/>[lib.rs]"]
  node_renderer["GPU renderer<br/>[renderer.rs]"]
end

subgraph group_observability["Profiling"]
  node_trace["Trace recording<br/>[trace.rs]"]
  node_collector["Trace collector<br/>[main.rs]"]
  node_trace_store[("Collected traces<br/>[collection.rs]")]
  node_file_sink["Trace file"]
end

node_user(("Application operator"))
node_tcp_collector(("TCP collector"))

node_user -->|"starts run"| node_runner
node_runner -->|"loads plugins"| node_registry
node_runner -->|"initializes world"| node_registry
node_registry -->|"provides systems"| node_plugin_system
node_runner -->|"runs loop"| node_engine
node_engine -->|"ticks systems"| node_plugin_system
node_runner -->|"creates world"| node_world
node_runner -->|"opens profile"| node_trace
node_engine -->|"records spans"| node_trace
node_runner -->|"writes profile"| node_file_sink
node_runner -->|"streams profile"| node_tcp_collector
node_tcp_collector -->|"accepts stream"| node_collector
node_collector -->|"collects events"| node_trace_store

click node_runner "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-run/src/main.rs"
click node_registry "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/registry.rs"
click node_plugin_system "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/plugin_system.rs"
click node_engine "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/engine.rs"
click node_world "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/world.rs"
click node_ecs "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-ecs/src/lib.rs"
click node_behavior "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-behavior/src/driver.rs"
click node_events "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-events/src/event_channel.rs"
click node_input "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-input/src/lib.rs"
click node_transform "https://github.com/s-ajensen/cask/tree/master/crates/foundation/cask-transform"
click node_physics "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-physics/src/simulation.rs"
click node_animation "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-animation/src/lib.rs"
click node_resources "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-resource/src/lib.rs"
click node_gltf "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-gltf/src/lib.rs"
click node_obj "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-obj/src/lib.rs"
click node_assembly "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-assembly/src/lib.rs"
click node_scenery "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-scenery/src/lib.rs"
click node_renderer "https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-renderer/src/renderer.rs"
click node_trace "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-trace/src/trace.rs"
click node_collector "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-collect/src/main.rs"
click node_trace_store "https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-collect/src/collection.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_runner,node_registry,node_plugin_system,node_engine,node_world toneBlue
class node_ecs,node_behavior,node_events,node_input,node_transform,node_physics,node_animation toneAmber
class node_resources,node_gltf,node_obj,node_assembly toneMint
class node_scenery,node_renderer toneRose
class node_trace,node_collector,node_trace_store,node_file_sink,node_user,node_tcp_collector toneIndigo
```

## Components

### Runtime

- [Application runner](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-run/src/main.rs): `crates/engine/cask-run/src/main.rs`
- [Plugin registry](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/registry.rs): `crates/engine/cask-engine/src/registry.rs`
- [Plugin systems](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/plugin_system.rs): `crates/engine/cask-engine/src/plugin_system.rs`
- [Tick engine](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/engine.rs): `crates/engine/cask-engine/src/engine.rs`
- [Shared world](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-engine/src/world.rs): `crates/engine/cask-engine/src/world.rs`

### World simulation

- [Entity components](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-ecs/src/lib.rs): `crates/foundation/cask-ecs/src/lib.rs`
- [Behavior runtime](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-behavior/src/driver.rs): `crates/foundation/cask-behavior/src/driver.rs`
- [Event channels](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-events/src/event_channel.rs): `crates/foundation/cask-events/src/event_channel.rs`
- [Input handling](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-input/src/lib.rs): `crates/foundation/cask-input/src/lib.rs`
- [Transforms](https://github.com/s-ajensen/cask/tree/master/crates/foundation/cask-transform): `crates/foundation/cask-transform`
- [Physics simulation](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-physics/src/simulation.rs): `crates/foundation/cask-physics/src/simulation.rs`
- [Animation](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-animation/src/lib.rs): `crates/foundation/cask-animation/src/lib.rs`

### Content and assets

- [Resource loading](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-resource/src/lib.rs): `crates/foundation/cask-resource/src/lib.rs`
- [glTF import](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-gltf/src/lib.rs): `crates/foundation/cask-gltf/src/lib.rs`
- [OBJ import](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-obj/src/lib.rs): `crates/foundation/cask-obj/src/lib.rs`
- [Scene assembly](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-assembly/src/lib.rs): `crates/foundation/cask-assembly/src/lib.rs`

### Rendering

- [Scene data](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-scenery/src/lib.rs): `crates/foundation/cask-scenery/src/lib.rs`
- [GPU renderer](https://github.com/s-ajensen/cask/blob/master/crates/foundation/cask-renderer/src/renderer.rs): `crates/foundation/cask-renderer/src/renderer.rs`

### Profiling

- [Trace recording](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-trace/src/trace.rs): `crates/engine/cask-trace/src/trace.rs`
- [Trace collector](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-collect/src/main.rs): `crates/engine/cask-collect/src/main.rs`
- [Collected traces](https://github.com/s-ajensen/cask/blob/master/crates/engine/cask-collect/src/collection.rs): `crates/engine/cask-collect/src/collection.rs`
- **Trace file**

### Other components

- **Application operator**
- **TCP collector**

## Connections

- Application operator → Application runner: starts run
- Application runner → Plugin registry: loads plugins
- Application runner → Plugin registry: initializes world
- Plugin registry → Plugin systems: provides systems
- Application runner → Tick engine: runs loop
- Tick engine → Plugin systems: ticks systems
- Application runner → Shared world: creates world
- Application runner → Trace recording: opens profile
- Tick engine → Trace recording: records spans
- Application runner → Trace file: writes profile
- Application runner → TCP collector: streams profile
- TCP collector → Trace collector: accepts stream
- Trace collector → Collected traces: collects events