Platform Overview
This section covers cross-cutting concerns: systems that multiple apps depend on and that have contracts worth understanding before touching any single app.
Current coverage
| Topic | Status |
|---|---|
| File Storage | Full deep-dive — lifecycle, cleanup safety, consumers, risk register, verification |
| Auth / JWT | Stub — expand when needed |
| Queues (CLEANUP_QUEUE, EMBEDDING_QUEUE) | Stub |
| Cron schedule | Covered inside File Storage → Cleanup Safety |
| Hyperdrive / DB access patterns | Stub |
| Rate limiting (Durable Objects) | Stub |
| Feature flags | See packages/feature-flags/AGENTS.md in the repo |
Design principles
- Single source of truth per concern. One table, one service, one function owns each invariant. Cross-cutting duplication is a smell.
- Layered defense for destructive operations. Anything that deletes data uses ≥3 independent gates. See File Storage → Cleanup Safety for the canonical example.
- API is the only R2 writer / deleter. Web, mobile, admin, cal,
ai-worker, clipper never call
env.STORAGE.putor.deletedirectly. - Migrations are additive. Rename/drop columns in two deploys (add new → backfill → switch readers → drop old).