System Map and Infrastructure Overview

Single reference for what the system is and how components connect. For ADRs and deeper design, see decisions/, runtime/, and systems/.

1. High-Level System Map

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              CepatEdge (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)  │   │   └────────────┘    │              │   │
│   │  └────────────┘  └────────────┘   │                      │              │   │
│   └──────────────────────────────────┼──────────────────────┼──────────────┘   │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

2. Request Flow (Simplified)

User → HTTPS → Cloudflare Edge.
Static/frontend → Cloudflare Pages (React + Vite SPA build); API → Cloudflare Workers (Hono).
Workers:
- Resolve auth (JWT + Durable Objects session).
- Hit cache (DO) when applicable; on miss, call Neon (Drizzle).
- For file read/write: R2 (avatars, maintenance attachments).
- For notifications: Email (e.g. SMTP / provider).
Response back through edge to browser.

3. Infrastructure Diagram (By Provider)

Layer	Technology	Purpose
Edge / CDN	Cloudflare	TLS, DDoS, routing, edge execution.
Compute (API)	Cloudflare Workers	Hono app: auth, me, maintenance, system routes.
Compute (UI)	Cloudflare Pages	Static/SPA frontend.
State / cache	Durable Objects	Sessions, cache instances (per namespace).
Database	Neon (PostgreSQL)	Persistent data (users, requests, attachments metadata).
Object storage	Cloudflare R2	Bucket `cepatedge` — avatars, maintenance attachments.
Email	Configurable	Notifications (e.g. welcome, maintenance assigned).

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.

4. Component Map (Logical)

Component	Location (code)	Depends on
API routes	`apps/worker/src/routes/`	Services, middleware
Auth	`services/auth/`	JWT, cookies, cache (DO session)
Me	`routes/me/`, `services/me/`	Auth, storage (avatar), DB
Maintenance	`routes/maintenance/`, `services/maintenance/`	Auth, DB, cache, storage (attachments)
Cache	`services/cache/`	Durable Objects
Storage	`services/storage/`	R2 bindings
DB	`lib/db/` (Drizzle)	Neon
Mailer	`services/mailer/`	Email provider

5. Data Flow Summary

Auth: Login → validate creds (DB) → create session (DO) → set cookie (JWT + session id). Later requests: cookie → DO session + JWT verify.
Maintenance: CRUD and workflow (create/approve/assign/complete) → DB; cache (DO) used for reads when enabled; attachments → R2, metadata in DB.
Avatar: Upload → R2 + DB path; GET → R2 stream.
Backups: Neon’s built-in backups; optional copy to R2 (see Runbook).

6. Where to Go Next

System /system/* observability (logs, audit, monitor, settings): SYSTEM.md at repository root — types, list vs detail, writers, cross-navigation; complete this track before leaning on dashboard analytics for the same surfaces.
Admin dashboard & analytics (cache metrics, KPI payloads): DASHBOARD.md at repository root — AnalyticsCacheService, consolidated endpoints, /system/cache and /system/settings hints.
Decisions: ADR index (edge-first, DO, Neon, R2, Hono, etc.).
DO vs KV analysis: do-vs-kv-analysis.md — Why DO (not KV) for logs and maintenance cache; timestamp/indexed storage + pagination plan.
Runtime limits and behaviour: runtime/.
Core systems (auth, maintenance, cache): systems/.
Deployment and rollback: Deployment workflow and Runbook.

System Map and Infrastructure Overview ​

1. High-Level System Map ​

2. Request Flow (Simplified) ​

3. Infrastructure Diagram (By Provider) ​

Public URLs (production) ​

4. Component Map (Logical) ​

5. Data Flow Summary ​

6. Where to Go Next ​