feat: add a live Postgres city to the front page

[NikolayS]

An animated, simplified PostgreSQL cluster for the front page, sitting between the hero CTA and the demo video.

Derived from PGSimCity (Apache-2.0), which is the same cluster in three dimensions. It keeps that project's plan, its compass and both of its hand-tuned semantic palettes, and drops the renderer: this is plain canvas 2D, no new dependency, no WebGL, no network — 10.1 KiB gzipped for the scene and the model together.

What it shows

Everything that moves is a consequence of a small deterministic model running in the reader's browser, and the order it happens in is the order PostgreSQL does the work:

• The postmaster forks one backend per connection, not per statement. Each connection gets its own duct from the client terminal and keeps it for the session — this is the misconception the scene most needed not to reinforce.
• A read that misses in the pool goes to storage. The clock sweep picks the victim, caps usage_count at 5, and a dirty victim is written out by the backend that needed the frame.
• A write dirties a page in shared memory and produces a WAL record. The commit waits for that record to reach durable storage, and the data page is still dirty in memory when the commit returns. No code path marks a frame clean at commit time — the claim is structural, not decorative.
• Dirty pages reach the data directory later: at a checkpoint, through the background writer, or because another backend needed the frame. A write-back only cleans a frame if it was not re-dirtied mid-write (BM_JUST_DIRTIED).
• full_page_writes re-arms at every checkpoint, so WAL volume climbs after one begins — and replication lag climbs with it.
• Replication ships the log. No data page crosses the wire; the standby's own frames are drawn from replay.

Honesty

Only dimensionless figures appear on screen — cache hit ratio by PostgreSQL's own blks_hit / (blks_hit + blks_read), dirty share of the pool, and a replay-lag bar. Nothing on the page can be mistaken for measured throughput from a real database.

The caption saying this is a model and not live data is treated as content rather than chrome: it is present in full at every breakpoint, including 390px, where the scene itself shrinks instead.

Behaviour

• Two separately tuned palettes for light and dark, following data-theme — not one set dimmed for both.
• Pauses when scrolled off-screen and when the tab is hidden. Honours prefers-reduced-motion, composing a still frame with an explicit control to start it.
• Every district is a real focusable control with a screen-reader description, plus a full text alternative of the city and the write path.
• Dirty frames stand proud of the deck. Clean and dirty are ~140° apart in hue but close in luminance, so height carries the same information where colour cannot — on a monochrome display or for a reader with a colour-vision deficiency.
• Fixed timestep, preallocated particle pool, all screen-space geometry computed once: the animation loop allocates nothing.

Tests

bun test src/components — 47 tests, added as a test script using the repo's existing bun, no new dependency.

They assert the claims the drawing makes rather than this calibration's numbers: that no structure stands unsupported over the excavation, that storage renders below memory, that each backend has its own connection duct and none crosses the postmaster's avenue, that pages survive a commit dirty, that WAL climbs after a checkpoint, and that both palettes stay perceptually separable (ΔE floors set just under what they measure today).

Verification

• bun test src/components — 47 pass
• bun run build — succeeds; only the repo's pre-existing broken-anchor warnings
• Rendered and inspected at 1280px and 390px, in both themes

Notes for review

• The title above the figure ("A PostgreSQL cluster, running") is a prop and easy to change or drop.
• Distance is compressed relative to PGSimCity and the excavation is a southern cutaway rather than a symmetric pit — a fixed camera cannot see into a symmetric one. Direction and ordering are exact; the compression is disclosed in plan.ts.
• npx tsc --noEmit is broken on master already (the root tsconfig.json extends @tsconfig/docusaurus, which is not in devDependencies). Left alone; the component typechecks clean under the correct config.
• The built site did not hydrate in this sandbox's headless Chromium — but neither did pages containing none of this code, so it is environmental. The component was verified by mounting it directly.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NeTbYVtLkNTuwrRC6yUVva

---

Generated by Claude Code