# Cloud Development Environment Platform

**Solution Architecture v1.0 · open source on raw/bare-metal compute · Platform Architecture · 2026-10 · 21 views · 14 architecture decision records**

Everyone has met this system from the outside. You click a repository, a machine appears with the code checked out and the dependencies installed, you work in it from a browser or your own editor, and a week later you come back and it is exactly as you left it — Codespaces, Replit, Gitpod, and the sandbox a cloud coding agent is handed. The product is easy to describe and the engineering underneath it is not, because three requirements pull against each other: it has to start fast, which argues for keeping machines warm; it has to be cheap enough to sell per seat when a developer's workspace is idle for most of the day it is open, which argues for keeping almost nothing warm; and it has to run code nobody reviewed, on a machine whose user has root, which argues for a boundary no container shares a kernel across. A fourth pressure arrived more recently and changes the shape of the problem: roughly two of every three workspaces are now started by a coding agent — headless, in bursts an order of magnitude above steady state, living seven minutes rather than ninety. This package is the architecture for a platform that serves both populations from one fleet. The assumed operating context is 250,000 daily active workspaces across 1,800 tenants, 60,000 concurrent at peak, 1,200,000 starts a day, 2,400,000 hibernated workspaces retained and 180 TB of new snapshot data a day, on about 1,400 owned bare-metal hosts in two regions, inside a resume budget of 2.5 seconds at p95.

The product is not the machine. It is **a workspace you can abandon without losing and resume without noticing** — and the second half is what rearranges every assumption the first half invites.

The design rests on one boundary: **the workspace is a snapshot in durable storage, late-bound to a disposable host.** That single line is why hibernation is the normal state rather than an optimisation, why host loss is a latency event rather than a data event, why kernel patching is a scheduling problem rather than a maintenance window, and why the economics work at all — idle workspaces occupy storage instead of RAM.

The decisions that carry the design:

- **The workspace is a snapshot, late-bound to a disposable host.** Identity lives in durable storage no host owns; the host's only job is to run it well and give it up cleanly (ADR-01).
- **Filesystem truth is object storage with a local copy-on-write overlay and lazy block fetch.** Time-to-usable stops scaling with disk size, and no host holds anything authoritative (ADR-02).
- **Memory state is kept while a workspace is recent and decays after a week.** Sub-second resume where it is actually used; storage bounded by recency rather than by population (ADR-03).
- **One microVM per workspace, boundary per workspace rather than per tenant.** Untrusted code is the normal case, so the boundary sits below the kernel the adversary controls (ADR-04).
- **Credentials are brokered, scoped and never resident.** Anything written into the workspace is assumed exported, so the defence is scope, a fifteen-minute lifetime and a recorded issuance (ADR-05).
- **Egress is deny-by-default for agents and allowlisted-with-audit for humans.** The strictest boundary goes where the code is least reviewed and refusal is most tolerable (ADR-06).
- **A prebuild is a post-create snapshot with an explicit validity predicate.** Create becomes restore, and staleness becomes decidable rather than guessed from age (ADR-07).
- **Capacity pressure is an explicit, class-aware refusal.** Agent creations shed before human resumes; a queue an orchestrator cannot see is worse than a no it can (ADR-08).
- **An authorised connection is the resume request.** The edge holds the client with a progress stream, so the wait has a cause (ADR-09).
- **Idleness is a composite signal on the host, with a bounded veto.** Unforgeable where it costs money, informative where it protects the developer (ADR-10).
- **Own bare metal and oversubscribe memory 4:1.** The promise is honest only because hibernation can take the memory back (ADR-11).
- **The control plane holds records, never content.** Running workspaces survive its outage, and the most attractive target in the system holds no source code (ADR-12).
- **Drain is the only maintenance mechanism.** Patching, host loss, rebalancing and idleness all use one path, so the most critical mechanism is exercised continuously (ADR-13).
- **Residency outranks availability.** Content never leaves its region; cross-region resume is a tenant-authorised migration (ADR-14).

The architecture one-pager (including why the design should still hold up in ten years, what a four-week prototype should falsify, and the six risks that would change it) and the full decision record appear on the landing page of the diagram set, directly below the index of views. The same content is published as [docs/architecture-one-pager.md](docs/architecture-one-pager.md) (~15 min) and [docs/decision-record.md](docs/decision-record.md) (~57 min).

---

## What is here

| Path | Contents |
|---|---|
| `diagrams/index.html` | The landing page: 21 views in seven acts with every format linked, then the **architecture one-pager** and the **decision record** |
| `diagrams/*.html` | One self-contained page per view: the inlined diagram plus the reasoning cards, with copy / PNG / PDF export |
| `diagrams/svg/*.svg` | The same views as SVG with the diagram XML embedded; they re-open fully editable in diagrams.net |
| `diagrams/drawio/*.drawio` | draw.io source |
| `docs/architecture-one-pager.md` | The one-pager as markdown |
| `docs/decision-record.md` | The 14 decision records, the capability-to-technology table and the package glossary as markdown |
| `specs/part-a..c.json` | Diagram specifications, the source of truth for every view |
| `specs/manifest-a..b.json` | Acts, page titles, subtitles and reasoning cards |
| `specs/adr-onepager.json`, `specs/adr-records-a..b.json` | The one-pager, the decision records, the capability-to-technology table and the glossary |
| `scripts/build.sh` | Rebuilds every deliverable from the specs (Node only, no network) |
| `ask.md` | The requirement |

## The twenty-one views

| # | View | What it answers |
|---|---|---|
| 01 | System Context | Who asks for a machine, what the platform depends on, and the three neighbouring systems drawn without a relationship on purpose |
| 02 | High-Level Architecture | Seven stages from request to running workspace, with the shedding gate ahead of placement rather than inside it |
| 03 | Actors and Their Core Journeys | Nine parties, two of them machines, including a coding agent whose goals contradict the developer's |
| 04 | Journey — Resuming Yesterday's Workspace | The trough is the wait, which is why the whole design is organised around resume rather than create |
| 05 | Journey — Forty Agent Sandboxes at Once | The workload that did not exist when this product category was designed, and the refusal it needs |
| 06 | Journey — Patching 1,800 Hosts | The operator journey that only exists because a workspace does not belong to a host |
| 07 | Layered Architecture | Eight layers with the untrusted one in the middle and the control plane outside the data path |
| 08 | Platform Components | What is stateless, what is region-pinned, what is untrusted, and what holds a key |
| 09 | Interface Catalogue | Four inbound interfaces under one authorisation model, and the single outbound path a workspace may take |
| 10 | Data Flow | What leaves the guest, what is deliberately dropped, and what never touches the control plane |
| 11 | Storage Zones by Rebuildability | Three bands: what cannot be lost, what costs time to lose, and what is on its way to deletion |
| 12 | Control-Plane Data Model | Eleven entities, and the relationship the model refuses to have — a workspace has no host |
| 13 | Critical Flow — Resuming a Workspace | Sixteen messages inside a 2.5-second budget, one of which is deliberate bad news |
| 14 | Prebuild Pipeline | How a create becomes a restore, and what makes a cached environment safe to trust |
| 15 | Stopping a Workspace | Four reasons, one mechanism, and two blank cells that carry the argument |
| 16 | Deployment Topology | Owned racks in two regions, and the one line this topology refuses to draw |
| 17 | Delivering the Platform Itself | One pipeline for kernel, host agent and control plane, with a snapshot-fidelity gate that cannot be waived |
| 18 | Observability Matrix | Five signal types across six layers, with the blank cells meant literally |
| 19 | The Loop That Pays For It | Demand to warm pools to oversubscription to hibernation to reclaim, and back |
| 20 | Trust Zones | Six zones, with the workspace sandbox above the host because it is the least trusted thing here |
| 21 | Identity Flow | Fourteen messages getting a token into a root-owned machine, of which the last two are the point |

## Rebuilding

```bash
cd architecture/deliverables/use-cases/cloud-dev-environment-platform
bash scripts/build.sh
```

Node 20+ and nothing else: no draw.io Desktop, no browser, no network. The script assembles
`specs/views.json` and `specs/manifest.json` from the authoring parts, generates and validates the
diagrams, renders the SVG and HTML, injects the one-pager and decision record into the landing page,
writes `docs/*.md`, and proves every relative link resolves. Edit the parts, never the assembled
files.

Two routing warnings are accepted in `09-integration-surface`: with four consumers and four
dependencies converging on one centre box, two protocol labels sit near a neighbouring edge. Both
are legibility nits on the least information-dense view in the set, and shortening the labels further
would cost more in meaning than it buys in geometry.