# hippomasakib1/lets-listen-together architecture

> Architecture diagram of the GitHub repository hippomasakib1/lets-listen-together, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hippomasakib1/lets-listen-together
- Repository: https://github.com/hippomasakib1/lets-listen-together

## Overview

Tune Together is a social media-listening platform: users authenticate, create or join an invited room, then synchronize playback and collaborate through queueing, chat, reactions, voice, and screen sharing. The frontend presents these room workflows; FastAPI serves REST operations while a Socket.IO hub handles live events and WebRTC signaling, with PostgreSQL-backed room and playback state. The README documents key client capabilities and network paths; unsampled frontend wiring is represented only where documented, not inferred from component names.

Main entry points: [`frontend/app/room/page.tsx`](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/room/page.tsx) (Room experience), [`backend/app/routers/rooms.py`](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/routers/rooms.py) (Room and search routes), [`backend/app/sockets/hub.py`](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/sockets/hub.py) (Socket event hub), [`backend/app/main.py`](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web Client"]
  node_web_routes["Entry and invites<br/>[page.tsx]"]
  node_auth_pages["Sign-in and registration<br/>[page.tsx]"]
  node_room_pages["Room experience<br/>[page.tsx]"]
  node_room_controls["Playback and queue<br/>[YouTubePlayer.tsx]"]
  node_chat_ui["Room chat<br/>[ChatPanel.tsx]"]
  node_member_ui["Members and voice status<br/>[MemberList.tsx]"]
  node_reactions_ui["Floating reactions"]
  node_screen_ui["Screen share viewer"]
  node_client_api["HTTP client<br/>[api.ts]"]
  node_client_socket["Socket client<br/>[socket.ts]"]
  node_webrtc_mesh["WebRTC mesh<br/>[webrtc.ts]"]
  node_auth_state["Authentication state<br/>[authStore.ts]"]
  node_room_state["Room state<br/>[roomStore.ts]"]
end

subgraph group_backend_api["REST and Identity"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_router["Authentication routes<br/>[auth.py]"]
  node_auth_schemas["Auth validation<br/>[auth.py]"]
  node_jwt["JWT verification<br/>[jwt.py]"]
  node_auth_deps["Request identity<br/>[deps.py]"]
  node_room_router["Room and search routes<br/>[rooms.py]"]
  node_room_schemas["Room validation<br/>[room.py]"]
end

subgraph group_realtime["Live Room Services"]
  node_socket_hub["Socket event hub<br/>[hub.py]"]
end

subgraph group_persistence["Persistence"]
  node_user_model["User records<br/>[user.py]"]
  node_room_model["Room and media records<br/>[room.py]"]
  node_database[("Async database<br/>[database.py]")]
end

node_participant(("Room participant"))
node_postgres[("PostgreSQL")]
node_youtube["YouTube player API"]

node_participant -->|"opens invite"| node_web_routes
node_participant -->|"authenticates"| node_auth_pages
node_participant -->|"uses room"| node_room_pages
node_web_routes -->|"preserves destination"| node_auth_pages
node_auth_pages -.->|"uses HTTP"| node_client_api
node_room_pages -.->|"presents playback"| node_room_controls
node_room_pages -.->|"presents chat"| node_chat_ui
node_room_pages -.->|"shows members"| node_member_ui
node_room_pages -.->|"shows reactions"| node_reactions_ui
node_room_pages -.->|"shows sharing"| node_screen_ui
node_room_controls -->|"controls playback"| node_youtube
node_room_pages -->|"requests REST"| node_client_api
node_client_api -->|"calls REST"| node_api_app
node_room_pages -.->|"uses live sync"| node_client_socket
node_client_socket -->|"exchanges events"| node_socket_hub
node_room_pages -->|"uses peer media"| node_webrtc_mesh
node_webrtc_mesh -->|"streams peer-to-peer"| node_participant
node_socket_hub -->|"relays signaling"| node_webrtc_mesh
node_api_app -->|"mounts routes"| node_auth_router
node_api_app -->|"mounts routes"| node_room_router
node_api_app -->|"mounts ASGI hub"| node_socket_hub
node_api_app -->|"initializes on startup"| node_database
node_auth_router -->|"gets sessions"| node_database
node_auth_router -->|"queries users"| node_user_model
node_auth_router -->|"validates payloads"| node_auth_schemas
node_auth_router -->|"creates tokens"| node_jwt
node_auth_deps -->|"verifies tokens"| node_jwt
node_room_router -->|"gets sessions"| node_database
node_room_router -->|"reads and writes"| node_room_model
node_room_router -->|"queries members"| node_user_model
node_room_router -->|"validates payloads"| node_room_schemas
node_room_router -->|"requires identity"| node_auth_deps
node_socket_hub -->|"loads sessions"| node_database
node_socket_hub -->|"updates room state"| node_room_model
node_socket_hub -->|"verifies socket token"| node_jwt
node_database -->|"persists data"| node_postgres

click node_web_routes "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/invite/%5Btoken%5D/page.tsx"
click node_auth_pages "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/login/page.tsx"
click node_room_pages "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/room/page.tsx"
click node_room_controls "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/YouTubePlayer.tsx"
click node_chat_ui "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/ChatPanel.tsx"
click node_member_ui "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/MemberList.tsx"
click node_reactions_ui "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/FloatingReactions.tsx"
click node_screen_ui "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/ScreenShareViewer.tsx"
click node_client_api "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/api.ts"
click node_client_socket "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/socket.ts"
click node_webrtc_mesh "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/webrtc.ts"
click node_auth_state "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/store/authStore.ts"
click node_room_state "https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/store/roomStore.ts"
click node_api_app "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/main.py"
click node_auth_router "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/routers/auth.py"
click node_auth_schemas "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/schemas/auth.py"
click node_jwt "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/auth/jwt.py"
click node_auth_deps "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/auth/deps.py"
click node_room_router "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/routers/rooms.py"
click node_room_schemas "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/schemas/room.py"
click node_socket_hub "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/sockets/hub.py"
click node_user_model "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/models/user.py"
click node_room_model "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/models/room.py"
click node_database "https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/database.py"

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_web_routes,node_auth_pages,node_room_pages,node_room_controls,node_chat_ui,node_member_ui,node_reactions_ui,node_screen_ui,node_client_api,node_client_socket,node_webrtc_mesh,node_auth_state,node_room_state toneBlue
class node_api_app,node_auth_router,node_auth_schemas,node_jwt,node_auth_deps,node_room_router,node_room_schemas,node_postgres toneAmber
class node_socket_hub,node_youtube toneMint
class node_user_model,node_room_model,node_database toneRose
class node_participant toneIndigo
```

## Components

### Web Client

- [Entry and invites](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/invite/%5Btoken%5D/page.tsx): `frontend/app/invite/[token]/page.tsx`
- [Sign-in and registration](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Room experience](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/app/room/page.tsx): `frontend/app/room/page.tsx`
- [Playback and queue](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/YouTubePlayer.tsx): `frontend/components/YouTubePlayer.tsx`
- [Room chat](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/ChatPanel.tsx): `frontend/components/ChatPanel.tsx`
- [Members and voice status](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/MemberList.tsx): `frontend/components/MemberList.tsx`
- [Floating reactions](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/FloatingReactions.tsx): `frontend/components/FloatingReactions.tsx`
- [Screen share viewer](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/components/ScreenShareViewer.tsx): `frontend/components/ScreenShareViewer.tsx`
- [HTTP client](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Socket client](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/socket.ts): `frontend/lib/socket.ts`
- [WebRTC mesh](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/lib/webrtc.ts): `frontend/lib/webrtc.ts`
- [Authentication state](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/store/authStore.ts): `frontend/store/authStore.ts`
- [Room state](https://github.com/hippomasakib1/lets-listen-together/blob/main/frontend/store/roomStore.ts): `frontend/store/roomStore.ts`

### REST and Identity

- [FastAPI application](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Auth validation](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/schemas/auth.py): `backend/app/schemas/auth.py`
- [JWT verification](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/auth/jwt.py): `backend/app/auth/jwt.py`
- [Request identity](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/auth/deps.py): `backend/app/auth/deps.py`
- [Room and search routes](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/routers/rooms.py): `backend/app/routers/rooms.py`
- [Room validation](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/schemas/room.py): `backend/app/schemas/room.py`

### Live Room Services

- [Socket event hub](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/sockets/hub.py): `backend/app/sockets/hub.py`

### Persistence

- [User records](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Room and media records](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/models/room.py): `backend/app/models/room.py`
- [Async database](https://github.com/hippomasakib1/lets-listen-together/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Room participant**
- **PostgreSQL**
- **YouTube player API**

## Connections

- Room participant → Entry and invites: opens invite
- Room participant → Sign-in and registration: authenticates
- Room participant → Room experience: uses room
- Entry and invites → Sign-in and registration: preserves destination
- Sign-in and registration → HTTP client: uses HTTP
- Room experience → Playback and queue: presents playback
- Room experience → Room chat: presents chat
- Room experience → Members and voice status: shows members
- Room experience → Floating reactions: shows reactions
- Room experience → Screen share viewer: shows sharing
- Playback and queue → YouTube player API: controls playback
- Room experience → HTTP client: requests REST
- HTTP client → FastAPI application: calls REST
- Room experience → Socket client: uses live sync
- Socket client → Socket event hub: exchanges events
- Room experience → WebRTC mesh: uses peer media
- WebRTC mesh → Room participant: streams peer-to-peer
- Socket event hub → WebRTC mesh: relays signaling
- FastAPI application → Authentication routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Room and search routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Socket event hub: mounts ASGI hub (evidence: `backend/app/main.py`)
- FastAPI application → Async database: initializes on startup (evidence: `backend/app/main.py`)
- Authentication routes → Async database: gets sessions (evidence: `backend/app/routers/auth.py`)
- Authentication routes → User records: queries users (evidence: `backend/app/routers/auth.py`)
- Authentication routes → Auth validation: validates payloads (evidence: `backend/app/routers/auth.py`)
- Authentication routes → JWT verification: creates tokens (evidence: `backend/app/routers/auth.py`)
- Request identity → JWT verification: verifies tokens (evidence: `backend/app/auth/deps.py`)
- Room and search routes → Async database: gets sessions (evidence: `backend/app/routers/rooms.py`)
- Room and search routes → Room and media records: reads and writes (evidence: `backend/app/routers/rooms.py`)
- Room and search routes → User records: queries members (evidence: `backend/app/routers/rooms.py`)
- Room and search routes → Room validation: validates payloads (evidence: `backend/app/routers/rooms.py`)
- Room and search routes → Request identity: requires identity (evidence: `backend/app/routers/rooms.py`)
- Socket event hub → Async database: loads sessions (evidence: `backend/app/sockets/hub.py`)
- Socket event hub → Room and media records: updates room state (evidence: `backend/app/sockets/hub.py`)
- Socket event hub → JWT verification: verifies socket token (evidence: `backend/app/sockets/hub.py`)
- Async database → PostgreSQL: persists data
