# comp426-25f/final-project-team-6 architecture

> Architecture diagram of the GitHub repository comp426-25f/final-project-team-6, 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/comp426-25f/final-project-team-6
- Repository: https://github.com/comp426-25f/final-project-team-6

## Overview

Echo is a private-room music listening app. Users sign up or log in, create or join a room, then share synchronized playback and manage its song queue; room members can also request AI song suggestions. The graph covers the documented product stages and the sampled tRPC, database, and realtime layers. Several feature implementations are unsampled, so their internal calls are not inferred; documented capabilities are shown without inventing backend wiring.

Main entry points: [`server/api/root.ts`](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/root.ts) (Router registry), [`components/queue/queue.tsx`](https://github.com/comp426-25f/final-project-team-6/blob/main/components/queue/queue.tsx) (Queue controls), [`components/sidebar/app-sidebar.tsx`](https://github.com/comp426-25f/final-project-team-6/blob/main/components/sidebar/app-sidebar.tsx) (Room navigation), [`utils/trpc/api.ts`](https://github.com/comp426-25f/final-project-team-6/blob/main/utils/trpc/api.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_auth_pages["Sign in and signup<br/>[login.tsx]"]
  node_room_page["Room view<br/>[&#91;roomId&#93;.tsx]"]
  node_room_sidebar["Room navigation<br/>[app-sidebar.tsx]"]
  node_profile_nav["Profile controls<br/>[nav-user.tsx]"]
  node_profile_avatar["Profile avatar<br/>[profile-avatar.tsx]"]
end

subgraph group_room_music["Room and music"]
  node_song_player["Synchronized player<br/>[song-player.tsx]"]
  node_queue_ui["Queue controls<br/>[queue.tsx]"]
  node_ai_search["AI song search<br/>[client.ts]"]
end

subgraph group_api["API and domain"]
  node_trpc_client["Typed API client<br/>[api.ts]"]
  node_trpc_endpoint["tRPC endpoint<br/>[&#91;trpc&#93;.ts]"]
  node_trpc_context["Auth context<br/>[trpc.ts]"]
  node_api_root["Router registry<br/>[root.ts]"]
  node_room_routes["Room operations<br/>[rooms.ts]"]
  node_queue_routes["Queue operations<br/>[queues.ts]"]
  node_song_routes["Song operations<br/>[songs.ts]"]
  node_profile_routes["Profile operations<br/>[profiles.ts]"]
end

subgraph group_data["Identity and data"]
  node_db_client["Database access<br/>[index.ts]"]
  node_db_schema[("Room and song schema<br/>[schema.ts]")]
  node_supabase_auth[("Supabase authentication")]
  node_supabase_storage["Avatar storage<br/>[storage.ts]"]
end

node_listener(("Listener"))

node_listener -->|"signs in"| node_auth_pages
node_listener -->|"creates or joins"| node_room_sidebar
node_listener -->|"manages queue"| node_queue_ui
node_listener -->|"controls playback"| node_song_player
node_listener -->|"requests suggestions"| node_ai_search
node_auth_pages -->|"authenticates"| node_supabase_auth
node_room_sidebar -->|"uploads room avatar"| node_supabase_storage
node_room_page -->|"renders"| node_song_player
node_room_page -->|"renders"| node_queue_ui
node_queue_ui -->|"mutates queue"| node_trpc_client
node_queue_ui -->|"subscribes to changes"| node_supabase_auth
node_room_sidebar -->|"uses API"| node_trpc_client
node_trpc_client -->|"types routes"| node_api_root
node_trpc_endpoint -->|"serves router"| node_api_root
node_trpc_endpoint -->|"creates context"| node_trpc_context
node_trpc_context -->|"checks claims"| node_supabase_auth
node_api_root -->|"registers"| node_room_routes
node_api_root -->|"registers"| node_queue_routes
node_api_root -->|"registers"| node_song_routes
node_api_root -->|"registers"| node_profile_routes
node_room_routes -->|"queries"| node_db_client
node_db_client -->|"configures ORM"| node_db_schema
node_profile_nav -->|"renders"| node_profile_avatar
node_profile_nav -->|"uploads avatar"| node_supabase_storage

click node_auth_pages "https://github.com/comp426-25f/final-project-team-6/blob/main/pages/login.tsx"
click node_room_page "https://github.com/comp426-25f/final-project-team-6/blob/main/pages/%5BroomId%5D.tsx"
click node_room_sidebar "https://github.com/comp426-25f/final-project-team-6/blob/main/components/sidebar/app-sidebar.tsx"
click node_profile_nav "https://github.com/comp426-25f/final-project-team-6/blob/main/components/sidebar/nav-user.tsx"
click node_profile_avatar "https://github.com/comp426-25f/final-project-team-6/blob/main/components/profile/profile-avatar.tsx"
click node_song_player "https://github.com/comp426-25f/final-project-team-6/blob/main/components/song-player/song-player.tsx"
click node_queue_ui "https://github.com/comp426-25f/final-project-team-6/blob/main/components/queue/queue.tsx"
click node_ai_search "https://github.com/comp426-25f/final-project-team-6/blob/main/utils/openai/client.ts"
click node_trpc_client "https://github.com/comp426-25f/final-project-team-6/blob/main/utils/trpc/api.ts"
click node_trpc_endpoint "https://github.com/comp426-25f/final-project-team-6/blob/main/pages/api/trpc/%5Btrpc%5D.ts"
click node_trpc_context "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/trpc.ts"
click node_api_root "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/root.ts"
click node_room_routes "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/rooms.ts"
click node_queue_routes "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/queues.ts"
click node_song_routes "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/songs.ts"
click node_profile_routes "https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/profiles.ts"
click node_db_client "https://github.com/comp426-25f/final-project-team-6/blob/main/server/db/index.ts"
click node_db_schema "https://github.com/comp426-25f/final-project-team-6/blob/main/server/db/schema.ts"
click node_supabase_storage "https://github.com/comp426-25f/final-project-team-6/blob/main/utils/supabase/storage.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_auth_pages,node_room_page,node_room_sidebar,node_profile_nav,node_profile_avatar toneBlue
class node_song_player,node_queue_ui,node_ai_search toneAmber
class node_trpc_client,node_trpc_endpoint,node_trpc_context,node_api_root,node_room_routes,node_queue_routes,node_song_routes,node_profile_routes toneMint
class node_db_client,node_db_schema,node_supabase_auth,node_supabase_storage toneRose
class node_listener toneIndigo
```

## Components

### User experience

- [Sign in and signup](https://github.com/comp426-25f/final-project-team-6/blob/main/pages/login.tsx): `pages/login.tsx`
- [Room view](https://github.com/comp426-25f/final-project-team-6/blob/main/pages/%5BroomId%5D.tsx): `pages/[roomId].tsx`
- [Room navigation](https://github.com/comp426-25f/final-project-team-6/blob/main/components/sidebar/app-sidebar.tsx): `components/sidebar/app-sidebar.tsx`
- [Profile controls](https://github.com/comp426-25f/final-project-team-6/blob/main/components/sidebar/nav-user.tsx): `components/sidebar/nav-user.tsx`
- [Profile avatar](https://github.com/comp426-25f/final-project-team-6/blob/main/components/profile/profile-avatar.tsx): `components/profile/profile-avatar.tsx`

### Room and music

- [Synchronized player](https://github.com/comp426-25f/final-project-team-6/blob/main/components/song-player/song-player.tsx): `components/song-player/song-player.tsx`
- [Queue controls](https://github.com/comp426-25f/final-project-team-6/blob/main/components/queue/queue.tsx): `components/queue/queue.tsx`
- [AI song search](https://github.com/comp426-25f/final-project-team-6/blob/main/utils/openai/client.ts): `utils/openai/client.ts`

### API and domain

- [Typed API client](https://github.com/comp426-25f/final-project-team-6/blob/main/utils/trpc/api.ts): `utils/trpc/api.ts`
- [tRPC endpoint](https://github.com/comp426-25f/final-project-team-6/blob/main/pages/api/trpc/%5Btrpc%5D.ts): `pages/api/trpc/[trpc].ts`
- [Auth context](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/trpc.ts): `server/api/trpc.ts`
- [Router registry](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/root.ts): `server/api/root.ts`
- [Room operations](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/rooms.ts): `server/api/routers/rooms.ts`
- [Queue operations](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/queues.ts): `server/api/routers/queues.ts`
- [Song operations](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/songs.ts): `server/api/routers/songs.ts`
- [Profile operations](https://github.com/comp426-25f/final-project-team-6/blob/main/server/api/routers/profiles.ts): `server/api/routers/profiles.ts`

### Identity and data

- [Database access](https://github.com/comp426-25f/final-project-team-6/blob/main/server/db/index.ts): `server/db/index.ts`
- [Room and song schema](https://github.com/comp426-25f/final-project-team-6/blob/main/server/db/schema.ts): `server/db/schema.ts`
- **Supabase authentication**
- [Avatar storage](https://github.com/comp426-25f/final-project-team-6/blob/main/utils/supabase/storage.ts): `utils/supabase/storage.ts`

### Other components

- **Listener**

## Connections

- Listener → Sign in and signup: signs in
- Listener → Room navigation: creates or joins
- Listener → Queue controls: manages queue
- Listener → Synchronized player: controls playback
- Listener → AI song search: requests suggestions
- Sign in and signup → Supabase authentication: authenticates
- Room navigation → Avatar storage: uploads room avatar (evidence: `components/sidebar/app-sidebar.tsx`)
- Room view → Synchronized player: renders (evidence: `pages/[roomId].tsx`)
- Room view → Queue controls: renders (evidence: `pages/[roomId].tsx`)
- Queue controls → Typed API client: mutates queue (evidence: `components/queue/queue.tsx`)
- Queue controls → Supabase authentication: subscribes to changes (evidence: `components/queue/queue.tsx`)
- Room navigation → Typed API client: uses API (evidence: `components/sidebar/app-sidebar.tsx`)
- Typed API client → Router registry: types routes (evidence: `utils/trpc/api.ts`)
- tRPC endpoint → Router registry: serves router (evidence: `pages/api/trpc/[trpc].ts`)
- tRPC endpoint → Auth context: creates context (evidence: `pages/api/trpc/[trpc].ts`)
- Auth context → Supabase authentication: checks claims (evidence: `server/api/trpc.ts`)
- Router registry → Room operations: registers (evidence: `server/api/root.ts`)
- Router registry → Queue operations: registers (evidence: `server/api/root.ts`)
- Router registry → Song operations: registers (evidence: `server/api/root.ts`)
- Router registry → Profile operations: registers (evidence: `server/api/root.ts`)
- Room operations → Database access: queries (evidence: `server/api/routers/rooms.ts`)
- Database access → Room and song schema: configures ORM (evidence: `server/db/index.ts`)
- Profile controls → Profile avatar: renders (evidence: `components/sidebar/nav-user.tsx`)
- Profile controls → Avatar storage: uploads avatar (evidence: `components/sidebar/nav-user.tsx`)
