# 📘 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 (`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 |

## 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.

---

**Documents**

- [01. System Overview & Design Philosophy](https://docs.cottoncloud.dev/s/overview/doc/01-system-overview-design-philosophy-dc2l3ejYdu)
- [02. Solution Layout, Projects & Build](https://docs.cottoncloud.dev/s/overview/doc/02-solution-layout-projects-build-SSfO7tkm6a)
- [03. Data Model & Persistence (EF Core)](https://docs.cottoncloud.dev/s/overview/doc/03-data-model-persistence-ef-core-gHfGnaMUT9)
- [04. Content-Addressed Storage: Chunks, Manifests & Deduplication](https://docs.cottoncloud.dev/s/overview/doc/04-content-addressed-storage-chunks-manifests-deduplication-8emCG1j9Ce)
- [05. Logical Filesystem: Layouts, Nodes & Topology](https://docs.cottoncloud.dev/s/overview/doc/05-logical-filesystem-layouts-nodes-topology-fbrekNqhO7)
- [06. Storage Pipeline & Backends](https://docs.cottoncloud.dev/s/overview/doc/06-storage-pipeline-backends-oLbrDKLrFt)
- [07. Cryptography Engine: Streaming AES-GCM](https://docs.cottoncloud.dev/s/overview/doc/07-cryptography-engine-streaming-aes-gcm-zw1O5yWetL)
- [08. Master Key, Autoconfig & Unlock Bootstrap](https://docs.cottoncloud.dev/s/overview/doc/08-master-key-autoconfig-unlock-bootstrap-c2A3wFIdGi)
- [09. Upload & File Lifecycle (Chunk-First Protocol)](https://docs.cottoncloud.dev/s/overview/doc/09-upload-file-lifecycle-chunk-first-protocol-gwqeaTK2GJ)
- [10. Garbage Collection & Storage Consistency](https://docs.cottoncloud.dev/s/overview/doc/10-garbage-collection-storage-consistency-x5lNkxbeNU)
- [11. Sharing, Versioning, Trash, Archives & Quotas](https://docs.cottoncloud.dev/s/overview/doc/11-sharing-versioning-trash-archives-quotas-S9tyy0IAvQ)
- [12. HTTP API & Application (Mediator) Layer](https://docs.cottoncloud.dev/s/overview/doc/12-http-api-application-mediator-layer-ZWQiNtXTUM)
- [13. Authentication, Sessions & Password Security](https://docs.cottoncloud.dev/s/overview/doc/13-authentication-sessions-password-security-Y6WV7x0HgD)
- [14. Passkeys (WebAuthn) & OIDC SSO](https://docs.cottoncloud.dev/s/overview/doc/14-passkeys-webauthn-oidc-sso-mhRQQkKuar)
- [15. Background Jobs & Scheduling](https://docs.cottoncloud.dev/s/overview/doc/15-background-jobs-scheduling-dc933d9o4F)
- [16. Real-time Events, Notifications & Email](https://docs.cottoncloud.dev/s/overview/doc/16-real-time-events-notifications-email-Wd6dh5mxpq)
- [17. WebDAV Interface](https://docs.cottoncloud.dev/s/overview/doc/17-webdav-interface-r9T6kvWAbh)
- [18. Previews & Media Processing](https://docs.cottoncloud.dev/s/overview/doc/18-previews-media-processing-VNcD6EjXxl)
- [19. Search](https://docs.cottoncloud.dev/s/overview/doc/19-search-u8yBlq5QxM)
- [20. Database Integrity & Tamper Evidence](https://docs.cottoncloud.dev/s/overview/doc/20-database-integrity-tamper-evidence-LCiJAGqGJS)
- [21. Database Backup & Auto-Restore](https://docs.cottoncloud.dev/s/overview/doc/21-database-backup-auto-restore-vVfLeXKn8l)
- [22. Security Hardening, Diagnostics & Validation](https://docs.cottoncloud.dev/s/overview/doc/22-security-hardening-diagnostics-validation-FcD3aIOcF9)
- [23. Frontend: Architecture, State & API Layer](https://docs.cottoncloud.dev/s/overview/doc/23-frontend-architecture-state-api-layer-wbR5zVUEib)
- [24. Frontend: Features & Upload Pipeline](https://docs.cottoncloud.dev/s/overview/doc/24-frontend-features-upload-pipeline-6cPisSlbxx)
- [25. Configuration, Settings & Server Startup](https://docs.cottoncloud.dev/s/overview/doc/25-configuration-settings-server-startup-Yl3uK2H9QZ)
- [26. Performance, Benchmarking & Testing](https://docs.cottoncloud.dev/s/overview/doc/26-performance-benchmarking-testing-XXppOsYtbs)
- [27. Deployment & Operations Guide](https://docs.cottoncloud.dev/s/overview/doc/27-deployment-operations-guide-Jybdq5sT3P)
- [28. Glossary](https://docs.cottoncloud.dev/s/overview/doc/28-glossary-7wk256c2bj)