# chinjuku/beatdrop architecture

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

- Interactive diagram: https://gitdiagram.com/chinjuku/beatdrop
- Repository: https://github.com/chinjuku/beatdrop

## Overview

BeatDrop is a Thai/international snippet-guessing game: players configure a mode and difficulty, play staged audio rounds, submit guesses, and view results or leaderboards. The architecture also supports daily challenges, artist and catalog management, and multiplayer rooms. Edges below reflect README statements and the shown source references; unsampled routes and room internals are represented conservatively, so some capabilities have no asserted internal call chain.

Main entry points: [`context/GameContext.tsx`](https://github.com/chinjuku/beatdrop/blob/main/context/GameContext.tsx) (Game interface), [`lib/engine/songPool.ts`](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/songPool.ts) (Song pool), [`lib/engine/roundEngine.ts`](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/roundEngine.ts) (Round engine), [`lib/engine/artistRoutes.ts`](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/artistRoutes.ts) (Artist services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Game play"]
  node_gameui["Game interface<br/>[GameContext.tsx]"]
  node_playpages["Play modes<br/>[page.tsx]"]
  node_roundapi["Round endpoints<br/>[route.ts]"]
  node_roundengine["Round engine<br/>[roundEngine.ts]"]
  node_audioplay["Audio playback"]
  node_audioproxy["Audio proxy<br/>[route.ts]"]
  node_guessui["Song Guesser<br/>[page.tsx]"]
end

subgraph group_daily["Daily challenge"]
  node_dailyui["Daily play<br/>[page.tsx]"]
  node_dailyapi["Daily endpoints<br/>[route.ts]"]
  node_dailyengine["Daily engine<br/>[dailyEngine.ts]"]
  node_dailyresults["Daily results<br/>[DailyResults.tsx]"]
  node_leaderboard["Leaderboard<br/>[leaderboard.ts]"]
end

subgraph group_catalog["Music catalog"]
  node_catalogui["Catalog browsing<br/>[page.tsx]"]
  node_artistui["Artist view<br/>[ArtistPageView.tsx]"]
  node_artistapi["Artist endpoints<br/>[route.ts]"]
  node_artistroutes["Artist services<br/>[artistRoutes.ts]"]
  node_songpool["Song pool<br/>[songPool.ts]"]
  node_itunes["iTunes ingestion<br/>[itunes.ts]"]
end

subgraph group_rooms["Multiplayer rooms"]
  node_roomui["Room interface<br/>[page.tsx]"]
  node_roomapi["Room endpoints<br/>[route.ts]"]
  node_roomservice["Room service<br/>[service.ts]"]
  node_roomstate["Room state<br/>[store.ts]"]
end

subgraph group_platform["Storage and platform"]
  node_database[("Database service<br/>[db.ts]")]
  node_supabase[("Supabase storage<br/>[supabase.ts]")]
  node_localprefs["Local preferences"]
  node_cron["Daily scheduler<br/>[route.ts]"]
end

node_player(("Player"))
node_external["iTunes API"]

node_player -->|"plays"| node_gameui
node_gameui -.->|"starts rounds"| node_roundapi
node_playpages -.->|"uses game state"| node_gameui
node_roundapi -.->|"dispatches"| node_roundengine
node_roundengine -->|"loads songs"| node_songpool
node_gameui -->|"controls audio"| node_audioplay
node_audioplay -->|"requests audio"| node_audioproxy
node_guessui -.->|"uses game state"| node_gameui
node_dailyui -->|"loads challenge"| node_dailyapi
node_dailyapi -.->|"handles challenge"| node_dailyengine
node_roundengine -->|"scopes daily player"| node_dailyengine
node_dailyui -->|"renders results"| node_dailyresults
node_leaderboard -.->|"reads and writes"| node_database
node_catalogui -->|"sets filters"| node_gameui
node_artistui -.->|"requests artist data"| node_artistapi
node_artistapi -->|"delegates"| node_artistroutes
node_artistroutes -->|"fetches songs"| node_songpool
node_artistroutes -->|"searches catalog"| node_itunes
node_itunes -.->|"fetches previews"| node_external
node_songpool -->|"loads catalog"| node_database
node_player -.->|"joins room"| node_roomui
node_roomui -.->|"controls room"| node_roomapi
node_roomapi -->|"delegates"| node_roomservice
node_roomservice -->|"uses room store"| node_roomstate
node_roomservice -->|"selects songs"| node_songpool
node_database -->|"cloud persistence"| node_supabase
node_gameui -->|"reads preferences"| node_localprefs
node_cron -.->|"creates daily set"| node_dailyengine

click node_gameui "https://github.com/chinjuku/beatdrop/blob/main/context/GameContext.tsx"
click node_playpages "https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/play/page.tsx"
click node_roundapi "https://github.com/chinjuku/beatdrop/blob/main/app/api/rounds/start/route.ts"
click node_roundengine "https://github.com/chinjuku/beatdrop/blob/main/lib/engine/roundEngine.ts"
click node_audioplay "https://github.com/chinjuku/beatdrop/blob/main/hooks/useAudioController.ts"
click node_audioproxy "https://github.com/chinjuku/beatdrop/blob/main/app/api/proxy/audio/route.ts"
click node_guessui "https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/guesser/page.tsx"
click node_dailyui "https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/daily/page.tsx"
click node_dailyapi "https://github.com/chinjuku/beatdrop/blob/main/app/api/daily/route.ts"
click node_dailyengine "https://github.com/chinjuku/beatdrop/blob/main/lib/engine/dailyEngine.ts"
click node_dailyresults "https://github.com/chinjuku/beatdrop/blob/main/components/daily/DailyResults.tsx"
click node_leaderboard "https://github.com/chinjuku/beatdrop/blob/main/lib/engine/leaderboard.ts"
click node_catalogui "https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/categories/page.tsx"
click node_artistui "https://github.com/chinjuku/beatdrop/blob/main/components/artist/ArtistPageView.tsx"
click node_artistapi "https://github.com/chinjuku/beatdrop/blob/main/app/api/artists/sync/route.ts"
click node_artistroutes "https://github.com/chinjuku/beatdrop/blob/main/lib/engine/artistRoutes.ts"
click node_songpool "https://github.com/chinjuku/beatdrop/blob/main/lib/engine/songPool.ts"
click node_itunes "https://github.com/chinjuku/beatdrop/blob/main/lib/itunes.ts"
click node_roomui "https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/room/%5Bcode%5D/page.tsx"
click node_roomapi "https://github.com/chinjuku/beatdrop/blob/main/app/api/rooms/route.ts"
click node_roomservice "https://github.com/chinjuku/beatdrop/blob/main/lib/rooms/service.ts"
click node_roomstate "https://github.com/chinjuku/beatdrop/blob/main/lib/rooms/store.ts"
click node_database "https://github.com/chinjuku/beatdrop/blob/main/lib/db.ts"
click node_supabase "https://github.com/chinjuku/beatdrop/blob/main/shared/supabase.ts"
click node_localprefs "https://github.com/chinjuku/beatdrop/blob/main/lib/preferenceStorage.ts"
click node_cron "https://github.com/chinjuku/beatdrop/blob/main/app/api/cron/daily/route.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_gameui,node_playpages,node_roundapi,node_roundengine,node_audioplay,node_audioproxy,node_guessui toneBlue
class node_dailyui,node_dailyapi,node_dailyengine,node_dailyresults,node_leaderboard toneAmber
class node_catalogui,node_artistui,node_artistapi,node_artistroutes,node_songpool,node_itunes,node_external toneMint
class node_roomui,node_roomapi,node_roomservice,node_roomstate toneRose
class node_database,node_supabase,node_localprefs,node_cron,node_player toneIndigo
```

## Components

### Game play

- [Game interface](https://github.com/chinjuku/beatdrop/blob/main/context/GameContext.tsx): `context/GameContext.tsx`
- [Play modes](https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/play/page.tsx): `app/[locale]/play/page.tsx`
- [Round endpoints](https://github.com/chinjuku/beatdrop/blob/main/app/api/rounds/start/route.ts): `app/api/rounds/start/route.ts`
- [Round engine](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/roundEngine.ts): `lib/engine/roundEngine.ts`
- [Audio playback](https://github.com/chinjuku/beatdrop/blob/main/hooks/useAudioController.ts): `hooks/useAudioController.ts`
- [Audio proxy](https://github.com/chinjuku/beatdrop/blob/main/app/api/proxy/audio/route.ts): `app/api/proxy/audio/route.ts`
- [Song Guesser](https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/guesser/page.tsx): `app/[locale]/guesser/page.tsx`

### Daily challenge

- [Daily play](https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/daily/page.tsx): `app/[locale]/daily/page.tsx`
- [Daily endpoints](https://github.com/chinjuku/beatdrop/blob/main/app/api/daily/route.ts): `app/api/daily/route.ts`
- [Daily engine](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/dailyEngine.ts): `lib/engine/dailyEngine.ts`
- [Daily results](https://github.com/chinjuku/beatdrop/blob/main/components/daily/DailyResults.tsx): `components/daily/DailyResults.tsx`
- [Leaderboard](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/leaderboard.ts): `lib/engine/leaderboard.ts`

### Music catalog

- [Catalog browsing](https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/categories/page.tsx): `app/[locale]/categories/page.tsx`
- [Artist view](https://github.com/chinjuku/beatdrop/blob/main/components/artist/ArtistPageView.tsx): `components/artist/ArtistPageView.tsx`
- [Artist endpoints](https://github.com/chinjuku/beatdrop/blob/main/app/api/artists/sync/route.ts): `app/api/artists/sync/route.ts`
- [Artist services](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/artistRoutes.ts): `lib/engine/artistRoutes.ts`
- [Song pool](https://github.com/chinjuku/beatdrop/blob/main/lib/engine/songPool.ts): `lib/engine/songPool.ts`
- [iTunes ingestion](https://github.com/chinjuku/beatdrop/blob/main/lib/itunes.ts): `lib/itunes.ts`

### Multiplayer rooms

- [Room interface](https://github.com/chinjuku/beatdrop/blob/main/app/%5Blocale%5D/room/%5Bcode%5D/page.tsx): `app/[locale]/room/[code]/page.tsx`
- [Room endpoints](https://github.com/chinjuku/beatdrop/blob/main/app/api/rooms/route.ts): `app/api/rooms/route.ts`
- [Room service](https://github.com/chinjuku/beatdrop/blob/main/lib/rooms/service.ts): `lib/rooms/service.ts`
- [Room state](https://github.com/chinjuku/beatdrop/blob/main/lib/rooms/store.ts): `lib/rooms/store.ts`

### Storage and platform

- [Database service](https://github.com/chinjuku/beatdrop/blob/main/lib/db.ts): `lib/db.ts`
- [Supabase storage](https://github.com/chinjuku/beatdrop/blob/main/shared/supabase.ts): `shared/supabase.ts`
- [Local preferences](https://github.com/chinjuku/beatdrop/blob/main/lib/preferenceStorage.ts): `lib/preferenceStorage.ts`
- [Daily scheduler](https://github.com/chinjuku/beatdrop/blob/main/app/api/cron/daily/route.ts): `app/api/cron/daily/route.ts`

### Other components

- **Player**
- **iTunes API**

## Connections

- Player → Game interface: plays
- Game interface → Round endpoints: starts rounds
- Play modes → Game interface: uses game state
- Round endpoints → Round engine: dispatches
- Round engine → Song pool: loads songs (evidence: `lib/engine/roundEngine.ts`)
- Game interface → Audio playback: controls audio (evidence: `context/GameContext.tsx`)
- Audio playback → Audio proxy: requests audio (evidence: `hooks/useAudioController.ts`)
- Song Guesser → Game interface: uses game state
- Daily play → Daily endpoints: loads challenge
- Daily endpoints → Daily engine: handles challenge
- Round engine → Daily engine: scopes daily player (evidence: `lib/engine/roundEngine.ts`)
- Daily play → Daily results: renders results (evidence: `app/[locale]/daily/page.tsx`)
- Leaderboard → Database service: reads and writes
- Catalog browsing → Game interface: sets filters (evidence: `app/[locale]/categories/page.tsx`)
- Artist view → Artist endpoints: requests artist data
- Artist endpoints → Artist services: delegates (evidence: `app/api/artists/sync/route.ts`)
- Artist services → Song pool: fetches songs (evidence: `lib/engine/artistRoutes.ts`)
- Artist services → iTunes ingestion: searches catalog (evidence: `lib/engine/artistRoutes.ts`)
- iTunes ingestion → iTunes API: fetches previews
- Song pool → Database service: loads catalog (evidence: `lib/engine/songPool.ts`)
- Player → Room interface: joins room
- Room interface → Room endpoints: controls room
- Room endpoints → Room service: delegates (evidence: `app/api/rooms/route.ts`)
- Room service → Room state: uses room store (evidence: `lib/rooms/service.ts`)
- Room service → Song pool: selects songs (evidence: `lib/rooms/service.ts`)
- Database service → Supabase storage: cloud persistence (evidence: `lib/db.ts`)
- Game interface → Local preferences: reads preferences (evidence: `context/GameContext.tsx`)
- Daily scheduler → Daily engine: creates daily set
