Directory structure

There are two layouts worth knowing: the repository (what you clone / build), and the runtime data directory (what StreamHub creates and reads/writes while running).

Repository layout

• Directorystreamhub-core/ NestJS core — REST API, serves the SPA, HLS, SDK

  • Directorysrc/

    • app.module.ts scaffolder-owned, don’t edit inside a feature
    • main.ts scaffolder-owned
    • Directorymodules/ apps, livekit, recording, s3, auth, streams, …

      • …
    • Directoryplugins/ backend plugins — auto-discovered, one dir per plugin

      • …
    • Directoryshared/ config, db, auth guard, cross-module contracts

      • …
  • Directorytest/ unit specs (*.spec.ts) + e2e (test/*.e2e-spec.ts)

    • …
• Directorystreamhub-web/ React 19 + Vite + Tailwind dashboard SPA

  • Directorysrc/

    • Directorypages/

      • …
    • Directoryplugins/ frontend plugin modules — auto-discovered

      • …
    • Directorylib/ ui/ layout/ auth/ api/ …

      • …
• Directorystreamhub-adaptor/ browser SDK — AntMedia WebRTCAdaptor shim over livekit-client

  • Directorysrc/

    • …
• Directoryyolo-worker/ Python worker spawned by the built-in yolo plugin

  • …
• Directorydeploy/ Dockerfile, Caddyfile, entrypoint, seeder, systemd/nginx units

  • Dockerfile multi-stage build: web + adaptor + core → one runtime image
  • Caddyfile Compose auto-TLS reverse proxy config
  • core-entrypoint.sh copies the adaptor SDK into DATA_DIR/sdk at boot
  • seed-token.js seeds the first sk_ API token into the DB
  • nginx-streamhub.conf server block for the systemd/nginx deploy shape
  • livekit.yaml LiveKit config template for native systemd
  • livekit.service / streamhub-core.service systemd units
  • backup.sh / restore.sh / deploy-core.sh operational scripts
  • Directoryobservability/ Prometheus + Grafana assets

    • …
• Directorystreamhub-docs/ architecture, operations, API reference, testing catalogue

  • …
• docker-compose.yml the Docker Compose stack (redis, livekit, ingress, egress, core, caddy)
• install.sh the hosted one-liner installer
• uninstall.sh companion teardown script
• .env.example fully-commented config template

legacy/ also exists at the repo root — retired code (the original Express LiveKit admin UI, old static player pages) kept only for reference. It is never built or deployed.

Runtime data directory (DATA_DIR)

Everything StreamHub reads and writes at runtime lives under one directory: DATA_DIR (/data inside the containers), bind-mounted from STREAMHUB_HOST_DATA_DIR (default ./data on the host) into both the core and egress containers. That shared mount is what lets egress write an MP4 exactly where core looks for it to upload to S3.

• Directorydata/ DATA_DIR — everything below is relative to this root

  • Directorydata/

    • streamhub.db global DB — tenants, users, api_tokens, nodes registry, apps pointer
    • streamhub.db.bak-<timestamp> pre-migration backup (VACUUM INTO), taken automatically
  • Directoryapps/

    • Directorylive/ the default app, seeded on first boot

      • config.yaml per-app config: recording, s3, webrtc, rtmp, transcoding, callbacks, features
      • app.db per-app DB — streams, vods (+ metatags, snapshot_key), ingress_auth
      • Directoryrecordings/ temp MP4s, deleted after a successful S3 upload

        • …
      • Directoryhls/

        • Directory<room>/ index.m3u8 + .ts segments (live HLS)

          • …
      • Directorysnapshots/ JPEG snapshots

        • …
      • Directorysamples/ publish.html, play.html, embed.html, meeting.html

        • …
    • Directory<app>/ one directory per app you create

      • …
  • secrets.json chmod 600 — per-app S3 access/secret keys, referenced from config.yaml
  • Directorylogs/ rotating log files (also mirrored into the server_logs table)

    • …
  • Directorysdk/

    • streamhub-adaptor.global.js copied in by the core entrypoint at every boot
  • Directoryredis/ redis AOF persistence (Docker Compose only)

    • …

This mirrors the split described in the data model: a minimal global streamhub.db holds only cross-tenant identity and cluster-routing rows, while each app owns its full state in one app.db plus its own directory tree. Practically, that means an app is self-contained — apps/<name>/ is the unit you’d back up, move, or (in a future cluster) relocate to another node without touching anything else.