Architecture overview
How Cloud Control is built: a Next.js App Router console, a driver-agnostic storage seam over SQLite, Postgres and Turso, the CloudProvider adapter seam, and the sync engine.
Cloud Control is a Next.js App Router application in TypeScript with a real authentication backend. It is designed around a few clean seams so that the same code runs identically on a laptop, in Docker, and on Vercel — and so that swapping a database or a cloud adapter never touches the rest of the system.
The console
Every screen has a distinct, deep-linkable URL — /dashboard, /inventory, /network, /cost, /audit, and so on — each server-validating the session on a direct load. After the first load, switching screens stays client-side through a single navigation seam, so the app feels instant without a second routing mechanism. The platform-admin console lives on its own page at /admin and is invisible (a 404) to anyone who is not a platform admin.
The storage seam
All database access goes through one driver-agnostic async Store interface. Three drivers implement it identically:
| Driver | Engine | Selected when |
|---|---|---|
sqlite | Node's built-in node:sqlite | Default — local development and Docker. |
postgres | pg | DATABASE_URL is set (for example in Docker Compose). |
turso | libSQL / @libsql/client | TURSO_DATABASE_URL is set (the live deployment). |
The three drivers are behaviorally identical — the same schema, the same seed, and ISO-8601 timestamp strings at every boundary. Nothing outside the storage layer imports a driver directly. The active driver is reported by `GET /api/health`, which is how a deployment self-diagnoses which database it is really talking to.
The CloudProvider seam
Cloud integrations sit behind a CloudProvider adapter interface. There are real adapters for AWS (STS AssumeRole with SigV4-signed calls) and GCP (workload identity federation with Cloud Asset Inventory). For development and the end-to-end test suite, setting CC_CLOUD_MODE=mock swaps in deterministic in-process 'mock worlds' so connection, sync and cost flows are testable without real credentials. A boot tripwire forbids mock mode on Vercel or any credentialed deployment.
The sync engine
Inventory freshness is the job of a single pass-runner driven three ways: a scheduled cron pass, a 'connect-kick' immediately after a connection turns healthy, and on-demand 'Sync now'. All three run the same engine — lease-claimed work units, persisted token buckets with jittered backoff, and delta cursors — with all state in the Store. The browser never calls a cloud API directly. See Resource inventory & sync.
Request lifecycle
Edge middleware does a fast cookie-presence check only — it cannot reach the database — redirecting page requests without a session to /login and answering API requests with a JSON 401. Real session validation happens server-side in the route handlers and pages. Route handlers stay thin: parse, validate, call into the server library (auth, authz, cloud, finops), and shape the response.
Deployment
Vercel is the primary deployment, backed by Turso. Docker Compose runs the console against Postgres for a self-contained local stack. Because serverless filesystems are ephemeral, any non-local deployment must use Postgres or Turso — SQLite is the local default only. See Environment variables.