# kaierhyeh/music-room architecture

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

- Interactive diagram: https://gitdiagram.com/kaierhyeh/music-room
- Repository: https://github.com/kaierhyeh/music-room

## Overview

MusicRoom is a collaborative music platform for live track-voting events and shared playlists, with accounts, friends, Google sign-in, and subscription tiers. Users enter through the mobile/web app, authenticate, then use social and music features backed by a Go API and PostgreSQL. The diagram preserves the documented feature branches, while sampled source confirms only selected client and server connections; dashed links mark documented but unsampled client-to-API interactions.

Main entry points: [`musicroom-backend/internal/api/router.go`](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/api/router.go) (Route wiring), [`musicroom-app/src/api/client.ts`](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/api/client.ts) (API client), [`musicroom-app/src/screens/events`](https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/events) (Event screens), [`musicroom-app/App.tsx`](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/App.tsx) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App Experience"]
  node_app["App entry<br/>[App.tsx]"]
  node_authnav["Auth navigation<br/>[AuthNavigator.tsx]"]
  node_authctx["Auth session<br/>[AuthContext.tsx]"]
end

subgraph group_social["Social Features"]
  node_friendui["Friend screens"]
  node_profileui["Profile screens"]
  node_socialsvc["Friend service<br/>[friend.go]"]
  node_usersvc["User service<br/>[user.go]"]
end

subgraph group_music["Music Collaboration"]
  node_eventui["Event screens"]
  node_playlistui["Playlist screens"]
  node_preview["Track previews"]
  node_eventsvc["Event service<br/>[event.go]"]
  node_playlistsvc["Playlist service<br/>[playlist.go]"]
end

subgraph group_server["API Services"]
  node_server["HTTP server<br/>[main.go]"]
  node_router["Route wiring<br/>[router.go]"]
  node_authsvc["Account service<br/>[auth.go]"]
  node_subsvc["Subscription service<br/>[subscription.go]"]
  node_handlers["HTTP handlers"]
end

subgraph group_infra["State and Integrations"]
  node_clientapi["API client<br/>[client.ts]"]
  node_storage["Token storage<br/>[storage.ts]"]
  node_repository[("SQL repository")]
  node_hub["Realtime hub<br/>[hub.go]"]
  node_deezer["Deezer integration<br/>[client.go]"]
  node_mailer["Email delivery<br/>[mail.go]"]
  node_google["Google OAuth<br/>[googleoauth.go]"]
end

node_user(("MusicRoom user"))
node_api(("MusicRoom API"))

node_user -->|"uses"| node_app
node_app -->|"provides auth"| node_authctx
node_app -->|"mounts navigation"| node_authnav
node_authctx -->|"calls auth APIs"| node_clientapi
node_authctx -->|"stores tokens"| node_storage
node_eventui -.->|"requests event data"| node_clientapi
node_eventui -->|"plays previews"| node_preview
node_eventui -.->|"receives updates"| node_hub
node_playlistui -.->|"requests playlist data"| node_clientapi
node_friendui -.->|"requests friend data"| node_clientapi
node_profileui -.->|"requests profile data"| node_clientapi
node_clientapi -->|"reads tokens"| node_storage
node_clientapi -.->|"sends requests"| node_api
node_server -->|"creates router"| node_router
node_router -->|"registers routes"| node_handlers
node_router -->|"constructs service"| node_authsvc
node_router -->|"constructs service"| node_eventsvc
node_router -->|"constructs service"| node_playlistsvc
node_router -->|"constructs service"| node_socialsvc
node_router -->|"constructs service"| node_usersvc
node_router -->|"constructs service"| node_subsvc
node_router -->|"creates queries"| node_repository
node_router -->|"creates hub"| node_hub
node_router -->|"creates client"| node_deezer
node_router -->|"creates mailer"| node_mailer
node_router -->|"creates OAuth flow"| node_google
node_api -.->|"routes requests"| node_router

click node_app "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/App.tsx"
click node_authnav "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/navigation/AuthNavigator.tsx"
click node_authctx "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/context/AuthContext.tsx"
click node_eventui "https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/events"
click node_playlistui "https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/playlists"
click node_friendui "https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/friends"
click node_profileui "https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/profile"
click node_clientapi "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/api/client.ts"
click node_storage "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/storage/storage.ts"
click node_preview "https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/audio/usePreviewPlayer.ts"
click node_server "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/cmd/server/main.go"
click node_router "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/api/router.go"
click node_authsvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/auth.go"
click node_eventsvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/event.go"
click node_playlistsvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/playlist.go"
click node_socialsvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/friend.go"
click node_usersvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/user.go"
click node_subsvc "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/subscription.go"
click node_handlers "https://github.com/kaierhyeh/music-room/tree/main/musicroom-backend/internal/api/handlers"
click node_repository "https://github.com/kaierhyeh/music-room/tree/main/musicroom-backend/internal/repository"
click node_hub "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/hub/hub.go"
click node_deezer "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/deezer/client.go"
click node_mailer "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/mail/mail.go"
click node_google "https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/auth/googleoauth.go"

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_authnav,node_authctx,node_user toneBlue
class node_friendui,node_profileui,node_socialsvc,node_usersvc toneAmber
class node_eventui,node_playlistui,node_preview,node_eventsvc,node_playlistsvc,node_api toneMint
class node_server,node_router,node_authsvc,node_subsvc,node_handlers toneRose
class node_clientapi,node_storage,node_repository,node_hub,node_deezer,node_mailer,node_google toneIndigo
```

## Components

### App Experience

- [App entry](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/App.tsx): `musicroom-app/App.tsx`
- [Auth navigation](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/navigation/AuthNavigator.tsx): `musicroom-app/src/navigation/AuthNavigator.tsx`
- [Auth session](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/context/AuthContext.tsx): `musicroom-app/src/context/AuthContext.tsx`

### Social Features

- [Friend screens](https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/friends): `musicroom-app/src/screens/friends`
- [Profile screens](https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/profile): `musicroom-app/src/screens/profile`
- [Friend service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/friend.go): `musicroom-backend/internal/service/friend.go`
- [User service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/user.go): `musicroom-backend/internal/service/user.go`

### Music Collaboration

- [Event screens](https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/events): `musicroom-app/src/screens/events`
- [Playlist screens](https://github.com/kaierhyeh/music-room/tree/main/musicroom-app/src/screens/playlists): `musicroom-app/src/screens/playlists`
- [Track previews](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/audio/usePreviewPlayer.ts): `musicroom-app/src/audio/usePreviewPlayer.ts`
- [Event service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/event.go): `musicroom-backend/internal/service/event.go`
- [Playlist service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/playlist.go): `musicroom-backend/internal/service/playlist.go`

### API Services

- [HTTP server](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/cmd/server/main.go): `musicroom-backend/cmd/server/main.go`
- [Route wiring](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/api/router.go): `musicroom-backend/internal/api/router.go`
- [Account service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/auth.go): `musicroom-backend/internal/service/auth.go`
- [Subscription service](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/service/subscription.go): `musicroom-backend/internal/service/subscription.go`
- [HTTP handlers](https://github.com/kaierhyeh/music-room/tree/main/musicroom-backend/internal/api/handlers): `musicroom-backend/internal/api/handlers`

### State and Integrations

- [API client](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/api/client.ts): `musicroom-app/src/api/client.ts`
- [Token storage](https://github.com/kaierhyeh/music-room/blob/main/musicroom-app/src/storage/storage.ts): `musicroom-app/src/storage/storage.ts`
- [SQL repository](https://github.com/kaierhyeh/music-room/tree/main/musicroom-backend/internal/repository): `musicroom-backend/internal/repository`
- [Realtime hub](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/hub/hub.go): `musicroom-backend/internal/hub/hub.go`
- [Deezer integration](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/deezer/client.go): `musicroom-backend/internal/deezer/client.go`
- [Email delivery](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/mail/mail.go): `musicroom-backend/internal/mail/mail.go`
- [Google OAuth](https://github.com/kaierhyeh/music-room/blob/main/musicroom-backend/internal/auth/googleoauth.go): `musicroom-backend/internal/auth/googleoauth.go`

### Other components

- **MusicRoom user**
- **MusicRoom API**

## Connections

- MusicRoom user → App entry: uses
- App entry → Auth session: provides auth (evidence: `musicroom-app/App.tsx`)
- App entry → Auth navigation: mounts navigation
- Auth session → API client: calls auth APIs (evidence: `musicroom-app/src/context/AuthContext.tsx`)
- Auth session → Token storage: stores tokens (evidence: `musicroom-app/src/context/AuthContext.tsx`)
- Event screens → API client: requests event data
- Event screens → Track previews: plays previews (evidence: `musicroom-app/src/screens/events/EventDetailScreen.tsx`)
- Event screens → Realtime hub: receives updates
- Playlist screens → API client: requests playlist data
- Friend screens → API client: requests friend data
- Profile screens → API client: requests profile data
- API client → Token storage: reads tokens (evidence: `musicroom-app/src/api/client.ts`)
- API client → MusicRoom API: sends requests
- HTTP server → Route wiring: creates router (evidence: `musicroom-backend/cmd/server/main.go`)
- Route wiring → HTTP handlers: registers routes (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Account service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Event service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Playlist service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Friend service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → User service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Subscription service: constructs service (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → SQL repository: creates queries (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Realtime hub: creates hub (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Deezer integration: creates client (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Email delivery: creates mailer (evidence: `musicroom-backend/internal/api/router.go`)
- Route wiring → Google OAuth: creates OAuth flow (evidence: `musicroom-backend/internal/api/router.go`)
- MusicRoom API → Route wiring: routes requests
