Skip to content

Architecture Overview

Introduction

Qubital is a virtual office service that gives remote teams persistent online workspaces. Inside those spaces, you get seamless, 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:

flowchart TD
    GitHub[(GitHub repo)] -->|Build| Docker{{Docker Image}}
    Docker -->|Push| GHCR[(GHCR)]
    GHCR -->|Pull| Backend[Backend<br/>Go Service]

    Backend -->|API| LiveKit[LiveKit Cloud]
    LiveKit -->|Webhook| GCR[Google Cloud Run<br/>Listener Service]
    GCR -->|Trigger| Job[Upload Job]
    Job -->|Download| R2[(R2<br/>24h retention)]
    Job -->|Upload| YouTube[YouTube]
    YouTube -->|Notify| Slack[Slack]

    Backend -->|Observer| Alloy{{Grafana Alloy}}
    Alloy -->|OTLP Logs| Loki[(Loki)]
    Alloy -->|Scrapes| Prometheus[(Prometheus)]
  • Code → Deploy: GitHub → Docker image → GHCR (for prod) → Sevalla (dev/staging from branches; prod pulls latest GHCR image)
  • 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 internal Sevalla URLs (shared CDN plane)
  • 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. A GitHub Action builds a Docker image, tags it with the commit SHA (and, when applicable, a release tag), and—when preparing for production—publishes the image to GitHub Container Registry (GHCR) as an immutable artifact. This establishes a single deployable unit that can be referenced unambiguously by tag and digest.

The flow is designed to keep development fast, staging representative, and production reproducible and auditable, while keeping internal traffic on Sevalla internal URLs for efficiency and reduced exposure.

Environments and Promotion

All environments run on Sevalla:

  • Development & Staging: Deploy directly from designated GitHub branches via a GitHub PAT (Personal Access Token)
  • Production: Never builds from source; pulls the latest published image from GHCR (typically the one built from the main branch)

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

Source and Build

All changes originate as commits to the GitHub repository. A GitHub Action builds a Docker image for the backend each time we intend to deploy. Images are tagged with:

  • Commit SHA: Guarantees traceability to an exact revision
  • Release tag: Human-readable version when desirable

For production, the action publishes the image to GHCR, treating it as an immutable artifact. 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 co-located with the backend in Sevalla and ingests this telemetry. 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 Sevalla uses internal URLs on the shared CDN plane. 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