# kixelated/moq architecture

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

- Interactive diagram: https://gitdiagram.com/kixelated/moq
- Repository: https://github.com/kixelated/moq

## Overview

##### Project’s Type and Purpose
- MoQ is a **multi-language**, **layered** media-delivery protocol implementation.
- It provides a generic pub/sub protocol over QUIC called **moq-lite**, media-specific extensions called **hang**, and ships both **native Rust** and **web/TypeScript** clients & servers.
- Components: core libraries (Rust/JS), relay servers (clusterable CDN-style), CLI tools, GStreamer plugin, WASM bridge, and front-end demos.

##### File Structure
- Top-level splits by language:
- `rs/` contains all native Rust crates (moq-lite, moq-relay, hang, hang-gst, hang-cli, hang-wasm, etc.)
- `js/` contains all TypeScript front-end libraries & demos (`@kixelated/moq`, `@kixelated/hang`, `hang-demo`, utilities)
- Deployment/dev config at root (`.github/`, `justfile`, Nix flakes).
- Each crate or package has its own `Cargo.toml` or `package.json`, build config, and source.

##### Main Components
a. Network & Transport Layer
- QUIC (Rust → Quinn)
- WebTransport (browser QUIC wrapper)
b. Protocol Layer
- moq-lite: pub/sub primitives (broadcast, track, frame, group)
c. Media Layer
- hang: encoding/decoding via WebCodecs (web) or GStreamer (native)
d. Application & Tools
- Front-end web app / demos (`hang-demo`, `@kixelated/hang` components)
- CLI (`hang-cli`)
- Native plugin (`hang-gst`)
- Relay servers (`moq-relay` clustered)
- WASM bridge (`hang-wasm`)
e. Clients & Peers
- Publishers (web or native)
- Subscribers/Viewers (web or native)

##### Relationships & Data Flows
- **Publishers** call into the **hang** layer → wrap frames into **moq-lite** messages → transport via **QUIC/WebTransport** → arrive at **moq-relay** cluster → forwarded to interested **subscribers**.
- **Subscribers** reverse the flow: receive QUIC streams → moq-lite demux → feed **hang** decode → render via WebCodecs or GStreamer.
- **CLI** and **demo apps** are simply clients of those libraries.
- **Relay cluster** peers talk to each other (peer-to-peer QUIC) to distribute load globally.

##### Architectural Patterns & Principles
- **Layered architecture**: clearly separate network, transport, protocol, media, and app layers.
- **Pub/Sub pattern** in moq-lite: topics = broadcasts/tracks/groups.
- **Clusterable servers**: moq-relay can be horizontally scaled.
- **Cross-platform** via multiple crates/packages—Rust native vs WASM/Web vs TypeScript.

##### Technologies & Frameworks to Call Out
- Rust ecosystem: `quinn` (QUIC), `wasm-bindgen`/`web-sys`, GStreamer bindings.
- JS ecosystem: Vite (bundling), React/TSX for controls, WebTransport API, WebCodecs API, Tailwind CSS (demo).
- Build/deploy: Just, Nix Flakes, Docker & GitHub Actions workflows.

##### Final Touches
- **pub/sub** topology: one publisher ↔ many subscribers through relays.

- Clearly separates each layer of MoQ
- Captures both native and browser stacks
- Shows how core libraries, servers, and apps interact
- Highlights protocol flows and clustering
- Omits nothing essential yet stays organized and readable.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Publishers
    subgraph "Publishers"
        direction TB
        natPub["Native Publisher"]:::client
        webPub["Web Publisher"]:::client
    end

    %% Network & Transport Layer
    subgraph "Network & Transport Layer"
        direction TB
        quinn["QUIC (Rust/quinn)"]:::transport
        wt["WebTransport (Browser QUIC wrapper)"]:::transport
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        moqliteRs["moq-lite core (Rust)"]:::protocol
        moqliteTs["moq-lite core (TS)"]:::protocol
    end

    %% Media Layer
    subgraph "Media Layer"
        direction TB
        hangRs["hang core (Rust)"]:::media
        gst["hang-gst plugin"]:::media
        hangTs["hang TS library"]:::media
        wasm["hang-wasm bridge"]:::wasm
    end

    %% Application & Tools
    subgraph "Application & Tools"
        direction TB
        demo["hang-demo App"]:::client
        cli["hang-cli"]:::client
        relay["moq-relay Server Cluster"]:::server
    end

    %% Subscribers
    subgraph "Subscribers"
        direction TB
        natSub["Native Subscriber"]:::client
        webSub["Web Subscriber"]:::client
    end

    %% Publish Flow
    natPub -->|"encode"| hangRs
    hangRs -->|"moq-lite msg"| moqliteRs
    moqliteRs -->|"QUIC streams"| quinn
    quinn -->|"QUIC streams"| relay

    webPub -->|"encode"| hangTs
    hangTs -->|"moq-lite msg"| moqliteTs
    moqliteTs -->|"WebTransport streams"| wt
    wt -->|"WebTransport streams"| relay

    %% Relay clustering
    relay -->|peer QUIC| relay

    %% Subscribe Flow
    relay -->|"QUIC streams"| quinn
    quinn -->|"moq-lite msg"| moqliteRs
    moqliteRs -->|"decode"| hangRs
    hangRs -->|"render"| natSub

    relay -->|"WebTransport streams"| wt
    wt -->|"moq-lite msg"| moqliteTs
    moqliteTs -->|"decode"| hangTs
    hangTs -->|"render"| webSub

    %% Click Events
    click quinn "https://github.com/kixelated/moq/blob/main/rs/moq-relay/src/connection.rs"
    click wt "https://github.com/kixelated/moq/blob/main/js/hang/src/connection.ts"
    click moqliteRs "https://github.com/kixelated/moq/tree/main/rs/moq/"
    click moqliteTs "https://github.com/kixelated/moq/tree/main/js/moq/"
    click hangRs "https://github.com/kixelated/moq/tree/main/rs/hang/"
    click gst "https://github.com/kixelated/moq/tree/main/rs/hang-gst/"
    click hangTs "https://github.com/kixelated/moq/tree/main/js/hang/"
    click wasm "https://github.com/kixelated/moq/tree/main/rs/hang-wasm/"
    click demo "https://github.com/kixelated/moq/tree/main/js/hang-demo/"
    click cli "https://github.com/kixelated/moq/tree/main/rs/hang-cli/"
    click relay "https://github.com/kixelated/moq/tree/main/rs/moq-relay/"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef transport fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32;
    classDef protocol fill:#FFF3E0,stroke:#E65100,color:#BF360C;
    classDef media fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef wasm fill:#E1F5FE,stroke:#0277BD,color:#01579B;
    classDef server fill:#FFEBEE,stroke:#C62828,color:#B71C1C;
```
