# jayjayloven/karaoke architecture

> Architecture diagram of the GitHub repository jayjayloven/karaoke, 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/jayjayloven/karaoke
- Repository: https://github.com/jayjayloven/karaoke

## Overview

Karaoke is an Express backend for users, shared rooms, and per-room song queues, with PostgreSQL persistence and WebSocket room broadcasts. The main workflow is an API request routed through a controller to a use case, which validates domain state, changes room/user/queue data through repositories, and may broadcast an update. The README also documents MinIO as a deployed service, but the supplied source index shows no application integration for it; the graph therefore leaves it unconnected. Edges reflect the supplied excerpts, source-index references, or README statements.

Main entry points: [`src/shared/core/dependencies.ts`](https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/dependencies.ts) (Dependency wiring), [`src/modules/room/application`](https://github.com/jayjayloven/karaoke/tree/main/src/modules/room/application) (Room use cases), [`src/modules/song-queue/application`](https://github.com/jayjayloven/karaoke/tree/main/src/modules/song-queue/application) (Queue use cases), [`src/modules/user/infrastructure/UserRepository.ts`](https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/infrastructure/UserRepository.ts) (User repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["Express app<br/>[app.ts]"]
  node_user_routes["User routes<br/>[UserRoutes.ts]"]
  node_user_controller["User controller<br/>[UserController.ts]"]
  node_room_routes["Room routes<br/>[RoomRoutes.ts]"]
  node_room_controller["Room controller<br/>[RoomController.ts]"]
  node_queue_routes["Queue routes<br/>[SongQueueRoutes.ts]"]
  node_queue_controller["Queue controller"]
end

subgraph group_identity["Users"]
  node_user_usecases["User use cases"]
  node_user_domain["User model<br/>[User.ts]"]
  node_user_repo["User repository<br/>[UserRepository.ts]"]
end

subgraph group_rooms["Rooms"]
  node_room_usecases["Room use cases"]
  node_room_domain["Room model<br/>[Room.ts]"]
  node_room_repo["Room repository<br/>[RoomRepository.ts]"]
end

subgraph group_queue["Song queue"]
  node_queue_usecases["Queue use cases"]
  node_song_domain["Song entry<br/>[SongEntry.ts]"]
  node_queue_repo["Queue repository"]
end

subgraph group_shared["Shared services"]
  node_validators["Request validators"]
  node_dependencies["Dependency wiring<br/>[dependencies.ts]"]
  node_ws_manager["WebSocket manager"]
  node_db_pool["PostgreSQL pool<br/>[postgres.ts]"]
end

node_caller(("API client"))
node_postgres[("PostgreSQL")]
node_minio[("MinIO storage")]

node_caller -->|"sends requests"| node_server
node_server -->|"starts"| node_app
node_app -->|"mounts"| node_user_routes
node_app -->|"mounts"| node_room_routes
node_app -->|"mounts"| node_queue_routes
node_user_routes -->|"routes to"| node_user_controller
node_room_routes -->|"routes to"| node_room_controller
node_queue_routes -->|"routes to"| node_queue_controller
node_user_controller -->|"invokes"| node_user_usecases
node_room_controller -->|"invokes"| node_room_usecases
node_queue_controller -->|"invokes"| node_queue_usecases
node_user_usecases -->|"persists users"| node_user_repo
node_user_repo -->|"builds entities"| node_user_domain
node_room_usecases -->|"changes rooms"| node_room_repo
node_room_usecases -->|"updates members"| node_user_repo
node_room_repo -->|"builds entities"| node_room_domain
node_queue_usecases -->|"changes queue"| node_queue_repo
node_queue_repo -->|"builds entries"| node_song_domain
node_room_usecases -->|"validates requests"| node_validators
node_queue_usecases -->|"validates requests"| node_validators
node_user_usecases -->|"validates requests"| node_validators
node_room_usecases -->|"broadcasts updates"| node_ws_manager
node_queue_usecases -->|"broadcasts updates"| node_ws_manager
node_dependencies -->|"constructs"| node_room_repo
node_dependencies -->|"constructs"| node_user_repo
node_dependencies -->|"constructs"| node_queue_repo
node_dependencies -->|"wires dependencies"| node_room_usecases
node_dependencies -->|"wires dependencies"| node_user_usecases
node_dependencies -->|"wires dependencies"| node_queue_usecases
node_dependencies -->|"constructs"| node_validators
node_dependencies -->|"constructs"| node_ws_manager
node_room_repo -->|"queries"| node_db_pool
node_user_repo -->|"queries"| node_db_pool
node_queue_repo -->|"queries"| node_db_pool
node_db_pool -->|"connects"| node_postgres

click node_server "https://github.com/jayjayloven/karaoke/blob/main/src/server.ts"
click node_app "https://github.com/jayjayloven/karaoke/blob/main/src/app.ts"
click node_user_routes "https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/presentation/UserRoutes.ts"
click node_user_controller "https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/presentation/UserController.ts"
click node_room_routes "https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/presentation/RoomRoutes.ts"
click node_room_controller "https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/presentation/RoomController.ts"
click node_queue_routes "https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/presentation/SongQueueRoutes.ts"
click node_queue_controller "https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/presentation/SongQueueController.ts"
click node_user_usecases "https://github.com/jayjayloven/karaoke/tree/main/src/modules/user/application"
click node_user_domain "https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/domain/User.ts"
click node_user_repo "https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/infrastructure/UserRepository.ts"
click node_room_usecases "https://github.com/jayjayloven/karaoke/tree/main/src/modules/room/application"
click node_room_domain "https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/domain/Room.ts"
click node_room_repo "https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/infrastructure/RoomRepository.ts"
click node_queue_usecases "https://github.com/jayjayloven/karaoke/tree/main/src/modules/song-queue/application"
click node_song_domain "https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/domain/SongEntry.ts"
click node_queue_repo "https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/infrastructure/SongQueueRepository.ts"
click node_validators "https://github.com/jayjayloven/karaoke/blob/main/src/shared/RequestValidators.ts"
click node_dependencies "https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/dependencies.ts"
click node_ws_manager "https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/WebSocketConnectionManager.ts"
click node_db_pool "https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/postgres.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_server,node_app,node_user_routes,node_user_controller,node_room_routes,node_room_controller,node_queue_routes,node_queue_controller,node_caller toneBlue
class node_user_usecases,node_user_domain,node_user_repo,node_postgres,node_minio toneAmber
class node_room_usecases,node_room_domain,node_room_repo toneMint
class node_queue_usecases,node_song_domain,node_queue_repo toneRose
class node_validators,node_dependencies,node_ws_manager,node_db_pool toneIndigo
```

## Components

### API entry

- [HTTP server](https://github.com/jayjayloven/karaoke/blob/main/src/server.ts): `src/server.ts`
- [Express app](https://github.com/jayjayloven/karaoke/blob/main/src/app.ts): `src/app.ts`
- [User routes](https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/presentation/UserRoutes.ts): `src/modules/user/presentation/UserRoutes.ts`
- [User controller](https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/presentation/UserController.ts): `src/modules/user/presentation/UserController.ts`
- [Room routes](https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/presentation/RoomRoutes.ts): `src/modules/room/presentation/RoomRoutes.ts`
- [Room controller](https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/presentation/RoomController.ts): `src/modules/room/presentation/RoomController.ts`
- [Queue routes](https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/presentation/SongQueueRoutes.ts): `src/modules/song-queue/presentation/SongQueueRoutes.ts`
- [Queue controller](https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/presentation/SongQueueController.ts): `src/modules/song-queue/presentation/SongQueueController.ts`

### Users

- [User use cases](https://github.com/jayjayloven/karaoke/tree/main/src/modules/user/application): `src/modules/user/application`
- [User model](https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/domain/User.ts): `src/modules/user/domain/User.ts`
- [User repository](https://github.com/jayjayloven/karaoke/blob/main/src/modules/user/infrastructure/UserRepository.ts): `src/modules/user/infrastructure/UserRepository.ts`

### Rooms

- [Room use cases](https://github.com/jayjayloven/karaoke/tree/main/src/modules/room/application): `src/modules/room/application`
- [Room model](https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/domain/Room.ts): `src/modules/room/domain/Room.ts`
- [Room repository](https://github.com/jayjayloven/karaoke/blob/main/src/modules/room/infrastructure/RoomRepository.ts): `src/modules/room/infrastructure/RoomRepository.ts`

### Song queue

- [Queue use cases](https://github.com/jayjayloven/karaoke/tree/main/src/modules/song-queue/application): `src/modules/song-queue/application`
- [Song entry](https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/domain/SongEntry.ts): `src/modules/song-queue/domain/SongEntry.ts`
- [Queue repository](https://github.com/jayjayloven/karaoke/blob/main/src/modules/song-queue/infrastructure/SongQueueRepository.ts): `src/modules/song-queue/infrastructure/SongQueueRepository.ts`

### Shared services

- [Request validators](https://github.com/jayjayloven/karaoke/blob/main/src/shared/RequestValidators.ts): `src/shared/RequestValidators.ts`
- [Dependency wiring](https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/dependencies.ts): `src/shared/core/dependencies.ts`
- [WebSocket manager](https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/WebSocketConnectionManager.ts): `src/shared/core/WebSocketConnectionManager.ts`
- [PostgreSQL pool](https://github.com/jayjayloven/karaoke/blob/main/src/shared/core/postgres.ts): `src/shared/core/postgres.ts`

### Other components

- **API client**
- **PostgreSQL**
- **MinIO storage**

## Connections

- API client → HTTP server: sends requests (evidence: `README.md`)
- HTTP server → Express app: starts (evidence: `src/server.ts`)
- Express app → User routes: mounts (evidence: `src/app.ts`)
- Express app → Room routes: mounts (evidence: `src/app.ts`)
- Express app → Queue routes: mounts (evidence: `src/app.ts`)
- User routes → User controller: routes to (evidence: `src/modules/user/presentation/UserRoutes.ts`)
- Room routes → Room controller: routes to (evidence: `src/modules/room/presentation/RoomRoutes.ts`)
- Queue routes → Queue controller: routes to (evidence: `src/modules/song-queue/presentation/SongQueueRoutes.ts`)
- User controller → User use cases: invokes (evidence: `src/modules/user/presentation/UserController.ts`)
- Room controller → Room use cases: invokes (evidence: `src/modules/room/presentation/RoomController.ts`)
- Queue controller → Queue use cases: invokes (evidence: `src/modules/song-queue/presentation/SongQueueController.ts`)
- User use cases → User repository: persists users (evidence: `src/modules/user/application/CreateUserUseCase.ts`)
- User repository → User model: builds entities (evidence: `src/modules/user/infrastructure/UserRepository.ts`)
- Room use cases → Room repository: changes rooms (evidence: `src/modules/room/application/LeaveRoomUseCase.ts`)
- Room use cases → User repository: updates members (evidence: `src/modules/room/application/LeaveRoomUseCase.ts`)
- Room repository → Room model: builds entities (evidence: `src/modules/room/infrastructure/RoomRepository.ts`)
- Queue use cases → Queue repository: changes queue (evidence: `src/modules/song-queue/application/QueueSongUseCase.ts`)
- Queue repository → Song entry: builds entries (evidence: `src/modules/song-queue/infrastructure/SongQueueRepository.ts`)
- Room use cases → Request validators: validates requests (evidence: `src/modules/room/application/LeaveRoomUseCase.ts`)
- Queue use cases → Request validators: validates requests (evidence: `src/modules/song-queue/application/QueueSongUseCase.ts`)
- User use cases → Request validators: validates requests (evidence: `src/modules/user/application/UpdateUsernameUseCase.ts`)
- Room use cases → WebSocket manager: broadcasts updates (evidence: `src/modules/room/application/LeaveRoomUseCase.ts`)
- Queue use cases → WebSocket manager: broadcasts updates (evidence: `src/modules/song-queue/application/QueueSongUseCase.ts`)
- Dependency wiring → Room repository: constructs (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → User repository: constructs (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → Queue repository: constructs (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → Room use cases: wires dependencies (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → User use cases: wires dependencies (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → Queue use cases: wires dependencies (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → Request validators: constructs (evidence: `src/shared/core/dependencies.ts`)
- Dependency wiring → WebSocket manager: constructs (evidence: `src/shared/core/dependencies.ts`)
- Room repository → PostgreSQL pool: queries (evidence: `src/modules/room/infrastructure/RoomRepository.ts`)
- User repository → PostgreSQL pool: queries (evidence: `src/modules/user/infrastructure/UserRepository.ts`)
- Queue repository → PostgreSQL pool: queries (evidence: `src/modules/song-queue/infrastructure/SongQueueRepository.ts`)
- PostgreSQL pool → PostgreSQL: connects (evidence: `src/shared/core/postgres.ts`)