This directory describes Cotton's architecture and operational contracts. It is intended for contributors, operators, and security reviewers.
Technical documentation must explain behavior that remains important when implementation details move:
- public HTTP, storage, cryptographic, and configuration contracts;
- domain concepts and architectural boundaries;
- security and tenancy invariants;
- concurrency, failure, recovery, and cancellation behavior;
- operational requirements and upgrade constraints;
- known limitations and intentional trade-offs.
Avoid duplicating the source tree. In particular, do not document line numbers, commit history, exhaustive file or class inventories, package patch versions, or step-by-step private-method implementations. Those details become stale without helping an operator or contributor make a decision.
Concrete identifiers are appropriate when they are themselves stable contracts: routes, configuration keys, persisted formats, database fields involved in migrations, public DTOs, and deliberate extension interfaces. Source file references should be exceptional rather than the organizing structure of a document.
When code and documentation disagree, treat the current code and migrations as authoritative and update the affected contract documentation in the same change.
Cotton is a self-hosted file cloud with a .NET backend, PostgreSQL persistence, and a React frontend. Files are split into content-addressed chunks, compressed, encrypted, and written through a storage pipeline to a filesystem or S3-compatible backend. Mutable user-visible paths are stored separately from immutable file content.
The runtime also provides background maintenance through Quartz, realtime updates through SignalR, WebDAV access, media previews, database integrity protection, and backup/restore support. One master key anchors storage encryption and related derived keys.
- 04. Content-addressed storage
- 05. Logical filesystem
- 06. Storage pipeline and backends
- 07. Cryptography engine
- 08. Master-key bootstrap
- 09. Upload and file lifecycle
- 10. Garbage collection
- 11. Sharing, versions, trash, archives, and quotas
- 12. HTTP API and mediator
- 13. Authentication and sessions
- 14. Passkeys and OIDC
- 15. Background jobs
- 16. Realtime events, notifications, and email
- 17. WebDAV
- 18. Previews and media
- 19. Search
- 20. Database integrity
- 21. Database backup and restore
- 22. Security hardening
- 23. Frontend architecture
- 24. Frontend features and upload
- 25. Configuration and startup
- 26. Performance and testing
- 27. Deployment and operations
- 28. Glossary
- Contributors: 01 → 03 → the subsystem being changed.
- Operators: 27 → 25 → 08 → 21.
- Security reviewers: 07 → 08 → 20 → 22 → 13 and 14.
- Frontend contributors: 23 → 24 → 12.