System map
Single reference for what the system is and how components connect. For ADRs see decisions/. Deeper topics: cache, logs, runtime, maintenance.
High-level map
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CepatEdge │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────────────────────────────────────────┐ │
│ │ Browser │ HTTPS │ Cloudflare Edge (global) │ │
│ │ (Users) │────────▶│ ┌─────────────┐ ┌─────────────────────┐ │ │
│ └──────────────┘ │ │ Pages (SPA) │ │ Workers (Hono API) │ │ │
│ │ │ React (Vite)│ │ Auth, Me, Maintenance│ │ │
│ │ └──────┬──────┘ └──────────┬──────────┘ │ │
│ │ │ │ │ │
│ │ │ ┌───────▼───────┐ │ │
│ │ │ │ Durable Obj │ │ │
│ │ │ │ Sessions + │ │ │
│ │ │ │ Cache (DO) │ │ │
│ │ │ └───────┬───────┘ │ │
│ └─────────┼──────────────────────┼───────────────┘ │
│ │ │ │
│ ┌──────────────────────────────────┼──────────────────────┼──────────────┐ │
│ │ External services │ │ │ │
│ │ ┌────────────┐ ┌────────────┐ │ ┌────────────┐ │ │ │
│ │ │ Neon │ │ R2 │ │ │ Email │ │ │ │
│ │ │ PostgreSQL │◀─┼────────────┼───┼───┤ (notifications) │ │ │
│ │ │ (DB) │ │ (Storage) │ │ └────────────┘ │ │ │
│ │ └────────────┘ └────────────┘ │ │ │ │
│ └──────────────────────────────────┴──────────────────────┴──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘Request flow
- User → HTTPS → Cloudflare Edge
- UI → Pages (React + Vite SPA); API → Workers (Hono)
- Workers:
- Auth (JWT + DO session)
- Cache (DO) when applicable; on miss → Neon (Drizzle)
- Files → R2; notifications → email provider
- Response back through the edge
Infrastructure by layer
| Layer | Technology | Purpose |
|---|---|---|
| Edge / CDN | Cloudflare | TLS, DDoS, routing, edge execution |
| Compute (API) | Workers | Hono: auth, me, maintenance, system |
| Compute (UI) | Pages | Static / SPA frontend |
| State / cache | Durable Objects | Sessions, cache namespaces |
| Database | Neon (PostgreSQL) | Users, requests, attachment metadata |
| Object storage | R2 | Avatars, maintenance attachments |
| Configurable | Notifications |
Public URLs (production)
| Role | Domain | App |
|---|---|---|
| Marketing | cepatedge.com | apps/landing |
| Product SPA | app.cepatedge.com | apps/web |
| API | api.cepatedge.com | apps/worker |
| Docs | docs.cepatedge.com | apps/docs |
| Git analytics | git.cepatedge.com | apps/git |
Auth cookies (.cepatedge.com) apply to app + API only. See guides/domains.md.
Component map
| Component | Location | Depends on |
|---|---|---|
| API routes | apps/worker/src/routes/ | Services, middleware |
| Auth | services/auth/ | JWT, cookies, DO session |
| Me | routes/me/, services/me/ | Auth, R2 avatar, DB |
| Maintenance | routes/maintenance/, services/maintenance/ | Auth, DB, cache, R2 |
| Cache | services/cache/ | Durable Objects |
| Storage | services/storage/ | R2 bindings |
| DB | lib/db/ (Drizzle) | Neon |
| Mailer | services/mailer/ | Email provider |
Data flow summary
- Auth: Login → DB creds → DO session → cookie (JWT + session id). Later: cookie → DO session + JWT verify.
- Maintenance: Workflow writes → DB; DO cache for reads when enabled; attachments → R2 + DB metadata.
- Avatar: Upload → R2 + DB path; GET → R2 stream.
- Backups: Neon backups; optional R2 copies — see Runbook.
Where to go next
- Cache · Logs · Security logs · Runtime · Maintenance
- ADRs
- Deployment workflow · Runbook
- Contributor maps:
maintainer/systems/(observability, cache, maintenance)