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 this repository (the marketing-toned root README.md is treated as a secondary source — where code and README disagree, the code wins and the docs say so).
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 / 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.
| Layer | Technology |
|---|---|
| Backend runtime | .NET 10 / ASP.NET Core (src/Cotton.Server) |
| Persistence | EF Core + PostgreSQL/Npgsql (src/Cotton.Database) |
| Application logic | EasyExtensions.Mediator (commands/queries), Mapster |
| Background jobs | Quartz (EasyExtensions.Quartz JobTrigger) |
| Realtime | SignalR (EventHub) |
| Storage engine | src/Cotton.Storage (pipeline + processors + backends) |
| Cryptography | src/Cotton.Crypto (streaming AES-GCM) |
| Compression | Zstd via ZstdSharp |
| Previews/media | src/Cotton.Previews (FFmpeg, Docnet/MuPDF, f3d, …) |
| Frontend | React 19 + Vite, MUI 7, TanStack Query, Zustand, react-router |
Foundations
- 01. System Overview & Design Philosophy
- 02. Solution Layout, Projects & Build
- 03. Data Model & Persistence (EF Core)
Storage core
- 04. Content-Addressed Storage: Chunks, Manifests & Deduplication
- 05. Logical Filesystem: Layouts, Nodes & Topology
- 06. Storage Pipeline & Backends
- 07. Cryptography Engine: Streaming AES-GCM
- 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
Integrity, security & backup
- 20. Database Integrity & Tamper Evidence
- 21. Database Backup & Auto-Restore
- 22. Security Hardening, Diagnostics & Validation
Frontend
Operations & quality
- 25. Configuration, Settings & Server Startup
- 26. Performance, Benchmarking & Testing
- 27. Deployment & Operations Guide
Reference
- 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.
- 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 (italicized).
This documentation was generated from a multi-agent study of the codebase: every section was drafted by reading the source, then independently fact-checked against the code a second time. The same content set is intended for publication to the Cotton Cloud Wiki once the wiki connector has write access.