Cotton Cloud — Technical Documentation
This is the canonical engineering documentation for Cotton Cloud — a self-hosted, encrypted, content-addressed file cloud. It is a living technical reference for two audiences: contributors who modify the code, and operators who deploy and run it. Every section is written against the actual source in the repository (the marketing-toned README.md is treated as a secondary source — where code and README disagree, the code wins and the docs say so).
What Cotton Cloud Is, in one paragraph
Cotton stores user files as content-addressed, Zstd-compressed, AES-GCM-encrypted chunks. A file is split into chunks keyed by the SHA-256 hash of their plaintext; each chunk flows through a streaming storage pipeline (compress → encrypt → backend) and the visible file is reconstructed on demand from an ordered manifest of chunk hashes. Borrowing git's model, Cotton separates content ("what" a file is — immutable, deduplicated, encrypted) from layout ("where" it appears — the user-visible folder tree). The backend is a single .NET 10 / ASP.NET Core runtime over PostgreSQL (EF Core), Quartz background jobs, and SignalR; the frontend is a React/TypeScript/Vite SPA. Everything cryptographic bottoms out at one root master key, from which the storage key, password pepper, database-integrity signing key, and backup scoping are deterministically derived.
Technology stack
Layer | Technology |
|---|---|
Backend runtime | .NET 10 / ASP.NET Core ( |
Persistence | EF Core + PostgreSQL/Npgsql ( |
Application logic | EasyExtensions.Mediator (commands/queries), Mapster |
Background jobs | Quartz (EasyExtensions.Quartz |
Realtime | SignalR ( |
Storage engine |
|
Cryptography |
|
Compression | Zstd via ZstdSharp |
Previews/media |
|
Frontend | React 19 + Vite, MUI 7, TanStack Query, Zustand, react-router |
How this documentation is organized
The wiki is a numbered, ordered set of sections (nested under this page). Read top-to-bottom for a full tour, or jump by theme:
Foundations — 01 System Overview & Design Philosophy · 02 Solution Layout, Projects & Build · 03 Data Model & Persistence (EF Core)
Storage core — 04 Content-Addressed Storage · 05 Logical Filesystem (Layouts, Nodes & Topology) · 06 Storage Pipeline & Backends · 07 Cryptography Engine · 08 Master Key, Autoconfig & Unlock Bootstrap
Content lifecycle — 09 Upload & File Lifecycle (Chunk-First Protocol) · 10 Garbage Collection & Storage Consistency · 11 Sharing, Versioning, Trash, Archives & Quotas
Application & API — 12 HTTP API & Application (Mediator) Layer · 13 Authentication, Sessions & Password Security · 14 Passkeys (WebAuthn) & OIDC SSO · 15 Background Jobs & Scheduling · 16 Real-time Events, Notifications & Email · 17 WebDAV Interface
Media & search — 18 Previews & Media Processing · 19 Search
Integrity, security & backup — 20 Database Integrity & Tamper Evidence · 21 Database Backup & Auto-Restore · 22 Security Hardening, Diagnostics & Validation
Frontend — 23 Frontend: Architecture, State & API Layer · 24 Frontend: Features & Upload Pipeline
Operations & quality — 25 Configuration, Settings & Server Startup · 26 Performance, Benchmarking & Testing · 27 Deployment & Operations Guide
Reference — 28 Glossary
Where to start
New contributor: 01 → 03 → 04 → 06 → 07, then the area you'll touch.
Operator / SRE: 27 Deployment & Operations Guide → 25 Configuration, Settings & Server Startup → 08 Master Key → 21 Database Backup & Auto-Restore.
Security reviewer: 07 Cryptography Engine → 08 Master Key → 20 Database Integrity → 22 Security Hardening → 13/14 Auth.
Frontend developer: 23 → 24, with 12 (HTTP API) as the contract.
Conventions in these docs
Source files are cited as backticked repo-relative paths, e.g.
src/Cotton.Server/Controllers/ChunkController.cs.Identifiers (classes, methods, enums, routes, config keys) are spelled exactly as in code.
Diagrams use Mermaid. Tables enumerate endpoints, settings, enums, and entity fields.
Cross-references name the target section by title.