Skip to main content

Architecture Overview

Introduction​

Qubital is a virtual office service that gives remote teams persistent online workspaces. Inside those spaces, you get high-quality video conferencing with real-time audio and video, participant management, and built-in recording. Recordings are saved so you can store, manage, and revisit sessions whenever you need.

Under the hood, Qubital is built on LiveKit, the open-source platform for real-time Audio/Video over WebRTC. Our backend is written in Go and runs in Docker containers. The system supports audio and video recording, allowing users to store and manage their sessions for later use.

High-Level Architecture​

The system follows this flow:

  • Code → Deploy: GitHub → image in GHCR, by digest → qubital-infra → Northflank (staging on every merge to main; prod through the promote, with the exact image staging ran). See Deployment
  • Runtime: Backend ↔ LiveKit Cloud (API key/secret)
  • Observability: OTLP → Grafana Alloy (co-located) → Loki on Grafana Cloud; event-derived Prometheus metrics alongside logs
  • Networking: Backend ↔ Alloy over Northflank's private network
  • Recordings: LiveKit webhooks → Google Cloud Run Listener → Upload Job → R2 (24 h) → YouTube (unlisted) → Slack

Architectural Details​

The system begins in a GitHub repository hosting the Go backend. On every merge to main, a GitHub Action builds the backend image and publishes it to GitHub Container Registry (GHCR), where every deploy references it by digest. This establishes a single deployable unit that can be referenced unambiguously.

The flow is designed to keep development fast, staging representative, and production reproducible and auditable, while keeping internal traffic on Northflank's private network.

Environments and Promotion​

All environments run on Northflank, in the projects qubital-staging and qubital-prod. Their desired state lives in the qubital-infra repo and Northflank applies it (ADR-0006):

  • Staging: every merge to main deploys the new image.
  • Production: never builds from source. The promote copies the exact image staging ran and verified, by digest, under the release version.

The result is fast iteration on staging and reproducible, auditable releases in production with no drift between what was validated and what is promoted.

Source and Build​

All changes originate as commits to the GitHub repository. Every merge to main builds the backend image once and publishes it to GHCR, tagged with the commit (staging-<sha>); deploys reference it by digest. A prod release copies that image into the prod package under its version (<version>, sha-<commit>). This separation—building once, publishing once, and promoting the same bits—ensures that production always runs a concretely identifiable image rather than a fresh build from source.

Runtime Integration with LiveKit​

While running, the backend communicates with LiveKit Cloud using an API key, secret and service URL. Through these credentials, it manages rooms, tracks, and egress. These credentials must be handled as secrets and rotated when appropriate.

Observability and Event-Derived Metrics​

The backend emits telemetry using the OpenTelemetry Protocol (OTLP). A Grafana Alloy instance (the observer) runs next to the backend in the prod Northflank project and ingests this telemetry; staging sends none. Alloy then forwards logs and lightweight metrics derived from events to Loki in Grafana Cloud.

This arrangement centralizes operational signals:

  • Logs: Provide detailed context for execution, errors, and state transitions in JSON format
  • Event-derived metrics: Built from LiveKit webhook events, making it possible to chart rates and outcomes alongside the related logs, improving visibility without maintaining a separate metrics pipeline

Networking Characteristics​

Internal service‑to‑service communication within a Northflank project uses its private network. This design lowers round‑trip time, cuts exposure to the public internet for internal data paths, and simplifies access control: the observer receives the backend's OTLP stream without crossing a public boundary. External communication is limited to the integrations that require it. LiveKit Cloud for media operations, Grafana Cloud for log storage and visualization, and Cloudflare/YouTube/Slack for the recording pipeline.

Recording Pipeline from Webhooks to Shareable Media​

LiveKit webhooks initiate the recording workflow and are connected to a Google Cloud Run Listener Service. This lightweight HTTP server verifies incoming webhooks and triggers downstream processing based on egress lifecycle events.

On egress.ended:

  • The Listener Service receives the webhook from LiveKit
  • It triggers the Upload Job via the Google Cloud API
  • The Job downloads the recording from Cloudflare R2 (configured with a 24-hour retention policy)
  • R2 acts as a short-lived landing zone to buffer files immediately after capture

On egress.complete:

  • The Upload Job processes the video file and metadata
  • Uploads the recording to our YouTube channel as an unlisted video
  • Logs the upload details to Google Sheets for tracking
  • Once the upload succeeds, posts the video link in our dedicated Slack channel

Architecture benefits:

  • Listener Service: Always-on, scalable, minimal resource usage for webhook verification
  • Upload Job: One-off execution with high memory allocation (2Gi+) for heavy video processing
  • Single Docker image: Both components share the same codebase, differing only in entry point

Storage strategy:

  • YouTube: Durable copy intended for ongoing access
  • R2: Temporary staging area that expires automatically, controlling storage growth without manual cleanup