# yumo-ymspace/rhythm-mania-v1-beta architecture

> Architecture diagram of the GitHub repository yumo-ymspace/rhythm-mania-v1-beta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yumo-ymspace/rhythm-mania-v1-beta
- Repository: https://github.com/yumo-ymspace/rhythm-mania-v1-beta

## Overview

RhythmMania is a browser-native mania rhythm game. Players select or import a beatmap, configure play, perform to an audio clock, and review results and timing history. The main UI coordinates those screens; gameplay combines the mania ruleset with a renderer and audio engine. Local maps and preferences support offline play, while the documented mirror catalog is an optional online branch. The README describes several capabilities whose detailed wiring is not visible in the sampled source, so those links are limited to documented flows.

Main entry points: [`src/App.tsx`](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/App.tsx) (App coordinator), [`src/components/GameplayCanvas.tsx`](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/GameplayCanvas.tsx) (Gameplay screen), [`src/components/SongSelect.tsx`](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/SongSelect.tsx) (Song selection), [`src/utils/osuTokenManager.ts`](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/osuTokenManager.ts) (Catalog client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Game experience"]
  node_app["App coordinator<br/>[App.tsx]"]
  node_songselect["Song selection<br/>[SongSelect.tsx]"]
  node_gameplay["Gameplay screen<br/>[GameplayCanvas.tsx]"]
  node_results["Results screen<br/>[ResultsScreen.tsx]"]
  node_history["Play history"]
end

subgraph group_play["Gameplay runtime"]
  node_rules["Mania ruleset<br/>[index.ts]"]
  node_audio["Audio engine<br/>[AudioEngine.ts]"]
  node_renderer["Playfield renderer"]
  node_webgl["3D renderer"]
end

subgraph group_library["Maps and history"]
  node_parser["Beatmap parser<br/>[beatmapParser.ts]"]
  node_unpack["Archive unpacking<br/>[unpackHelper.ts]"]
  node_storage[("Local beatmap store<br/>[storageManager.ts]")]
  node_replay["Replay manager<br/>[replayManager.ts]"]
  node_star["Star estimation<br/>[starRating.ts]"]
end

subgraph group_preferences["Settings and media"]
  node_settings["Settings screen<br/>[SettingsScreen.tsx]"]
  node_video["Video sync"]
end

subgraph group_online["Online catalog"]
  node_catalog["Catalog client<br/>[osuTokenManager.ts]"]
  node_router["Catalog router<br/>[catalog-router.ts]"]
  node_search["Catalog search<br/>[_search.ts]"]
  node_mirrorservice["Mirror catalog service<br/>[mirrorCatalog.ts]"]
end

node_player(("Player"))
node_mirrors["Beatmap mirrors"]

node_player -->|"uses"| node_app
node_app -->|"shows"| node_songselect
node_app -->|"shows"| node_gameplay
node_app -->|"shows"| node_results
node_app -->|"shows"| node_history
node_songselect -->|"unpacks imports"| node_unpack
node_unpack -->|"parses maps"| node_parser
node_songselect -->|"loads maps"| node_storage
node_unpack -->|"saves maps"| node_storage
node_songselect -->|"estimates difficulty"| node_star
node_gameplay -->|"controls transport"| node_audio
node_gameplay -->|"judges input"| node_rules
node_gameplay -->|"draws playfield"| node_renderer
node_gameplay -.->|"draws 3D field"| node_webgl
node_gameplay -.->|"syncs background"| node_video
node_results -->|"creates record"| node_replay
node_history -->|"reads records"| node_storage
node_app -->|"migrates history"| node_replay
node_player -->|"configures"| node_settings
node_settings -->|"persists preferences"| node_storage
node_songselect -->|"searches sets"| node_catalog
node_app -->|"downloads archives"| node_catalog
node_catalog -->|"requests search"| node_router
node_router -->|"dispatches"| node_search
node_search -->|"searches"| node_mirrorservice
node_mirrorservice -->|"queries"| node_mirrors
node_catalog -->|"downloads archive"| node_mirrors

click node_app "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/App.tsx"
click node_songselect "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/SongSelect.tsx"
click node_gameplay "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/GameplayCanvas.tsx"
click node_results "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/ResultsScreen.tsx"
click node_history "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/PersonalHistoryScreen.tsx"
click node_parser "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/beatmapParser.ts"
click node_unpack "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/unpackHelper.ts"
click node_storage "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/storageManager.ts"
click node_replay "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/replayManager.ts"
click node_star "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/starRating.ts"
click node_rules "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/ruleset/mania/index.ts"
click node_audio "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/audio/AudioEngine.ts"
click node_renderer "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/render/Canvas2DRenderer.ts"
click node_webgl "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/render/WebGL2PlayfieldRenderer.ts"
click node_settings "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/SettingsScreen.tsx"
click node_video "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/videoSyncController.ts"
click node_catalog "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/osuTokenManager.ts"
click node_router "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/catalog-router.ts"
click node_search "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/catalog/_search.ts"
click node_mirrorservice "https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/_lib/mirrorCatalog.ts"

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_app,node_songselect,node_gameplay,node_results,node_history toneBlue
class node_rules,node_audio,node_renderer,node_webgl toneAmber
class node_parser,node_unpack,node_storage,node_replay,node_star toneMint
class node_settings,node_video toneRose
class node_catalog,node_router,node_search,node_mirrorservice,node_player,node_mirrors toneIndigo
```

## Components

### Game experience

- [App coordinator](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/App.tsx): `src/App.tsx`
- [Song selection](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/SongSelect.tsx): `src/components/SongSelect.tsx`
- [Gameplay screen](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/GameplayCanvas.tsx): `src/components/GameplayCanvas.tsx`
- [Results screen](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/ResultsScreen.tsx): `src/components/ResultsScreen.tsx`
- [Play history](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/PersonalHistoryScreen.tsx): `src/components/PersonalHistoryScreen.tsx`

### Gameplay runtime

- [Mania ruleset](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/ruleset/mania/index.ts): `src/ruleset/mania/index.ts`
- [Audio engine](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/audio/AudioEngine.ts): `src/audio/AudioEngine.ts`
- [Playfield renderer](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/render/Canvas2DRenderer.ts): `src/render/Canvas2DRenderer.ts`
- [3D renderer](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/render/WebGL2PlayfieldRenderer.ts): `src/render/WebGL2PlayfieldRenderer.ts`

### Maps and history

- [Beatmap parser](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/beatmapParser.ts): `src/utils/beatmapParser.ts`
- [Archive unpacking](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/unpackHelper.ts): `src/utils/unpackHelper.ts`
- [Local beatmap store](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/storageManager.ts): `src/utils/storageManager.ts`
- [Replay manager](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/replayManager.ts): `src/utils/replayManager.ts`
- [Star estimation](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/starRating.ts): `src/utils/starRating.ts`

### Settings and media

- [Settings screen](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/components/SettingsScreen.tsx): `src/components/SettingsScreen.tsx`
- [Video sync](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/videoSyncController.ts): `src/utils/videoSyncController.ts`

### Online catalog

- [Catalog client](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/src/utils/osuTokenManager.ts): `src/utils/osuTokenManager.ts`
- [Catalog router](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/catalog-router.ts): `api/catalog-router.ts`
- [Catalog search](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/catalog/_search.ts): `api/catalog/_search.ts`
- [Mirror catalog service](https://github.com/yumo-ymspace/rhythm-mania-v1-beta/blob/main/api/_lib/mirrorCatalog.ts): `api/_lib/mirrorCatalog.ts`

### Other components

- **Player**
- **Beatmap mirrors**

## Connections

- Player → App coordinator: uses
- App coordinator → Song selection: shows
- App coordinator → Gameplay screen: shows
- App coordinator → Results screen: shows
- App coordinator → Play history: shows
- Song selection → Archive unpacking: unpacks imports
- Archive unpacking → Beatmap parser: parses maps
- Song selection → Local beatmap store: loads maps
- Archive unpacking → Local beatmap store: saves maps
- Song selection → Star estimation: estimates difficulty
- Gameplay screen → Audio engine: controls transport
- Gameplay screen → Mania ruleset: judges input
- Gameplay screen → Playfield renderer: draws playfield
- Gameplay screen → 3D renderer: draws 3D field
- Gameplay screen → Video sync: syncs background
- Results screen → Replay manager: creates record
- Play history → Local beatmap store: reads records
- App coordinator → Replay manager: migrates history
- Player → Settings screen: configures
- Settings screen → Local beatmap store: persists preferences
- Song selection → Catalog client: searches sets
- App coordinator → Catalog client: downloads archives
- Catalog client → Catalog router: requests search
- Catalog router → Catalog search: dispatches
- Catalog search → Mirror catalog service: searches
- Mirror catalog service → Beatmap mirrors: queries
- Catalog client → Beatmap mirrors: downloads archive