Design Overview

Capsule is an end-to-end-encrypted personal photo and media store with optional federation. These design docs are its normative specification: every primitive, schema, and protocol is declared in exactly one owner doc and referenced by anchor everywhere else (the Single Source of Truth rule).

The shape of the system

The design stacks in layers, each building on the one below — the sidebar groups follow this order:

• Foundations — the core principles every component obeys, the module map from code module to owning doc, the API surfaces map from server surface to transport, and how those surfaces become published reference.
• Cryptography — the primitives inventory, the key hierarchy, MLS group membership with its resilience contracts, asset/metadata encryption, and signed provenance. The server holds only opaque ciphertext — never a key.
• Identity & access — authentication, authorization, and device enrollment.
• Storage — the server and client filesystems, the metadata sidecar schema, thumbnails, and quota.
• Import & sync — the import pipeline, upload protocol, download & sync, storage verification, backup, and versioning.
• Sharing & federation — server-to-server federation, device-to-device peering, share links, web upload for guest drops, and moderation.
• Organization & clients — albums and stacks, native client duties, how a key-free server reaches a user at all (notifications), internationalization, and on-device AI/ML.
• Threat model — the cross-cutting damage-scenario map, validation invariants, and schema rules that bound what a faulty or hostile client can do.

Where to start

• New to the project? Read Core Principles, then the Cryptography overview.
• Implementing a feature? Find your code module in the Module Map — it names the owning design doc and the validation tier.
• Reviewing security? Start at the Threat Model and follow each damage scenario to the owner doc that defeats it.