# mischa255/velorider-game architecture

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

- Interactive diagram: https://gitdiagram.com/mischa255/velorider-game
- Repository: https://github.com/mischa255/velorider-game

## Overview

VeloRider is a browser-based bicycle racing game. The player enters through the game UI, configures a bike or selects a track, races against bots, and receives progression or reward handling in the UI. Racing includes obstacle generation, bike simulation, collision handling, bot decisions, and rendering; the README specifically calls out bot hazard avoidance. The source index confirms the main module dependencies, but excerpts omit some runtime wiring, so the graph shows only evidenced calls and storage operations.

Main entry points: [`main.js`](https://github.com/mischa255/velorider-game/blob/main/main.js) (Game bootstrap), [`race.js`](https://github.com/mischa255/velorider-game/blob/main/race.js) (Race simulation and rendering), [`state.js`](https://github.com/mischa255/velorider-game/blob/main/state.js) (Player state and autosave), [`audio.js`](https://github.com/mischa255/velorider-game/blob/main/audio.js) (Music and sound effects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Game flow"]
  node_app["Game bootstrap<br/>[main.js]"]
  node_garage["Garage and bike setup<br/>[main.js]"]
  node_trackselect["Track and history selection<br/>[main.js]"]
  node_rewards["Results and rewards<br/>[main.js]"]
end

subgraph group_racing["Race runtime"]
  node_race["Race simulation and rendering<br/>[race.js]"]
  node_botai["Bot driving decisions<br/>[bot-ai.js]"]
  node_utils["Shared utilities<br/>[utils.js]"]
end

subgraph group_content["Game content"]
  node_catalog["Items, tracks, obstacles<br/>[db.js]"]
end

subgraph group_platform["Persistence and audio"]
  node_state["Player state and autosave<br/>[state.js]"]
  node_localstore[("Browser local storage")]
  node_supabase[("Supabase saves")]
  node_audio["Music and sound effects<br/>[audio.js]"]
end

node_player(("Player"))

node_player -->|"plays"| node_app
node_app -->|"loads state"| node_state
node_app -->|"starts race"| node_race
node_app -->|"initializes audio"| node_audio
node_app -->|"reads catalogs"| node_catalog
node_app -->|"uses rarity helper"| node_utils
node_race -->|"reads race state"| node_state
node_race -->|"reads race data"| node_catalog
node_race -->|"uses helpers"| node_utils
node_race -->|"plays race sounds"| node_audio
node_race -->|"requests bot decisions"| node_botai
node_audio -->|"uses clamp"| node_utils
node_state -->|"reads and writes"| node_localstore
node_state -->|"loads and saves"| node_supabase

click node_app "https://github.com/mischa255/velorider-game/blob/main/main.js"
click node_garage "https://github.com/mischa255/velorider-game/blob/main/main.js"
click node_trackselect "https://github.com/mischa255/velorider-game/blob/main/main.js"
click node_rewards "https://github.com/mischa255/velorider-game/blob/main/main.js"
click node_race "https://github.com/mischa255/velorider-game/blob/main/race.js"
click node_botai "https://github.com/mischa255/velorider-game/blob/main/bot-ai.js"
click node_catalog "https://github.com/mischa255/velorider-game/blob/main/db.js"
click node_state "https://github.com/mischa255/velorider-game/blob/main/state.js"
click node_audio "https://github.com/mischa255/velorider-game/blob/main/audio.js"
click node_utils "https://github.com/mischa255/velorider-game/blob/main/utils.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_app,node_garage,node_trackselect,node_rewards toneBlue
class node_race,node_botai,node_utils toneAmber
class node_catalog toneMint
class node_state,node_localstore,node_supabase,node_audio toneRose
class node_player toneIndigo
```

## Components

### Game flow

- [Game bootstrap](https://github.com/mischa255/velorider-game/blob/main/main.js): `main.js`
- [Garage and bike setup](https://github.com/mischa255/velorider-game/blob/main/main.js): `main.js`
- [Track and history selection](https://github.com/mischa255/velorider-game/blob/main/main.js): `main.js`
- [Results and rewards](https://github.com/mischa255/velorider-game/blob/main/main.js): `main.js`

### Race runtime

- [Race simulation and rendering](https://github.com/mischa255/velorider-game/blob/main/race.js): `race.js`
- [Bot driving decisions](https://github.com/mischa255/velorider-game/blob/main/bot-ai.js): `bot-ai.js`
- [Shared utilities](https://github.com/mischa255/velorider-game/blob/main/utils.js): `utils.js`

### Game content

- [Items, tracks, obstacles](https://github.com/mischa255/velorider-game/blob/main/db.js): `db.js`

### Persistence and audio

- [Player state and autosave](https://github.com/mischa255/velorider-game/blob/main/state.js): `state.js`
- **Browser local storage**
- **Supabase saves**
- [Music and sound effects](https://github.com/mischa255/velorider-game/blob/main/audio.js): `audio.js`

### Other components

- **Player**

## Connections

- Player → Game bootstrap: plays (evidence: `README.md`)
- Game bootstrap → Player state and autosave: loads state (evidence: `main.js`)
- Game bootstrap → Race simulation and rendering: starts race (evidence: `main.js`)
- Game bootstrap → Music and sound effects: initializes audio (evidence: `main.js`)
- Game bootstrap → Items, tracks, obstacles: reads catalogs (evidence: `main.js`)
- Game bootstrap → Shared utilities: uses rarity helper (evidence: `main.js`)
- Race simulation and rendering → Player state and autosave: reads race state (evidence: `race.js`)
- Race simulation and rendering → Items, tracks, obstacles: reads race data (evidence: `race.js`)
- Race simulation and rendering → Shared utilities: uses helpers (evidence: `race.js`)
- Race simulation and rendering → Music and sound effects: plays race sounds (evidence: `race.js`)
- Race simulation and rendering → Bot driving decisions: requests bot decisions (evidence: `race.js`)
- Music and sound effects → Shared utilities: uses clamp (evidence: `audio.js`)
- Player state and autosave → Browser local storage: reads and writes (evidence: `state.js`)
- Player state and autosave → Supabase saves: loads and saves (evidence: `state.js`)