# taratipt/songguessr architecture

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

- Interactive diagram: https://gitdiagram.com/taratipt/songguessr
- Repository: https://github.com/taratipt/songguessr

## Overview

SongGuessr is a browser-based music-guessing game with solo, real-time room, and 1v1 SongDraft modes. Players choose a category, hear a song preview, answer by choice or text, use hints, and see round and game results; faster correct answers score higher. The graph follows the app’s documented flow and sampled calls. Some UI wiring and unsampled feature internals are represented only where documented, rather than inferred from filenames.

Main entry points: [`src/App.tsx`](https://github.com/taratipt/songguessr/blob/main/src/App.tsx) (Game coordinator), [`src/services/itunesApi.ts`](https://github.com/taratipt/songguessr/blob/main/src/services/itunesApi.ts) (Song search and matching), [`src/services/multiplayerService.ts`](https://github.com/taratipt/songguessr/blob/main/src/services/multiplayerService.ts) (Realtime room service), [`src/components/CategorySelectModal.tsx`](https://github.com/taratipt/songguessr/blob/main/src/components/CategorySelectModal.tsx) (Category setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gameplay["Game flow"]
  node_app["Game coordinator<br/>[App.tsx]"]
  node_categories["Category setup"]
  node_answers["Answer input<br/>[GuessBar.tsx]"]
  node_choices["Multiple choice"]
  node_hints["Hints<br/>[HintCards.tsx]"]
  node_round_results["Round results"]
  node_game_results["Game results<br/>[GameOverModal.tsx]"]
  node_score["Score calculation<br/>[scoreCalculator.ts]"]
end

subgraph group_catalog["Music catalog"]
  node_category_data["Music categories<br/>[categories.ts]"]
  node_artist_data["Artist catalog<br/>[artistsData.ts]"]
  node_curated_songs["Curated songs<br/>[curatedSongs.ts]"]
  node_song_search["Song search and matching<br/>[itunesApi.ts]"]
  node_karaoke["Thai karaoke mappings<br/>[thaiKaraokeMap.ts]"]
  node_title_aliases["Song title aliases"]
  node_thai_artists["Thai artist catalog<br/>[thaiArtists.ts]"]
  node_choices_service["Choice generation<br/>[choiceGenerator.ts]"]
end

subgraph group_multiplayer["Rooms and draft"]
  node_room_service["Realtime room service"]
  node_draft["SongDraft arena<br/>[SongDraftArena.tsx]"]
end

subgraph group_experience["Player experience"]
  node_storage[("Player settings<br/>[storageService.ts]")]
  node_audio["Player and audio<br/>[PlayerScreen.tsx]"]
  node_sound["Sound effects<br/>[soundEffects.ts]"]
  node_artist_picker["Artist selection"]
end

node_player(("Player"))
node_itunes["Apple iTunes API"]
node_mqtt["MQTT WebSocket brokers"]

node_player -->|"starts game"| node_app
node_player -->|"chooses settings"| node_categories
node_categories -->|"configures play"| node_app
node_app -->|"fetches songs"| node_song_search
node_song_search -->|"searches catalog"| node_itunes
node_song_search -->|"uses fallback data"| node_curated_songs
node_song_search -->|"uses artist metadata"| node_artist_data
node_song_search -->|"matches romanization"| node_karaoke
node_song_search -->|"matches aliases"| node_title_aliases
node_app -->|"generates choices"| node_choices_service
node_choices_service -->|"uses song matching"| node_song_search
node_app -->|"presents round"| node_audio
node_player -->|"submits guess"| node_answers
node_player -->|"selects answer"| node_choices
node_player -->|"requests hint"| node_hints
node_answers -->|"checks title aliases"| node_title_aliases
node_answers -->|"checks romanization"| node_karaoke
node_app -->|"shows round summary"| node_round_results
node_app -->|"shows final results"| node_game_results
node_player -->|"joins room"| node_room_service
node_app -->|"starts host game"| node_room_service
node_room_service -->|"publishes room updates"| node_mqtt
node_room_service -->|"calculates verified score"| node_score
node_app -.->|"scores solo rounds"| node_score
node_player -->|"picks and bans"| node_draft
node_draft -.->|"synchronizes draft"| node_room_service
node_categories -->|"offers categories"| node_category_data
node_player -->|"filters artists"| node_artist_picker
node_artist_picker -->|"browses artists"| node_artist_data
node_categories -->|"persists preferences"| node_storage
node_audio -->|"plays effects"| node_sound
node_player -.->|"browses Thai artists"| node_thai_artists

click node_app "https://github.com/taratipt/songguessr/blob/main/src/App.tsx"
click node_categories "https://github.com/taratipt/songguessr/blob/main/src/components/CategorySelectModal.tsx"
click node_answers "https://github.com/taratipt/songguessr/blob/main/src/components/GuessBar.tsx"
click node_choices "https://github.com/taratipt/songguessr/blob/main/src/components/MultipleChoiceBar.tsx"
click node_hints "https://github.com/taratipt/songguessr/blob/main/src/components/HintCards.tsx"
click node_round_results "https://github.com/taratipt/songguessr/blob/main/src/components/RoundSummaryModal.tsx"
click node_game_results "https://github.com/taratipt/songguessr/blob/main/src/components/GameOverModal.tsx"
click node_score "https://github.com/taratipt/songguessr/blob/main/src/utils/scoreCalculator.ts"
click node_category_data "https://github.com/taratipt/songguessr/blob/main/src/data/categories.ts"
click node_artist_data "https://github.com/taratipt/songguessr/blob/main/src/data/artistsData.ts"
click node_curated_songs "https://github.com/taratipt/songguessr/blob/main/src/data/curatedSongs.ts"
click node_song_search "https://github.com/taratipt/songguessr/blob/main/src/services/itunesApi.ts"
click node_karaoke "https://github.com/taratipt/songguessr/blob/main/src/data/thaiKaraokeMap.ts"
click node_title_aliases "https://github.com/taratipt/songguessr/blob/main/src/data/thaiSongTitleAliases.ts"
click node_thai_artists "https://github.com/taratipt/songguessr/blob/main/src/data/thaiArtists.ts"
click node_choices_service "https://github.com/taratipt/songguessr/blob/main/src/services/choiceGenerator.ts"
click node_room_service "https://github.com/taratipt/songguessr/blob/main/src/services/multiplayerService.ts"
click node_draft "https://github.com/taratipt/songguessr/blob/main/src/components/SongDraftArena.tsx"
click node_storage "https://github.com/taratipt/songguessr/blob/main/src/services/storageService.ts"
click node_audio "https://github.com/taratipt/songguessr/blob/main/src/components/PlayerScreen.tsx"
click node_sound "https://github.com/taratipt/songguessr/blob/main/src/services/soundEffects.ts"
click node_artist_picker "https://github.com/taratipt/songguessr/blob/main/src/components/GlobalArtistPickerModal.tsx"

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_categories,node_answers,node_choices,node_hints,node_round_results,node_game_results,node_score toneBlue
class node_category_data,node_artist_data,node_curated_songs,node_song_search,node_karaoke,node_title_aliases,node_thai_artists,node_choices_service toneAmber
class node_room_service,node_draft,node_itunes toneMint
class node_storage,node_audio,node_sound,node_artist_picker toneRose
class node_player,node_mqtt toneIndigo
```

## Components

### Game flow

- [Game coordinator](https://github.com/taratipt/songguessr/blob/main/src/App.tsx): `src/App.tsx`
- [Category setup](https://github.com/taratipt/songguessr/blob/main/src/components/CategorySelectModal.tsx): `src/components/CategorySelectModal.tsx`
- [Answer input](https://github.com/taratipt/songguessr/blob/main/src/components/GuessBar.tsx): `src/components/GuessBar.tsx`
- [Multiple choice](https://github.com/taratipt/songguessr/blob/main/src/components/MultipleChoiceBar.tsx): `src/components/MultipleChoiceBar.tsx`
- [Hints](https://github.com/taratipt/songguessr/blob/main/src/components/HintCards.tsx): `src/components/HintCards.tsx`
- [Round results](https://github.com/taratipt/songguessr/blob/main/src/components/RoundSummaryModal.tsx): `src/components/RoundSummaryModal.tsx`
- [Game results](https://github.com/taratipt/songguessr/blob/main/src/components/GameOverModal.tsx): `src/components/GameOverModal.tsx`
- [Score calculation](https://github.com/taratipt/songguessr/blob/main/src/utils/scoreCalculator.ts): `src/utils/scoreCalculator.ts`

### Music catalog

- [Music categories](https://github.com/taratipt/songguessr/blob/main/src/data/categories.ts): `src/data/categories.ts`
- [Artist catalog](https://github.com/taratipt/songguessr/blob/main/src/data/artistsData.ts): `src/data/artistsData.ts`
- [Curated songs](https://github.com/taratipt/songguessr/blob/main/src/data/curatedSongs.ts): `src/data/curatedSongs.ts`
- [Song search and matching](https://github.com/taratipt/songguessr/blob/main/src/services/itunesApi.ts): `src/services/itunesApi.ts`
- [Thai karaoke mappings](https://github.com/taratipt/songguessr/blob/main/src/data/thaiKaraokeMap.ts): `src/data/thaiKaraokeMap.ts`
- [Song title aliases](https://github.com/taratipt/songguessr/blob/main/src/data/thaiSongTitleAliases.ts): `src/data/thaiSongTitleAliases.ts`
- [Thai artist catalog](https://github.com/taratipt/songguessr/blob/main/src/data/thaiArtists.ts): `src/data/thaiArtists.ts`
- [Choice generation](https://github.com/taratipt/songguessr/blob/main/src/services/choiceGenerator.ts): `src/services/choiceGenerator.ts`

### Rooms and draft

- [Realtime room service](https://github.com/taratipt/songguessr/blob/main/src/services/multiplayerService.ts): `src/services/multiplayerService.ts`
- [SongDraft arena](https://github.com/taratipt/songguessr/blob/main/src/components/SongDraftArena.tsx): `src/components/SongDraftArena.tsx`

### Player experience

- [Player settings](https://github.com/taratipt/songguessr/blob/main/src/services/storageService.ts): `src/services/storageService.ts`
- [Player and audio](https://github.com/taratipt/songguessr/blob/main/src/components/PlayerScreen.tsx): `src/components/PlayerScreen.tsx`
- [Sound effects](https://github.com/taratipt/songguessr/blob/main/src/services/soundEffects.ts): `src/services/soundEffects.ts`
- [Artist selection](https://github.com/taratipt/songguessr/blob/main/src/components/GlobalArtistPickerModal.tsx): `src/components/GlobalArtistPickerModal.tsx`

### Other components

- **Player**
- **Apple iTunes API**
- **MQTT WebSocket brokers**

## Connections

- Player → Game coordinator: starts game
- Player → Category setup: chooses settings
- Category setup → Game coordinator: configures play (evidence: `src/App.tsx`)
- Game coordinator → Song search and matching: fetches songs (evidence: `src/App.tsx`)
- Song search and matching → Apple iTunes API: searches catalog
- Song search and matching → Curated songs: uses fallback data (evidence: `src/services/itunesApi.ts`)
- Song search and matching → Artist catalog: uses artist metadata (evidence: `src/services/itunesApi.ts`)
- Song search and matching → Thai karaoke mappings: matches romanization (evidence: `src/services/itunesApi.ts`)
- Song search and matching → Song title aliases: matches aliases (evidence: `src/services/itunesApi.ts`)
- Game coordinator → Choice generation: generates choices (evidence: `src/App.tsx`)
- Choice generation → Song search and matching: uses song matching (evidence: `src/services/choiceGenerator.ts`)
- Game coordinator → Player and audio: presents round (evidence: `src/App.tsx`)
- Player → Answer input: submits guess
- Player → Multiple choice: selects answer
- Player → Hints: requests hint
- Answer input → Song title aliases: checks title aliases (evidence: `src/components/GuessBar.tsx`)
- Answer input → Thai karaoke mappings: checks romanization (evidence: `src/components/GuessBar.tsx`)
- Game coordinator → Round results: shows round summary (evidence: `src/App.tsx`)
- Game coordinator → Game results: shows final results (evidence: `src/App.tsx`)
- Player → Realtime room service: joins room
- Game coordinator → Realtime room service: starts host game (evidence: `src/App.tsx`)
- Realtime room service → MQTT WebSocket brokers: publishes room updates
- Realtime room service → Score calculation: calculates verified score (evidence: `src/services/multiplayerService.ts`)
- Game coordinator → Score calculation: scores solo rounds (evidence: `src/App.tsx`)
- Player → SongDraft arena: picks and bans
- SongDraft arena → Realtime room service: synchronizes draft
- Category setup → Music categories: offers categories (evidence: `src/components/CategorySelectModal.tsx`)
- Player → Artist selection: filters artists
- Artist selection → Artist catalog: browses artists (evidence: `src/components/GlobalArtistPickerModal.tsx`)
- Category setup → Player settings: persists preferences (evidence: `src/components/CategorySelectModal.tsx`)
- Player and audio → Sound effects: plays effects (evidence: `src/components/PlayerScreen.tsx`)
- Player → Thai artist catalog: browses Thai artists