Collaborative Playlist · P2P Architecture

Requirements choose the architecture

Requirement	Architecture signal	Reason
Edits during long offline periods	P2P / local-first	A local replica accepts writes immediately and merges them after reconnection.
Small, invite-only collaborator groups	P2P / local-first	A bounded mesh keeps fanout and membership manageable.
Device-held data, direct LAN sync, outage operation	P2P / local-first	The playlist remains usable while cloud services or Internet access are unavailable.
Public discovery, recommendations, analytics, royalties	Managed services	Global indexes and trusted aggregation need continuously available shared infrastructure.
Thousands of simultaneous editors	Managed or relay-backed hybrid	Peer connection count, bandwidth, and membership dissemination grow with the group.
Immediate revocation, moderation, and legal audit	Managed authority	A central policy boundary provides prompt enforcement and a canonical audit trail.

High-level architecture

Control plane

Identity + invite→Rendezvous / signaling→STUN / TURN

Replica data plane

Peer A
local replica↔WebRTC data channel↔Peer B
local replica

Availability path

Encrypted change log↔Mailbox / sync relay↔Offline peer later

The fast path carries changes directly between devices. Signaling introduces peers, TURN relays blocked connections, and the mailbox holds encrypted changes for peers that return later.

Mutation and synchronization flow

The device loads the playlist CRDT and membership epoch from IndexedDB or SQLite.
A local add, remove, or move creates a stable operation ID and updates the UI immediately.
The device persists the CRDT change before advertising it to connected peers.
Peers exchange document heads or version vectors and request missing changes.
Each replica validates the signer, membership epoch, operation shape, and stable entry IDs.
The CRDT merge produces the same ordered entries on every replica that has received the same changes.
An encrypted mailbox retains changes for offline members; snapshots compact old history under an explicit retention policy.

Ordering contract

Store playlist entries in a map keyed by immutable entry_id; keep the visible order as a replicated sequence of those IDs.
Represent move as one logical operation over an entry and neighboring anchors. A move-aware list algorithm preserves one occurrence under concurrent moves.
Concurrent inserts at one gap survive with a deterministic actor and operation tie-break.
A removal tombstone wins over concurrent moves of the removed entry.
Every operation carries actor identity, membership epoch, causal context, and a unique operation ID.

Technology map and usage

Technology	Responsibility	How to use it here
Automerge	Local-first CRDT document	Keep one document per playlist, persist it locally, exchange missing changes through repository network adapters, and merge concurrent edits automatically.
Yjs + y-webrtc	Browser prototype and peer sync	Place peers in one room per playlist and synchronize replicated structures through WebRTC. Apply an explicit move contract for stable entry identities.
IndexedDB / SQLite	Durable local replica	Persist the document, pending changes, membership certificates, peer acknowledgements, and compaction checkpoint.
WebRTC RTCDataChannel	Encrypted browser data path	Send compact CRDT changes directly. Use ordered reliable delivery for mutations and a separate ephemeral channel for presence.
WebSocket signaling	Peer introduction	Exchange session descriptions and ICE candidates for authorized playlist members.
STUN + TURN	NAT traversal and relay	Try direct connectivity through STUN and route through TURN when firewalls or symmetric NAT block the direct path.
Signed capabilities	Authorization	The owner signs member role and membership epoch. Every replica verifies a mutation before applying it.

Tradeoffs

Advantages

Instant local writes and full offline editing
Continued use during service outages
Direct transfer and lower server data traffic
Device-held source of truth
Natural multi-device and branch history

Costs

Eventual convergence replaces immediate global order
Revocation propagates by membership epoch
Offline delivery needs mailbox peers or a relay
Client storage and migration become production concerns
Malicious peers require signature and policy validation

Topology threshold

A full mesh creates n(n-1)/2 connections. Ten editors create 45 peer links; one hundred editors create 4,950. Yjs documents the resulting browser limits for large collaborator sets.

2 to 10 active editors: full WebRTC mesh is straightforward.
10 to 50: partial mesh, relay hub, or small GossipSub overlay controls connection count.
Large public playlists: server-assisted CRDT sync and CDN-backed snapshots provide predictable availability.

Failure and security boundaries

Peer disappears: remaining peers continue; the mailbox carries missed changes on return.
Network partition: each side accepts local changes and merges after connectivity returns.
Owner revokes a member: a signed membership epoch blocks later operations from the revoked identity after replicas learn the new epoch.
Relay reads traffic: encrypt private playlist changes at the application layer; WebRTC already encrypts the transport path.
Replica loses storage: restore from another peer or an encrypted snapshot backup.
Old history grows: publish a snapshot and retain a bounded change tail based on acknowledgements and device-expiry policy.

Interview decision sequence

Which requirement makes local acceptance of writes valuable?
How many collaborators are concurrently online?
Who introduces peers and supplies TURN relay capacity?
How does an offline member receive missed changes?
Which CRDT rule resolves concurrent moves?
How are membership and revocation authenticated?
Which product capabilities retain managed services?