FrameWorks

Warning: This stack is pre‑release and experimental. Do not deploy to production. Interfaces and schemas change frequently. Use for local development and evaluation only.

Sovereign SaaS for live video. Run on your infrastructure, ours, or both—no vendor lock-in.

An open streaming stack for live video: apps, real‑time APIs, and analytics. Services are narrowly scoped. Frontend uses GraphQL; service-to-service uses HTTP/gRPC APIs; analytics and realtime use Kafka events. Each service owns its data (no cross‑DB access).

NPM packages

FrameWorks ships official player and browser-ingest packages:

FrameWorks Player

StreamCrafter (browser ingest)

Architecture at a glance

• Gateway
  • Bridge (api_gateway): GraphQL gateway, aggregates all services
• Control plane (business logic)
  • Commodore (api_control): auth, streams, business logic
  • Quartermaster (api_tenants): tenants, clusters, nodes
  • Purser (api_billing): usage, invoices, payments
• Data plane (events & analytics)
  • Periscope Ingest (api_analytics_ingest): consumes Kafka, writes ClickHouse
  • Periscope Query (api_analytics_query): serves analytics & usage summaries
  • Decklog (api_firehose): gRPC ingress → Kafka
  • Kafka: event backbone
  • PostgreSQL: state & aggregates
  • ClickHouse: time‑series
• Media plane
  • Foghorn (api_balancing): regional load balancer & media pipeline orchestrator
  • Helmsman (api_sidecar): edge sidecar, MistServer management via Foghorn
  • MistServer: ingest/processing/edge delivery
  • Livepeer Gateway (golivepeer): transcoding/AI processing
• Network & Infrastructure
  • Navigator (api_dns): public DNS automation & certificate issuance
  • Privateer (api_mesh): WireGuard mesh agent & local DNS
• Realtime
  • Signalman (api_realtime): WebSocket hub for live updates
• Interfaces
  • Web Console (website_application): main dashboard
  • Marketing Site (website_marketing): public site
  • Documentation (website_docs): Astro Starlight docs
  • Forms API (api_forms): contact forms, newsletter (Listmonk)

Principles

• Strict service boundaries (no cross‑DB reads)
• Time‑serie/data-plane in ClickHouse; control/aggregates in Postgres
• Type safety by reusing the gRPC types straight from the emitter. Passthrough and leave source data intact as much as possible, with optional enrichment fields

Quick Start

Development Setup (docker-compose)

For local development and testing:

git clone https://github.com/Livepeer-FrameWorks/monorepo.git
cd monorepo
cp config/env/secrets.env.example config/env/secrets.env  # edit values as needed
make env  # writes .env from config/env
docker-compose up

The Compose stack loads ${ENV_FILE:-.env} automatically. Override ENV_FILE (and pass --env-file to docker compose) when you want to use a different generated env file (for example .env.staging).

Endpoints (local)

• GraphQL Gateway: http://localhost:18090/graphql
• GraphQL WebSocket: ws://localhost:18090/graphql/ws (subscriptions)
• App via Nginx: http://localhost:18090
• Web Console: http://localhost:18030
• Marketing site: http://localhost:18031
• Listmonk (Admin): http://localhost:9001
• MistServer: http://localhost:4242 (RTMP: 1935, HTTP: 8080)
• Kafka (external): localhost:29092
• Postgres: localhost:5432
• ClickHouse: 8123 (HTTP), 9000 (native)

Ports

Configuration

GeoIP

Foghorn (api_balancing) can determine geography from either:

• Proxy-injected geo headers (e.g., Cloudflare’s CF-IPCountry or similar), or
• A local MMDB file (any vendor providing a compatible City/Country database).

It is recommended to point it to a local MMDB file, which ensures all events are enriched with Geo data. Only events originating from the Load Balancer can be enriched via geo headers.

To use a local database, set GEOIP_MMDB_PATH to the path of your MMDB file. If neither headers nor MMDB are available, Foghorn operates without geo routing data.

Docs

See website_docs/ for full documentation (Astro Starlight site):

• Streamers — Quick start, encoder setup, API reference, playback
• Operators — Architecture, deployment, DNS, CLI reference, WireGuard mesh
• Hybrid — Self-hosted edge nodes with managed control plane
• Roadmap — Feature status and priorities
• Blog — Changelog, technical posts