Architecture

System Overview

P2P Protocol Stack

Connection Flow

Signaling via GossipSub

WebRTC signaling (offer/answer/ICE candidates) rides on the same GossipSub room topic used for chat and file transfer. No separate signaling server needed. The relay only facilitates initial peer discovery — once a direct WebRTC connection is established, media flows peer-to-peer.

Deterministic Offer Initiator

To prevent "glare" (both peers sending offers simultaneously), the peer with the lexicographically larger PeerId always sends the offer. The other peer waits for it.

Room Architecture

Room as GossipSub Topic

Each room maps to a GossipSub topic: /hq-world/room/1.0.0/{roomId}. Subscribing to the topic is equivalent to joining the room. All room messages (signaling, state, moderation, files) are published to this topic.

Message Types

The room layer defines 22 message types routed by manager.ts:

Role Hierarchy

Media Architecture

WebRTC Mesh

Every peer maintains a direct RTCPeerConnection to every other peer (full mesh). This works well for small rooms (2–8 participants). The stream.ts module manages the connection lifecycle.

Adaptive Quality (SFU)

The host runs a hybrid SFU that monitors all peer connections and adjusts video quality based on bandwidth:

Quality checks run every 5 seconds with a 10-second per-peer cooldown to prevent thrashing.

Connection Quality Score

Each peer connection gets a composite quality score (0–100):

Score ≥ 70 = good (3 bars, green). Score ≥ 40 = fair (2 bars, amber). Below 40 = poor (1 bar, red).

File Transfer Protocol

Presence & Discovery

Room Directory

Active rooms publish room-announce messages to a global GossipSub topic (_directory). Announcements include:

• Room ID, name, and status (open/closed)
• Host PeerId, display name, and status (available/busy/away)
• Current participant count and max capacity

Announcements have a 60-second TTL and are re-broadcast every 30 seconds. Stale entries expire automatically from the directory view.

Knock Protocol

Closed rooms require visitors to knock. The knock state machine:

Hosts receive knock requests as native macOS notifications via Tauri's notification plugin.

Project Structure

hq-world/
├── docs/                    # This documentation site
├── scripts/
│   └── relay.mjs            # Local circuit relay v2 server
├── src/
│   ├── App.tsx              # Root component (lobby/room/directory/knocking views)
│   ├── components/
│   │   ├── profile/         # Avatar, ProfileEditor
│   │   └── room/            # RoomView, VideoGrid, MediaControls, HostControls,
│   │                        # ParticipantList, KnockDialog, RoomDirectory,
│   │                        # StatusSelector, FileDropZone, FileTransfer,
│   │                        # BandwidthMonitor, QualityIndicator
│   ├── hooks/               # useProfile, useFileTransfers, useMediaState,
│   │                        # usePeerMedia, useSfu
│   └── lib/
│       ├── p2p/             # node, config, discovery, media, stream,
│       │                    # file-transfer, sfu, bandwidth, quality
│       ├── room/            # manager, types, knock, presence, roles, moderation
│       └── profile/         # types, storage, sync
├── src-tauri/
│   ├── src/main.rs          # Tauri entry point
│   ├── Cargo.toml           # Rust dependencies
│   ├── tauri.conf.json      # App config (window, bundle, CSP)
│   └── capabilities/        # Tauri permission grants
├── tests/
│   └── e2e/                 # Vitest E2E tests
├── package.json
├── tsconfig.json
├── vite.config.ts
└── vitest.config.ts

Configuration Reference

All P2P constants live in src/lib/p2p/config.ts: