# superstreamerapp/superstreamer architecture

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

- Interactive diagram: https://gitdiagram.com/superstreamerapp/superstreamer
- Repository: https://github.com/superstreamerapp/superstreamer

## Overview

Superstreamer is a self-hostable video-delivery platform: users submit processing work, produce packaged HLS media in object storage, then browse or play it; the platform also stitches dynamic playlists with interstitials and ads. The API, dashboard, artisan workers, stitcher, and player facade form the principal product areas. The README documents the processing, packaging, ad, and playback capabilities; sampled source confirms API route mounting and storage browsing/preview behavior. Unsampled worker and stitcher links are omitted where no direct wiring is evidenced.

Main entry points: [`apps/api/src/routes/storage.ts`](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/storage.ts) (Storage endpoints), [`apps/api/src/index.ts`](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/index.ts) (REST API), [`extern/vast-client/src/vast_client.js`](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/vast_client.js) (VAST client), [`apps/artisan/src/workers/pipeline.ts`](https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/pipeline.ts) (Media pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and storage"]
  node_api_server["REST API<br/>[index.ts]"]
  node_job_routes["Job endpoints<br/>[jobs.ts]"]
  node_asset_routes["Asset endpoints<br/>[assets.ts]"]
  node_storage_routes["Storage endpoints<br/>[storage.ts]"]
  node_storage_schema["Storage schemas<br/>[storage.ts]"]
  node_s3_access["S3 access<br/>[s3.ts]"]
  node_repositories[("Data repositories")]
  node_workers["API workers<br/>[index.ts]"]
end

subgraph group_processing["Media processing"]
  node_artisan_pipeline["Media pipeline<br/>[pipeline.ts]"]
  node_transcoding["Transcoding<br/>[transcode.ts]"]
  node_packaging["HLS packaging<br/>[package.ts]"]
  node_artisan_s3["Media object access<br/>[s3.ts]"]
end

subgraph group_stitching["Playlist stitching"]
  node_stitch_routes["Stitcher routes<br/>[out.ts]"]
  node_stitch_sessions["Ad sessions<br/>[sessions.ts]"]
  node_playlist["Playlist generation<br/>[playlist.ts]"]
  node_vmap["VMAP handling<br/>[vmap.ts]"]
  node_vast["VAST handling<br/>[vast.ts]"]
end

subgraph group_dashboard["Operations dashboard"]
  node_dashboard["Dashboard UI<br/>[storage.tsx]"]
  node_api_client["API client<br/>[api.tsx]"]
  node_preview["File preview<br/>[FilePreview.tsx]"]
end

subgraph group_playback["Playback and ads"]
  node_vast_client["VAST client<br/>[vast_client.js]"]
  node_vast_parser["VAST parser<br/>[vast_parser.js]"]
  node_ad_parser["Ad parsing<br/>[ad_parser.js]"]
  node_vast_fetcher["VAST fetching<br/>[fetcher.js]"]
  node_vast_storage["Client storage<br/>[storage.js]"]
  node_player_facade["HLS player facade<br/>[hls-player.ts]"]
  node_event_manager["Event management<br/>[event-manager.ts]"]
end

node_operator(("API user"))
node_media_store[("S3 media store")]
node_viewer(("Playback viewer"))

node_operator -->|"calls API"| node_api_server
node_api_server -->|"mounts routes"| node_job_routes
node_api_server -->|"mounts routes"| node_asset_routes
node_api_server -->|"mounts routes"| node_storage_routes
node_storage_routes -->|"validates responses"| node_storage_schema
node_storage_routes -->|"reads objects"| node_s3_access
node_dashboard -->|"requests storage"| node_api_client
node_dashboard -->|"opens preview"| node_preview
node_preview -->|"fetches file"| node_api_client
node_api_client -->|"calls storage API"| node_storage_routes
node_storage_routes -->|"lists and retrieves"| node_media_store
node_job_routes -.->|"persists job data"| node_repositories
node_workers -.->|"dispatches work"| node_artisan_pipeline
node_artisan_pipeline -.->|"transcodes media"| node_transcoding
node_artisan_pipeline -.->|"packages HLS"| node_packaging
node_packaging -.->|"writes outputs"| node_artisan_s3
node_artisan_s3 -.->|"writes media"| node_media_store
node_stitch_routes -.->|"serves playlists"| node_playlist
node_stitch_sessions -.->|"handles VMAP"| node_vmap
node_stitch_sessions -.->|"schedules VAST"| node_vast
node_vast_client -->|"stores state"| node_vast_storage
node_vast_client -->|"parses responses"| node_vast_parser
node_vast_client -->|"fetches documents"| node_vast_fetcher
node_vast_parser -->|"parses ads"| node_ad_parser
node_viewer -->|"uses player"| node_player_facade
node_player_facade -->|"manages events"| node_event_manager
node_viewer -.->|"requests stitched HLS"| node_stitch_routes

click node_api_server "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/index.ts"
click node_job_routes "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/jobs.ts"
click node_asset_routes "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/assets.ts"
click node_storage_routes "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/storage.ts"
click node_storage_schema "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/schemas/storage.ts"
click node_s3_access "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/utils/s3.ts"
click node_repositories "https://github.com/superstreamerapp/superstreamer/tree/main/apps/api/src/repositories"
click node_workers "https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/workers/index.ts"
click node_artisan_pipeline "https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/pipeline.ts"
click node_transcoding "https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/transcode.ts"
click node_packaging "https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/package.ts"
click node_artisan_s3 "https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/lib/s3.ts"
click node_stitch_routes "https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/routes/out.ts"
click node_stitch_sessions "https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/routes/sessions.ts"
click node_playlist "https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/playlist.ts"
click node_vmap "https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/vmap.ts"
click node_vast "https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/vast.ts"
click node_dashboard "https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/routes/(dashboard)/_layout/storage.tsx"
click node_api_client "https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/api.tsx"
click node_preview "https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/components/FilePreview.tsx"
click node_vast_client "https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/vast_client.js"
click node_vast_parser "https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/parser/vast_parser.js"
click node_ad_parser "https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/parser/ad_parser.js"
click node_vast_fetcher "https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/fetcher/fetcher.js"
click node_vast_storage "https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/util/storage.js"
click node_player_facade "https://github.com/superstreamerapp/superstreamer/blob/main/packages/player/src/hls-player.ts"
click node_event_manager "https://github.com/superstreamerapp/superstreamer/blob/main/packages/player/src/event-manager.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_api_server,node_job_routes,node_asset_routes,node_storage_routes,node_storage_schema,node_s3_access,node_repositories,node_workers,node_operator,node_viewer toneBlue
class node_artisan_pipeline,node_transcoding,node_packaging,node_artisan_s3,node_media_store toneAmber
class node_stitch_routes,node_stitch_sessions,node_playlist,node_vmap,node_vast toneMint
class node_dashboard,node_api_client,node_preview toneRose
class node_vast_client,node_vast_parser,node_ad_parser,node_vast_fetcher,node_vast_storage,node_player_facade,node_event_manager toneIndigo
```

## Components

### API and storage

- [REST API](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Job endpoints](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/jobs.ts): `apps/api/src/routes/jobs.ts`
- [Asset endpoints](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/assets.ts): `apps/api/src/routes/assets.ts`
- [Storage endpoints](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/routes/storage.ts): `apps/api/src/routes/storage.ts`
- [Storage schemas](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/schemas/storage.ts): `apps/api/src/schemas/storage.ts`
- [S3 access](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/utils/s3.ts): `apps/api/src/utils/s3.ts`
- [Data repositories](https://github.com/superstreamerapp/superstreamer/tree/main/apps/api/src/repositories): `apps/api/src/repositories`
- [API workers](https://github.com/superstreamerapp/superstreamer/blob/main/apps/api/src/workers/index.ts): `apps/api/src/workers/index.ts`

### Media processing

- [Media pipeline](https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/pipeline.ts): `apps/artisan/src/workers/pipeline.ts`
- [Transcoding](https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/transcode.ts): `apps/artisan/src/workers/transcode.ts`
- [HLS packaging](https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/workers/package.ts): `apps/artisan/src/workers/package.ts`
- [Media object access](https://github.com/superstreamerapp/superstreamer/blob/main/apps/artisan/src/lib/s3.ts): `apps/artisan/src/lib/s3.ts`

### Playlist stitching

- [Stitcher routes](https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/routes/out.ts): `apps/stitcher/src/routes/out.ts`
- [Ad sessions](https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/routes/sessions.ts): `apps/stitcher/src/routes/sessions.ts`
- [Playlist generation](https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/playlist.ts): `apps/stitcher/src/playlist.ts`
- [VMAP handling](https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/vmap.ts): `apps/stitcher/src/vmap.ts`
- [VAST handling](https://github.com/superstreamerapp/superstreamer/blob/main/apps/stitcher/src/vast.ts): `apps/stitcher/src/vast.ts`

### Operations dashboard

- [Dashboard UI](https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/routes/(dashboard)/_layout/storage.tsx): `apps/app/src/routes/(dashboard)/_layout/storage.tsx`
- [API client](https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/api.tsx): `apps/app/src/api.tsx`
- [File preview](https://github.com/superstreamerapp/superstreamer/blob/main/apps/app/src/components/FilePreview.tsx): `apps/app/src/components/FilePreview.tsx`

### Playback and ads

- [VAST client](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/vast_client.js): `extern/vast-client/src/vast_client.js`
- [VAST parser](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/parser/vast_parser.js): `extern/vast-client/src/parser/vast_parser.js`
- [Ad parsing](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/parser/ad_parser.js): `extern/vast-client/src/parser/ad_parser.js`
- [VAST fetching](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/fetcher/fetcher.js): `extern/vast-client/src/fetcher/fetcher.js`
- [Client storage](https://github.com/superstreamerapp/superstreamer/blob/main/extern/vast-client/src/util/storage.js): `extern/vast-client/src/util/storage.js`
- [HLS player facade](https://github.com/superstreamerapp/superstreamer/blob/main/packages/player/src/hls-player.ts): `packages/player/src/hls-player.ts`
- [Event management](https://github.com/superstreamerapp/superstreamer/blob/main/packages/player/src/event-manager.ts): `packages/player/src/event-manager.ts`

### Other components

- **API user**
- **S3 media store**
- **Playback viewer**

## Connections

- API user → REST API: calls API
- REST API → Job endpoints: mounts routes (evidence: `apps/api/src/index.ts`)
- REST API → Asset endpoints: mounts routes (evidence: `apps/api/src/index.ts`)
- REST API → Storage endpoints: mounts routes (evidence: `apps/api/src/index.ts`)
- Storage endpoints → Storage schemas: validates responses (evidence: `apps/api/src/routes/storage.ts`)
- Storage endpoints → S3 access: reads objects (evidence: `apps/api/src/routes/storage.ts`)
- Dashboard UI → API client: requests storage (evidence: `apps/app/src/routes/(dashboard)/_layout/storage.tsx`)
- Dashboard UI → File preview: opens preview (evidence: `apps/app/src/routes/(dashboard)/_layout/storage.tsx`)
- File preview → API client: fetches file (evidence: `apps/app/src/components/FilePreview.tsx`)
- API client → Storage endpoints: calls storage API (evidence: `apps/api/src/routes/storage.ts`)
- Storage endpoints → S3 media store: lists and retrieves (evidence: `apps/api/src/routes/storage.ts`)
- Job endpoints → Data repositories: persists job data
- API workers → Media pipeline: dispatches work
- Media pipeline → Transcoding: transcodes media
- Media pipeline → HLS packaging: packages HLS
- HLS packaging → Media object access: writes outputs
- Media object access → S3 media store: writes media
- Stitcher routes → Playlist generation: serves playlists
- Ad sessions → VMAP handling: handles VMAP
- Ad sessions → VAST handling: schedules VAST
- VAST client → Client storage: stores state (evidence: `extern/vast-client/src/vast_client.js`)
- VAST client → VAST parser: parses responses (evidence: `extern/vast-client/src/vast_client.js`)
- VAST client → VAST fetching: fetches documents (evidence: `extern/vast-client/src/vast_client.js`)
- VAST parser → Ad parsing: parses ads (evidence: `extern/vast-client/src/parser/vast_parser.js`)
- Playback viewer → HLS player facade: uses player
- HLS player facade → Event management: manages events (evidence: `packages/player/src/hls-player.ts`)
- Playback viewer → Stitcher routes: requests stitched HLS
