# ujjwalvivek/journey architecture

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

- Interactive diagram: https://gitdiagram.com/ujjwalvivek/journey
- Repository: https://github.com/ujjwalvivek/journey

## Overview

1. **Repository shape**
   - This is a Rust workspace centered on a 2D action game tech demo.
   - The workspace is split into reusable engine code, game/content code, audio-generation crates, release tooling, and a web distribution layer.

2. **Core architectural boundary: `engine/` vs `game/`**
   - `engine` is the reusable runtime/library layer and appears to be the main public API surface.
   - `game` is the content/application layer that implements the actual gameplay, scenes, player/enemy logic, level handling, and startup flow.
   - The README explicitly emphasizes a clean API from engine to game to avoid tight coupling.

3. **Engine subsystem**
   - `engine/src` is organized around the low-level runtime concerns of a 2D game engine: context, runtime, time, input, camera, physics, sprite/texture handling, animation, UI, audio, math, and atmosphere.
   - The engine uses `wgpu` for rendering, `winit` for window/input events, `egui` for UI, `gilrs` for gamepad input, `glam` for math, and `pollster` for async startup.
   - Shader assets live under `engine/assets/shaders`, so rendering is shader-driven and asset-backed rather than hard-coded.

4. **Simulation and rendering flow**
   - The architecture is described as data-oriented, trait-driven, and fixed-step.
   - A typical frame flows from platform events into input state, through fixed-step simulation/physics/time, and then into rendering via the engine’s context/runtime layers.
   - The presence of `physics.rs`, `time.rs`, and `runtime.rs` suggests the engine owns the deterministic update loop, while `camera.rs`, `sprite.rs`, and `texture_manager.rs` feed the render pass.

5. **Gameplay subsystem**
   - `game/src` contains the actual metroidvania gameplay: `player`, `enemy`, `projectile`, `scene`, `level`, `level_editor`, `start_sequence`, `benchmark`, and `config`.
   - There is a dedicated combat subsystem under `game/src/combat` with its own FSM, input buffering, and move definitions, which implies combat is treated as a separate gameplay domain.
   - `game/src/main.rs` is the executable entry point; `game/src/lib.rs` likely binds the game into the engine’s app trait.

6. **Input and controls**
   - Input is split between engine-level event capture and game-level action mapping.
   - `game/src/input.rs` and `game/src/combat/input_buffer.rs` indicate a layered control model: raw input comes from the engine, then game-specific actions and buffered combat timing are interpreted in gameplay code.
   - This is consistent with the README’s focus on jump buffering, coyote time, and precise parry timing.

7. **Audio stack**
   - Audio is intentionally decomposed into two crates: `resonance` and `cadence`.
   - `resonance` is the lower-level DSP/sound primitive layer, with modules like oscillator, envelope, buffer, LUT, and patch.
   - `cadence` is the higher-level sequencer/scene/track layer, likely used to generate or schedule music and procedural audio behavior.
   - The game asset tree also includes many `.ogg` effects and ambient/legacy audio, so runtime audio appears to combine authored samples with procedural synthesis/sequencing.

8. **Web distribution and browser integration**
   - `web/` is a Vite + TypeScript frontend used to run or package the WASM build in the browser.
   - The browser side includes TypeScript components for `cadence` and `resonance`, plus `shared-audio.ts` and a `resonance_worklet.js` file in `public`, which strongly suggests Web Audio integration through an audio worklet.
   - This layer acts as the browser host/glue, not the gameplay engine itself.

9. **Assets and content pipeline**
   - `game/assets` contains level data, player assets, effects, and audio files, so the gameplay crate owns most runtime content.
   - `engine/assets` contains shader sources, while `web/public` contains browser delivery artifacts like the audio worklet and redirects.
   - The architecture separates code-owned engine assets from game-owned content assets.

10. **Tooling and release infrastructure**
   - GitHub Actions workflows cover CI, deploy, and publishing, indicating the repo is built and released as both a Rust crate and an npm package.
   - `tools/release` is a substantial Go-based release pipeline with orchestration, semver, stats, and TUI support, so versioning/publishing is treated as its own subsystem.
   - `tools/versioning` appears to support release/version management separately from the main build.

11. **Documentation and developer experience**
   - `docs/` is a full mdBook-style documentation site with intro, API, technical docs, and audio docs.
   - The repository also includes Zed editor configuration, a Makefile, and release notes, implying the project is optimized for active iteration across Rust and TypeScript.

12. **What an architecture diagram should emphasize**
   - Show `game` depending on `engine`, with `engine` depending on platform/render/audio libraries.
   - Show `cadence` and `resonance` as a separate audio-generation stack that feeds runtime audio.
   - Show `web` as the browser host around the WASM build, and `tools/` plus GitHub Actions as the build/release pipeline around the product.

Main entry points: [`game/src/scene.rs`](https://github.com/ujjwalvivek/journey/blob/main/game/src/scene.rs) (Scene), [`engine/src/runtime.rs`](https://github.com/ujjwalvivek/journey/blob/main/engine/src/runtime.rs) (Runtime), [`engine/src/lib.rs`](https://github.com/ujjwalvivek/journey/blob/main/engine/src/lib.rs) (Engine API), [`game/src/lib.rs`](https://github.com/ujjwalvivek/journey/blob/main/game/src/lib.rs) (Game API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Engine"]
  node_engine_lib["Engine API<br/>engine facade<br/>[lib.rs]"]
  node_engine_runtime["Runtime<br/>engine loop<br/>[runtime.rs]"]
  node_engine_context["Context<br/>render ctx<br/>[context.rs]"]
  node_engine_input["Input<br/>event state<br/>[input.rs]"]
  node_engine_time["Time<br/>fixed step<br/>[time.rs]"]
  node_engine_physics["Physics<br/>simulation<br/>[physics.rs]"]
end

subgraph group_gameplay["Game"]
  node_game_main["Game Main<br/>exe entry<br/>[main.rs]"]
  node_game_lib["Game API<br/>app glue<br/>[lib.rs]"]
  node_game_scene["Scene<br/>world flow<br/>[scene.rs]"]
  node_game_player["Player<br/>character logic<br/>[player.rs]"]
  node_game_combat["Combat<br/>[mod.rs]"]
  node_game_level["Level<br/>[level.rs]"]
  node_game_audio["Game Audio<br/>content audio<br/>[audio.rs]"]
end

subgraph group_audio["Audio"]
  node_cadence_lib["Cadence<br/>sequencer<br/>[lib.rs]"]
  node_resonance_lib["Resonance<br/>dsp core<br/>[lib.rs]"]
  node_tools_audio["Audio Tool<br/>generator cli<br/>[main.rs]"]
end

subgraph group_web["Web"]
  node_web_main["Web Host<br/>browser app<br/>[main.ts]"]
  node_web_audio_ui["Audio UI<br/>browser glue<br/>[shared-audio.ts]"]
end

subgraph group_tooling["Tooling"]
  node_release_tool["Release Tool<br/>release pipeline<br/>[main.go]"]
  node_versioning_tool["Versioning<br/>semver tool<br/>[main.go]"]
end

subgraph group_docs["Docs"]
  node_docs_intro["Docs<br/>[SUMMARY.md]"]
end

node_game_main -->|"starts"| node_game_lib
node_game_lib -->|"uses"| node_engine_lib
node_game_lib -->|"drives"| node_game_scene
node_game_scene -->|"updates"| node_game_player
node_game_scene -->|"loads"| node_game_level
node_game_scene -->|"runs"| node_game_combat
node_game_scene -->|"triggers"| node_game_audio
node_game_combat -->|"buffers"| node_game_player
node_engine_runtime -->|"renders"| node_engine_context
node_engine_runtime -->|"polls"| node_engine_input
node_engine_runtime -->|"steps"| node_engine_time
node_engine_runtime -->|"simulates"| node_engine_physics
node_engine_lib -->|"exports"| node_engine_runtime
node_engine_lib -->|"exports"| node_engine_input
node_cadence_lib -->|"builds on"| node_resonance_lib
node_tools_audio -->|"generates"| node_cadence_lib
node_tools_audio -->|"renders"| node_resonance_lib
node_web_main -->|"hosts"| node_web_audio_ui
node_web_audio_ui -->|"adapts"| node_cadence_lib
node_web_audio_ui -->|"adapts"| node_resonance_lib
node_release_tool -->|"coordinates"| node_versioning_tool
node_docs_intro -->|"documents"| node_engine_lib
node_docs_intro -->|"documents"| node_cadence_lib
node_docs_intro -->|"documents"| node_game_lib

click node_engine_lib "https://github.com/ujjwalvivek/journey/blob/main/engine/src/lib.rs"
click node_engine_runtime "https://github.com/ujjwalvivek/journey/blob/main/engine/src/runtime.rs"
click node_engine_context "https://github.com/ujjwalvivek/journey/blob/main/engine/src/context.rs"
click node_engine_input "https://github.com/ujjwalvivek/journey/blob/main/engine/src/input.rs"
click node_engine_time "https://github.com/ujjwalvivek/journey/blob/main/engine/src/time.rs"
click node_engine_physics "https://github.com/ujjwalvivek/journey/blob/main/engine/src/physics.rs"
click node_game_main "https://github.com/ujjwalvivek/journey/blob/main/game/src/main.rs"
click node_game_lib "https://github.com/ujjwalvivek/journey/blob/main/game/src/lib.rs"
click node_game_scene "https://github.com/ujjwalvivek/journey/blob/main/game/src/scene.rs"
click node_game_player "https://github.com/ujjwalvivek/journey/blob/main/game/src/player.rs"
click node_game_combat "https://github.com/ujjwalvivek/journey/blob/main/game/src/combat/mod.rs"
click node_game_level "https://github.com/ujjwalvivek/journey/blob/main/game/src/level.rs"
click node_game_audio "https://github.com/ujjwalvivek/journey/blob/main/game/src/audio.rs"
click node_cadence_lib "https://github.com/ujjwalvivek/journey/blob/main/cadence/src/lib.rs"
click node_resonance_lib "https://github.com/ujjwalvivek/journey/blob/main/resonance/src/lib.rs"
click node_tools_audio "https://github.com/ujjwalvivek/journey/blob/main/tools/audio/src/main.rs"
click node_web_main "https://github.com/ujjwalvivek/journey/blob/main/web/src/main.ts"
click node_web_audio_ui "https://github.com/ujjwalvivek/journey/blob/main/web/src/components/shared-audio.ts"
click node_release_tool "https://github.com/ujjwalvivek/journey/blob/main/tools/release/main.go"
click node_versioning_tool "https://github.com/ujjwalvivek/journey/blob/main/tools/versioning/main.go"
click node_docs_intro "https://github.com/ujjwalvivek/journey/blob/main/docs/src/SUMMARY.md"

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_engine_lib,node_engine_runtime,node_engine_context,node_engine_input,node_engine_time,node_engine_physics toneBlue
class node_game_main,node_game_lib,node_game_scene,node_game_player,node_game_combat,node_game_level,node_game_audio toneAmber
class node_cadence_lib,node_resonance_lib,node_tools_audio toneMint
class node_web_main,node_web_audio_ui toneRose
class node_release_tool,node_versioning_tool toneIndigo
class node_docs_intro toneTeal
```

## Components

### Engine

Reusable runtime and low-level engine systems

- [Engine API](https://github.com/ujjwalvivek/journey/blob/main/engine/src/lib.rs): engine facade · Public engine surface that the game builds on · `engine/src/lib.rs`
- [Runtime](https://github.com/ujjwalvivek/journey/blob/main/engine/src/runtime.rs): engine loop · Owns startup and fixed-step execution flow · `engine/src/runtime.rs`
- [Context](https://github.com/ujjwalvivek/journey/blob/main/engine/src/context.rs): render ctx · Rendering and frame context boundary · `engine/src/context.rs`
- [Input](https://github.com/ujjwalvivek/journey/blob/main/engine/src/input.rs): event state · Platform and controller input capture · `engine/src/input.rs`
- [Time](https://github.com/ujjwalvivek/journey/blob/main/engine/src/time.rs): fixed step · Frame timing and deterministic update cadence · `engine/src/time.rs`
- [Physics](https://github.com/ujjwalvivek/journey/blob/main/engine/src/physics.rs): simulation · Core world and movement simulation · `engine/src/physics.rs`

### Game

Gameplay, scenes, combat, and content glue

- [Game Main](https://github.com/ujjwalvivek/journey/blob/main/game/src/main.rs): exe entry · Executable entry point · `game/src/main.rs`
- [Game API](https://github.com/ujjwalvivek/journey/blob/main/game/src/lib.rs): app glue · Binds gameplay into the engine app model · `game/src/lib.rs`
- [Scene](https://github.com/ujjwalvivek/journey/blob/main/game/src/scene.rs): world flow · Top-level gameplay scene orchestration · `game/src/scene.rs`
- [Player](https://github.com/ujjwalvivek/journey/blob/main/game/src/player.rs): character logic · Player movement and interactions · `game/src/player.rs`
- [Combat](https://github.com/ujjwalvivek/journey/blob/main/game/src/combat/mod.rs): combat domain · Buffered FSM-based combat system · `game/src/combat/mod.rs`
- [Level](https://github.com/ujjwalvivek/journey/blob/main/game/src/level.rs): level data · Level loading and progression logic · `game/src/level.rs`
- [Game Audio](https://github.com/ujjwalvivek/journey/blob/main/game/src/audio.rs): content audio · Gameplay-specific sound triggering and integration · `game/src/audio.rs`

### Audio

Procedural audio generation stack

- [Cadence](https://github.com/ujjwalvivek/journey/blob/main/cadence/src/lib.rs): sequencer · Higher-level sequencing and scene-driven audio logic · `cadence/src/lib.rs`
- [Resonance](https://github.com/ujjwalvivek/journey/blob/main/resonance/src/lib.rs): dsp core · Low-level synthesis and sound primitives · `resonance/src/lib.rs`
- [Audio Tool](https://github.com/ujjwalvivek/journey/blob/main/tools/audio/src/main.rs): generator cli · CLI orchestration for audio generation and web export · `tools/audio/src/main.rs`

### Web

Browser host and WASM distribution layer

- [Web Host](https://github.com/ujjwalvivek/journey/blob/main/web/src/main.ts): browser app · Vite/TypeScript browser entry and WASM host · `web/src/main.ts`
- [Audio UI](https://github.com/ujjwalvivek/journey/blob/main/web/src/components/shared-audio.ts): browser glue · Shared browser-side audio integration and components · `web/src/components/shared-audio.ts`

### Tooling

Release and auxiliary build tools

- [Release Tool](https://github.com/ujjwalvivek/journey/blob/main/tools/release/main.go): release pipeline · Go-based orchestration for versioning and publishing · `tools/release/main.go`
- [Versioning](https://github.com/ujjwalvivek/journey/blob/main/tools/versioning/main.go): semver tool · Standalone version management utility · `tools/versioning/main.go`

### Docs

Developer and technical documentation

- [Docs](https://github.com/ujjwalvivek/journey/blob/main/docs/src/SUMMARY.md): book docs · mdBook documentation set for engine, audio, and technical notes · `docs/src/SUMMARY.md`

## Connections

- Game Main → Game API: starts · Executable boots the game layer
- Game API → Engine API: uses · Gameplay is built on the reusable engine API
- Game API → Scene: drives · Game entry binds scene orchestration
- Scene → Player: updates · Scene owns player state and flow
- Scene → Level: loads · Scene advances through levels and content
- Scene → Combat: runs · Scene coordinates combat interactions
- Scene → Game Audio: triggers · Scene and gameplay events emit audio cues
- Combat → Player: buffers · Combat logic depends on player timing and input
- Runtime → Context: renders · Runtime hands off to the frame/render context
- Runtime → Input: polls · Runtime ingests platform input each frame
- Runtime → Time: steps · Fixed-step timing governs simulation cadence
- Runtime → Physics: simulates · Runtime advances physics and movement systems
- Engine API → Runtime: exports · Library surface exposes the core loop
- Engine API → Input: exports · Library surface exposes input handling
- Cadence → Resonance: builds on · Sequencing layer sits on top of DSP primitives
- Audio Tool → Cadence: generates · Audio tooling orchestrates cadence-based content
- Audio Tool → Resonance: renders · Tooling can render or transform resonance assets
- Web Host → Audio UI: hosts · Browser entry mounts shared audio components
- Audio UI → Cadence: adapts · Web layer bridges cadence concepts into the browser
- Audio UI → Resonance: adapts · Web layer bridges resonance synthesis into Web Audio
- Release Tool → Versioning: coordinates · Release pipeline uses version management support
- Docs → Engine API: documents · Documentation covers the engine API and architecture
- Docs → Cadence: documents · Documentation covers the audio generation stack
- Docs → Game API: documents · Documentation covers gameplay and runtime flow