# andrechiapetta/karaokeando architecture

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

- Interactive diagram: https://gitdiagram.com/andrechiapetta/karaokeando
- Repository: https://github.com/andrechiapetta/karaokeando

## Overview

Karaokêando is a real-time social karaoke app: a host creates a room, guests join on mobile to find and queue songs or choose duet partners, and the TV plays songs while displaying live room state and rankings. The backend owns room coordination, WebSocket updates, authentication, and persistence; the frontend supplies host, guest, and TV experiences. The README documents the main product capabilities; some subsystem connections are omitted where sampled source does not show the caller.

Main entry points: [`frontend/src/main.tsx`](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/main.tsx) (App routing), [`frontend/src/api.ts`](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/api.ts) (API and WebSocket), [`backend/src/lib/prisma.ts`](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/prisma.ts) (Prisma client), [`frontend/src/pages/RoomMobile.tsx`](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/RoomMobile.tsx) (Mobile controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experiences"]
  node_frontend_router["App routing<br/>[main.tsx]"]
  node_auth_ui["Auth flows<br/>[AuthContext.tsx]"]
  node_room_setup["Room setup<br/>[CreateRoom.tsx]"]
  node_home["Home and join<br/>[Home.tsx]"]
  node_mobile["Mobile controller<br/>[RoomMobile.tsx]"]
  node_tv["TV player<br/>[RoomTV.tsx]"]
  node_admin["Admin dashboard<br/>[Dashboard.tsx]"]
  node_api_client["API and WebSocket<br/>[api.ts]"]
end

subgraph group_room["Live room"]
  node_room_server["Room runtime<br/>[server.ts]"]
  node_room_routes["Room endpoints<br/>[rooms.ts]"]
end

subgraph group_identity["Identity and rooms"]
  node_auth_routes["Auth endpoints<br/>[auth.ts]"]
  node_auth_crypto["Password and tokens<br/>[auth.ts]"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_database[("PostgreSQL<br/>[schema.prisma]")]
end

subgraph group_catalog["Song catalog and scoring"]
  node_song_search["Song search<br/>[server.ts]"]
  node_song_library["Saved songs<br/>[songs.ts]"]
  node_score_overlay["Score display<br/>[ScoreOverlay.tsx]"]
  node_score_logic["Score calculation<br/>[pikaraokeScore.ts]"]
  node_score_reviews["Score reviews"]
  node_fireworks["Score effects<br/>[fireworks.ts]"]
end

node_host(("Host"))
node_guests(("Guests"))
node_youtube["YouTube"]

node_host -->|"uses"| node_frontend_router
node_guests -->|"join rooms"| node_frontend_router
node_frontend_router -->|"routes to"| node_home
node_frontend_router -->|"routes to"| node_mobile
node_frontend_router -->|"routes to"| node_tv
node_frontend_router -->|"routes to"| node_admin
node_frontend_router -->|"provides"| node_auth_ui
node_host -->|"creates rooms"| node_room_setup
node_room_setup -->|"creates room"| node_api_client
node_mobile -->|"searches and queues"| node_api_client
node_tv -->|"controls playback"| node_api_client
node_admin -->|"requests data"| node_api_client
node_auth_ui -->|"requests auth"| node_api_client
node_api_client -->|"calls API and WebSocket"| node_room_server
node_room_server -->|"registers routes"| node_room_routes
node_room_server -->|"restores rooms"| node_prisma
node_room_routes -->|"reads and writes"| node_prisma
node_auth_routes -->|"reads and writes"| node_prisma
node_auth_routes -->|"hashes and verifies"| node_auth_crypto
node_room_routes -->|"checks user"| node_auth_routes
node_prisma -->|"persists data"| node_database
node_mobile -->|"searches YouTube"| node_song_search
node_mobile -->|"loads saved songs"| node_song_library
node_room_server -->|"loads library"| node_song_library
node_song_library -->|"reads songs"| node_prisma
node_song_search -->|"searches videos"| node_youtube
node_tv -->|"shows score"| node_score_overlay
node_score_overlay -->|"calculates score"| node_score_logic
node_score_overlay -->|"launches effects"| node_fireworks
node_score_logic -->|"selects review"| node_score_reviews

click node_frontend_router "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/main.tsx"
click node_auth_ui "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/context/AuthContext.tsx"
click node_room_setup "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/CreateRoom.tsx"
click node_home "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/Home.tsx"
click node_mobile "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/RoomMobile.tsx"
click node_tv "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/RoomTV.tsx"
click node_admin "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/Dashboard.tsx"
click node_api_client "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/api.ts"
click node_room_server "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/server.ts"
click node_room_routes "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/routes/rooms.ts"
click node_song_search "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/server.ts"
click node_song_library "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/songs.ts"
click node_score_overlay "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/components/ScoreOverlay.tsx"
click node_score_logic "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/pikaraokeScore.ts"
click node_score_reviews "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/pikaraokeReviews.ts"
click node_fireworks "https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/fireworks.ts"
click node_auth_routes "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/routes/auth.ts"
click node_auth_crypto "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/auth.ts"
click node_prisma "https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/prisma.ts"
click node_database "https://github.com/andrechiapetta/karaokeando/blob/main/backend/prisma/schema.prisma"

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_frontend_router,node_auth_ui,node_room_setup,node_home,node_mobile,node_tv,node_admin,node_api_client toneBlue
class node_room_server,node_room_routes toneAmber
class node_auth_routes,node_auth_crypto,node_prisma,node_database toneMint
class node_song_search,node_song_library,node_score_overlay,node_score_logic,node_score_reviews,node_fireworks toneRose
class node_host,node_guests,node_youtube toneIndigo
```

## Components

### Web experiences

- [App routing](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Auth flows](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Room setup](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/CreateRoom.tsx): `frontend/src/pages/CreateRoom.tsx`
- [Home and join](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Mobile controller](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/RoomMobile.tsx): `frontend/src/pages/RoomMobile.tsx`
- [TV player](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/RoomTV.tsx): `frontend/src/pages/RoomTV.tsx`
- [Admin dashboard](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [API and WebSocket](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Live room

- [Room runtime](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Room endpoints](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/routes/rooms.ts): `backend/src/routes/rooms.ts`

### Identity and rooms

- [Auth endpoints](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Password and tokens](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/auth.ts): `backend/src/lib/auth.ts`
- [Prisma client](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/prisma.ts): `backend/src/lib/prisma.ts`
- [PostgreSQL](https://github.com/andrechiapetta/karaokeando/blob/main/backend/prisma/schema.prisma): `backend/prisma/schema.prisma`

### Song catalog and scoring

- [Song search](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Saved songs](https://github.com/andrechiapetta/karaokeando/blob/main/backend/src/lib/songs.ts): `backend/src/lib/songs.ts`
- [Score display](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/components/ScoreOverlay.tsx): `frontend/src/components/ScoreOverlay.tsx`
- [Score calculation](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/pikaraokeScore.ts): `frontend/src/score/pikaraokeScore.ts`
- [Score reviews](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/pikaraokeReviews.ts): `frontend/src/score/pikaraokeReviews.ts`
- [Score effects](https://github.com/andrechiapetta/karaokeando/blob/main/frontend/src/score/fireworks.ts): `frontend/src/score/fireworks.ts`

### Other components

- **Host**
- **Guests**
- **YouTube**

## Connections

- Host → App routing: uses (evidence: `README.md`)
- Guests → App routing: join rooms (evidence: `README.md`)
- App routing → Home and join: routes to (evidence: `frontend/src/main.tsx`)
- App routing → Mobile controller: routes to (evidence: `frontend/src/main.tsx`)
- App routing → TV player: routes to (evidence: `frontend/src/main.tsx`)
- App routing → Admin dashboard: routes to (evidence: `frontend/src/main.tsx`)
- App routing → Auth flows: provides (evidence: `frontend/src/main.tsx`)
- Host → Room setup: creates rooms (evidence: `README.md`)
- Room setup → API and WebSocket: creates room (evidence: `frontend/src/pages/CreateRoom.tsx`)
- Mobile controller → API and WebSocket: searches and queues (evidence: `frontend/src/pages/RoomMobile.tsx`)
- TV player → API and WebSocket: controls playback (evidence: `frontend/src/pages/RoomTV.tsx`)
- Admin dashboard → API and WebSocket: requests data (evidence: `frontend/src/pages/Dashboard.tsx`)
- Auth flows → API and WebSocket: requests auth (evidence: `frontend/src/context/AuthContext.tsx`)
- API and WebSocket → Room runtime: calls API and WebSocket (evidence: `README.md`)
- Room runtime → Room endpoints: registers routes (evidence: `backend/src/server.ts`)
- Room runtime → Prisma client: restores rooms (evidence: `backend/src/server.ts`)
- Room endpoints → Prisma client: reads and writes (evidence: `backend/src/routes/rooms.ts`)
- Auth endpoints → Prisma client: reads and writes (evidence: `backend/src/routes/auth.ts`)
- Auth endpoints → Password and tokens: hashes and verifies (evidence: `backend/src/routes/auth.ts`)
- Room endpoints → Auth endpoints: checks user (evidence: `backend/src/routes/rooms.ts`)
- Prisma client → PostgreSQL: persists data (evidence: `README.md`)
- Mobile controller → Song search: searches YouTube (evidence: `frontend/src/pages/RoomMobile.tsx`)
- Mobile controller → Saved songs: loads saved songs (evidence: `README.md`)
- Room runtime → Saved songs: loads library (evidence: `backend/src/server.ts`)
- Saved songs → Prisma client: reads songs (evidence: `backend/src/lib/songs.ts`)
- Song search → YouTube: searches videos (evidence: `README.md`)
- TV player → Score display: shows score (evidence: `README.md`)
- Score display → Score calculation: calculates score (evidence: `frontend/src/components/ScoreOverlay.tsx`)
- Score display → Score effects: launches effects (evidence: `frontend/src/components/ScoreOverlay.tsx`)
- Score calculation → Score reviews: selects review (evidence: `frontend/src/score/pikaraokeScore.ts`)
