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, and the API surfaces map from server surface to transport.
• 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, 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.