# jerome-joseph-1/ulw-video-streaming-platform architecture

> Architecture diagram of the GitHub repository jerome-joseph-1/ulw-video-streaming-platform, 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/jerome-joseph-1/ulw-video-streaming-platform
- Repository: https://github.com/jerome-joseph-1/ulw-video-streaming-platform

## Overview

ULW is a Linux video platform with a media workflow and separate realtime services. The main media path is upload, queued transcode, HLS storage, then playback via rewritten playlists and presigned segment URLs. Chat routes room activity across owner nodes; live video has separate SFU and ingest-to-packager paths. The graph combines README-documented product relationships with sampled entry-point wiring; unsampled internals are represented at their existing directory paths, and no uncertain implementation links are asserted.

Main entry points: [`apps/gateway/src`](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/gateway/src) (Gateway), [`apps/live-packager/src`](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/live-packager/src) (Live packager), [`infra/postgres`](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/postgres) (Catalog and jobs), [`infra/storage/s3`](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/storage/s3) (Object storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_media["Video platform"]
  node_gateway["Gateway"]
  node_worker["Transcode worker"]
  node_reaper["Upload reaper"]
end

subgraph group_realtime["Realtime services"]
  node_chat["Chat server"]
  node_room_router["Room router<br/>[room_router.cpp]"]
  node_chat_store[("Room and message stores")]
end

subgraph group_live["Live media"]
  node_stunner{{"STUNner"}}
  node_livekit["LiveKit SFU"]
  node_ingest["SRT ingest<br/>[ingest.cpp]"]
  node_packager["Live packager"]
  node_live_remux["Live remux<br/>[live_remux.cpp]"]
  node_recordings[("Recording catalog")]
end

subgraph group_shared["Shared infrastructure"]
  node_catalog_queue[("Catalog and jobs")]
  node_object_store[("Object storage")]
  node_ffmpeg["FFmpeg sandbox"]
  node_live_storage[("Live HLS storage<br/>[s3_transfer.cpp]")]
end

node_client(("Client"))
node_envoy{{"Envoy"}}
node_chat_client(("Chat client"))
node_call_client(("Call client"))

node_client -->|"sends requests"| node_envoy
node_envoy -->|"routes uploads"| node_gateway
node_gateway -->|"reads and writes"| node_catalog_queue
node_gateway -->|"grants upload URLs"| node_object_store
node_worker -->|"claims jobs"| node_catalog_queue
node_worker -->|"transcodes media"| node_ffmpeg
node_worker -->|"stores renditions"| node_object_store
node_gateway -->|"grants playback URLs"| node_object_store
node_gateway -->|"reads playback catalog"| node_catalog_queue
node_reaper -->|"reaps abandoned uploads"| node_catalog_queue
node_reaper -.->|"cleans abandoned data"| node_object_store
node_chat_client -->|"connects"| node_envoy
node_envoy -->|"routes chat"| node_chat
node_chat -->|"routes room activity"| node_room_router
node_chat -->|"uses room and message stores"| node_chat_store
node_room_router -->|"persists room state"| node_chat_store
node_call_client -->|"connects for calls"| node_stunner
node_stunner -->|"forwards media"| node_livekit
node_ingest -->|"feeds live stream"| node_packager
node_packager -->|"remuxes stream"| node_live_remux
node_packager -->|"publishes HLS"| node_live_storage
node_packager -->|"records stream status"| node_recordings

click node_gateway "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/gateway/src"
click node_catalog_queue "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/postgres"
click node_object_store "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/storage/s3"
click node_worker "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/worker/src"
click node_ffmpeg "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/ffmpeg"
click node_reaper "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/reaper/src"
click node_chat "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/chat/src"
click node_room_router "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/rt/src/room_router.cpp"
click node_chat_store "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/postgres/src"
click node_livekit "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/sfu/livekit/src"
click node_ingest "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/srt/src/ingest.cpp"
click node_packager "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/live-packager/src"
click node_live_remux "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/ffmpeg/src/live_remux.cpp"
click node_live_storage "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/storage/s3/src/s3_transfer.cpp"
click node_recordings "https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/postgres/src/live_recordings.cpp"

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_gateway,node_worker,node_reaper,node_client,node_chat_client,node_call_client toneBlue
class node_chat,node_room_router,node_chat_store toneAmber
class node_stunner,node_livekit,node_ingest,node_packager,node_live_remux,node_recordings toneMint
class node_catalog_queue,node_object_store,node_ffmpeg,node_live_storage toneRose
class node_envoy toneIndigo
```

## Components

### Video platform

- [Gateway](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/gateway/src): `apps/gateway/src`
- [Transcode worker](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/worker/src): `apps/worker/src`
- [Upload reaper](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/reaper/src): `apps/reaper/src`

### Realtime services

- [Chat server](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/chat/src): `apps/chat/src`
- [Room router](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/rt/src/room_router.cpp): `rt/src/room_router.cpp`
- [Room and message stores](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/postgres/src): `infra/postgres/src`

### Live media

- **STUNner**
- [LiveKit SFU](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/sfu/livekit/src): `infra/sfu/livekit/src`
- [SRT ingest](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/srt/src/ingest.cpp): `infra/srt/src/ingest.cpp`
- [Live packager](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/apps/live-packager/src): `apps/live-packager/src`
- [Live remux](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/ffmpeg/src/live_remux.cpp): `infra/ffmpeg/src/live_remux.cpp`
- [Recording catalog](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/postgres/src/live_recordings.cpp): `infra/postgres/src/live_recordings.cpp`

### Shared infrastructure

- [Catalog and jobs](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/postgres): `infra/postgres`
- [Object storage](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/storage/s3): `infra/storage/s3`
- [FFmpeg sandbox](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/tree/main/infra/ffmpeg): `infra/ffmpeg`
- [Live HLS storage](https://github.com/jerome-joseph-1/ulw-video-streaming-platform/blob/main/infra/storage/s3/src/s3_transfer.cpp): `infra/storage/s3/src/s3_transfer.cpp`

### Other components

- **Client**
- **Envoy**
- **Chat client**
- **Call client**

## Connections

- Client → Envoy: sends requests (evidence: `README.md`)
- Envoy → Gateway: routes uploads (evidence: `README.md`)
- Gateway → Catalog and jobs: reads and writes (evidence: `README.md`)
- Gateway → Object storage: grants upload URLs (evidence: `README.md`)
- Transcode worker → Catalog and jobs: claims jobs (evidence: `README.md`)
- Transcode worker → FFmpeg sandbox: transcodes media (evidence: `README.md`)
- Transcode worker → Object storage: stores renditions (evidence: `README.md`)
- Gateway → Object storage: grants playback URLs (evidence: `README.md`)
- Gateway → Catalog and jobs: reads playback catalog (evidence: `README.md`)
- Upload reaper → Catalog and jobs: reaps abandoned uploads (evidence: `README.md`)
- Upload reaper → Object storage: cleans abandoned data (evidence: `apps/reaper/src/main.cpp`)
- Chat client → Envoy: connects (evidence: `README.md`)
- Envoy → Chat server: routes chat (evidence: `README.md`)
- Chat server → Room router: routes room activity (evidence: `apps/chat/src/main.cpp`)
- Chat server → Room and message stores: uses room and message stores (evidence: `apps/chat/src/main.cpp`)
- Room router → Room and message stores: persists room state
- Call client → STUNner: connects for calls (evidence: `README.md`)
- STUNner → LiveKit SFU: forwards media (evidence: `README.md`)
- SRT ingest → Live packager: feeds live stream (evidence: `README.md`)
- Live packager → Live remux: remuxes stream (evidence: `apps/live-packager/src/main.cpp`)
- Live packager → Live HLS storage: publishes HLS (evidence: `README.md`)
- Live packager → Recording catalog: records stream status (evidence: `apps/live-packager/src/main.cpp`)
