# nersus15/kamscode-meet-service architecture

> Architecture diagram of the GitHub repository nersus15/kamscode-meet-service, 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/nersus15/kamscode-meet-service
- Repository: https://github.com/nersus15/kamscode-meet-service

## Overview

This repository implements a room-based video-meeting backend: an HTTP API manages accounts and rooms, then issues short-lived join tokens; clients use those tokens to connect to a WebSocket signaling service and exchange media through an SFU. The API also provisions ICE/TURN settings, while the SFU manages participants, peer connections, media forwarding, chat, and participant state. The graph shows only relationships supported by the excerpts, SOURCE INDEX references, or explicit code wiring; several internal storage and SFU interactions are not fully sampled.

Main entry points: [`apps/api/main.go`](https://github.com/nersus15/kamscode-meet-service/blob/main/apps/api/main.go) (API Service), [`internal/signaling/handler.go`](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/signaling/handler.go) (WebSocket Signaling), [`internal/api/auth.go`](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/auth.go) (Account Handlers), [`internal/api/rooms.go`](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/rooms.go) (Room Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_main["API Service<br/>[main.go]"]
  node_api_routes["HTTP Routing<br/>[server.go]"]
  node_api_auth["Account Handlers<br/>[auth.go]"]
  node_api_rooms["Room Handlers<br/>[rooms.go]"]
end

subgraph group_identity["Identity and Data"]
  node_user_store["User Store<br/>[user.go]"]
  node_session_store["Session Store<br/>[session.go]"]
  node_passwords["Password Auth<br/>[password.go]"]
  node_room_store["Room Store<br/>[room.go]"]
  node_database[("PostgreSQL<br/>[db.go]")]
  node_join_tokens["Join Tokens<br/>[token.go]"]
  node_turn_provider["ICE and TURN<br/>[turn.go]"]
end

subgraph group_realtime["Signaling and SFU"]
  node_sfu_main["SFU Service<br/>[main.go]"]
  node_signaling["WebSocket Signaling<br/>[handler.go]"]
  node_ws_connection["WebSocket Connection<br/>[conn.go]"]
  node_protocol["Message Protocol<br/>[message.go]"]
  node_sfu_server["SFU Server<br/>[server.go]"]
  node_sfu_room["Live Rooms<br/>[room.go]"]
  node_participant["Participants<br/>[participant.go]"]
end

subgraph group_media["Media and Collaboration"]
  node_peer["Peer Connections<br/>[peer.go]"]
  node_publisher["Publisher Peer<br/>[publisher.go]"]
  node_subscriber["Subscriber Peer<br/>[subscriber.go]"]
  node_media_tracks["Media Tracks<br/>[media.go]"]
  node_forwarder["RTP Forwarding<br/>[forwarder.go]"]
  node_chat["Room Chat<br/>[chat.go]"]
end

node_client(("Meeting Client"))

node_client -->|"uses API"| node_api_routes
node_api_main -->|"opens and migrates"| node_database
node_api_main -->|"serves routes"| node_api_routes
node_api_main -->|"constructs"| node_user_store
node_api_main -->|"constructs"| node_session_store
node_api_main -->|"constructs"| node_room_store
node_api_main -->|"configures signer"| node_join_tokens
node_api_main -->|"configures provider"| node_turn_provider
node_api_routes -->|"routes auth"| node_api_auth
node_api_routes -->|"routes rooms"| node_api_rooms
node_api_auth -->|"reads and creates users"| node_user_store
node_api_auth -->|"hashes and verifies"| node_passwords
node_api_auth -->|"creates and deletes sessions"| node_session_store
node_api_rooms -->|"manages rooms"| node_room_store
node_api_rooms -->|"signs join token"| node_join_tokens
node_api_rooms -->|"returns ICE servers"| node_turn_provider
node_client -->|"opens WebSocket"| node_sfu_main
node_sfu_main -->|"routes /ws"| node_signaling
node_sfu_main -->|"creates and closes"| node_sfu_server
node_sfu_main -->|"loads ICE servers"| node_turn_provider
node_signaling -->|"verifies token"| node_join_tokens
node_signaling -->|"joins participants"| node_sfu_server
node_signaling -->|"handles messages"| node_protocol
node_signaling -->|"dispatches chat"| node_chat
node_ws_connection -->|"encodes and decodes"| node_protocol
node_sfu_server -->|"creates and manages"| node_sfu_room
node_sfu_room -->|"creates peer connections"| node_peer
node_participant -->|"selects peer by role"| node_peer
node_sfu_room -->|"forwards tracks"| node_forwarder
node_media_tracks -->|"uses forwarder"| node_forwarder
node_sfu_room -->|"tracks published media"| node_media_tracks
node_peer -.->|"specialized implementation"| node_publisher
node_peer -.->|"specialized implementation"| node_subscriber

click node_api_main "https://github.com/nersus15/kamscode-meet-service/blob/main/apps/api/main.go"
click node_api_routes "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/server.go"
click node_api_auth "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/auth.go"
click node_api_rooms "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/rooms.go"
click node_user_store "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/user/user.go"
click node_session_store "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/auth/session.go"
click node_passwords "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/auth/password.go"
click node_room_store "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/room/room.go"
click node_database "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/db/db.go"
click node_join_tokens "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/token/token.go"
click node_turn_provider "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/turn/turn.go"
click node_sfu_main "https://github.com/nersus15/kamscode-meet-service/blob/main/apps/sfu/main.go"
click node_signaling "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/signaling/handler.go"
click node_ws_connection "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/signaling/conn.go"
click node_protocol "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/protocol/message.go"
click node_sfu_server "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/server.go"
click node_sfu_room "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/room.go"
click node_participant "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/participant.go"
click node_peer "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/peer.go"
click node_publisher "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/publisher.go"
click node_subscriber "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/subscriber.go"
click node_media_tracks "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/media.go"
click node_forwarder "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/router/forwarder.go"
click node_chat "https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/chat.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_api_main,node_api_routes,node_api_auth,node_api_rooms,node_client toneBlue
class node_user_store,node_session_store,node_passwords,node_room_store,node_database,node_join_tokens,node_turn_provider toneAmber
class node_sfu_main,node_signaling,node_ws_connection,node_protocol,node_sfu_server,node_sfu_room,node_participant toneMint
class node_peer,node_publisher,node_subscriber,node_media_tracks,node_forwarder,node_chat toneRose
```

## Components

### HTTP API

- [API Service](https://github.com/nersus15/kamscode-meet-service/blob/main/apps/api/main.go): `apps/api/main.go`
- [HTTP Routing](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/server.go): `internal/api/server.go`
- [Account Handlers](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/auth.go): `internal/api/auth.go`
- [Room Handlers](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/api/rooms.go): `internal/api/rooms.go`

### Identity and Data

- [User Store](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/user/user.go): `internal/user/user.go`
- [Session Store](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/auth/session.go): `internal/auth/session.go`
- [Password Auth](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/auth/password.go): `internal/auth/password.go`
- [Room Store](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/room/room.go): `internal/room/room.go`
- [PostgreSQL](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/db/db.go): `internal/db/db.go`
- [Join Tokens](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/token/token.go): `internal/token/token.go`
- [ICE and TURN](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/turn/turn.go): `internal/turn/turn.go`

### Signaling and SFU

- [SFU Service](https://github.com/nersus15/kamscode-meet-service/blob/main/apps/sfu/main.go): `apps/sfu/main.go`
- [WebSocket Signaling](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/signaling/handler.go): `internal/signaling/handler.go`
- [WebSocket Connection](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/signaling/conn.go): `internal/signaling/conn.go`
- [Message Protocol](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/protocol/message.go): `internal/protocol/message.go`
- [SFU Server](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/server.go): `internal/sfu/server.go`
- [Live Rooms](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/room.go): `internal/sfu/room.go`
- [Participants](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/participant.go): `internal/sfu/participant.go`

### Media and Collaboration

- [Peer Connections](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/peer.go): `internal/sfu/peer/peer.go`
- [Publisher Peer](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/publisher.go): `internal/sfu/peer/publisher.go`
- [Subscriber Peer](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/peer/subscriber.go): `internal/sfu/peer/subscriber.go`
- [Media Tracks](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/media.go): `internal/sfu/media.go`
- [RTP Forwarding](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/router/forwarder.go): `internal/sfu/router/forwarder.go`
- [Room Chat](https://github.com/nersus15/kamscode-meet-service/blob/main/internal/sfu/chat.go): `internal/sfu/chat.go`

### Other components

- **Meeting Client**

## Connections

- Meeting Client → HTTP Routing: uses API (evidence: `internal/api/server.go`)
- API Service → PostgreSQL: opens and migrates (evidence: `apps/api/main.go`)
- API Service → HTTP Routing: serves routes (evidence: `apps/api/main.go`)
- API Service → User Store: constructs (evidence: `apps/api/main.go`)
- API Service → Session Store: constructs (evidence: `apps/api/main.go`)
- API Service → Room Store: constructs (evidence: `apps/api/main.go`)
- API Service → Join Tokens: configures signer (evidence: `apps/api/main.go`)
- API Service → ICE and TURN: configures provider (evidence: `apps/api/main.go`)
- HTTP Routing → Account Handlers: routes auth (evidence: `internal/api/server.go`)
- HTTP Routing → Room Handlers: routes rooms (evidence: `internal/api/server.go`)
- Account Handlers → User Store: reads and creates users (evidence: `internal/api/auth.go`)
- Account Handlers → Password Auth: hashes and verifies (evidence: `internal/api/auth.go`)
- Account Handlers → Session Store: creates and deletes sessions (evidence: `internal/api/auth.go`)
- Room Handlers → Room Store: manages rooms (evidence: `internal/api/rooms.go`)
- Room Handlers → Join Tokens: signs join token (evidence: `internal/api/rooms.go`)
- Room Handlers → ICE and TURN: returns ICE servers (evidence: `internal/api/rooms.go`)
- Meeting Client → SFU Service: opens WebSocket (evidence: `apps/sfu/main.go`)
- SFU Service → WebSocket Signaling: routes /ws (evidence: `apps/sfu/main.go`)
- SFU Service → SFU Server: creates and closes (evidence: `apps/sfu/main.go`)
- SFU Service → ICE and TURN: loads ICE servers (evidence: `apps/sfu/main.go`)
- WebSocket Signaling → Join Tokens: verifies token (evidence: `internal/signaling/handler.go`)
- WebSocket Signaling → SFU Server: joins participants (evidence: `internal/signaling/handler.go`)
- WebSocket Signaling → Message Protocol: handles messages (evidence: `internal/signaling/handler.go`)
- WebSocket Signaling → Room Chat: dispatches chat (evidence: `internal/signaling/handler.go`)
- WebSocket Connection → Message Protocol: encodes and decodes (evidence: `internal/signaling/conn.go`)
- SFU Server → Live Rooms: creates and manages (evidence: `internal/sfu/server.go`)
- Live Rooms → Peer Connections: creates peer connections (evidence: `internal/sfu/room.go`)
- Participants → Peer Connections: selects peer by role (evidence: `internal/sfu/participant.go`)
- Live Rooms → RTP Forwarding: forwards tracks (evidence: `internal/sfu/room.go`)
- Media Tracks → RTP Forwarding: uses forwarder (evidence: `internal/sfu/media.go`)
- Live Rooms → Media Tracks: tracks published media (evidence: `internal/sfu/room.go`)
- Peer Connections → Publisher Peer: specialized implementation
- Peer Connections → Subscriber Peer: specialized implementation