Architecture decision records
One file per decision that constrains future work: a dependency, a data format, a rendering approach, a workflow rule, or a rejected alternative that must not be retried blindly. ADRs record why the code is the way it is; the ledger transformations.md records what each data → look transformation does, and rendering.md and data-pipeline.md how it is built.
Index
| # | Decision |
|---|---|
| 0001 | Static where possible: no database, no accounts, nothing kept about a visitor; stateless server functions only where a source or service needs one |
| 0002 | Imperative three.js inside a React shell, not react-three-fiber |
| 0005 | Data stays in its provider's UTM zone, under one recenter offset and a rotated world group |
| 0009 | Light, shadows and post: soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool, DoF dropped while moving, AO never |
| 0010 | The look: opaque clay on a painted ground, colours within one palette, windows drawn by the shader, detail soft, water matte |
| 0012 | Sources: official data first, OSM and Wikidata for what it lacks, named stand-ins marked per city, no look switch per city |
| 0018 | Headless tests run a lite profile and count frames; visuals are judged on a real GPU; the Snapshot is a validated contract |
| 0021 | docs/ is published as /wissen, and its diagrams are prerendered SVG |
| 0024 | The build bakes each city into a 3D Tiles tileset that streams around the camera, content-hashed, first frame before the rest |
| 0027 | WebGPURenderer and TSL node materials, one path, public API only |
| 0030 | The ground: a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules |
| 0032 | The camera is never below the ground or inside a building |
| 0034 | Picture styles are one post pass over the clay scene, reading the light and the world |
| 0036 | Buildings are LoD2; geometry beyond it only where a measurement and a name agree; roofs that miss the scan are rebuilt in its form |
| 0037 | Cities, providers and the pipeline: fetch, bake, build; one deployment, a route per city |
| 0040 | Data layers are switches, off at start, drawn as glass; optional features start on first use |
| 0041 | Rails, trams and bridges: decks measured in the surface model, every line on a drivable profile solved by the build |
| 0042 | The twin answers on demand: facts and provenance ride in the tileset, text appears only in a card |
| 0043 | Crash and page reports go to an error tracker without an SDK; the privacy page says what the code does |
| 0044 | Modell: the city in parallel projection, every pass reading the camera through a lens |
| 0047 | Every device gets a budget in true bytes, a phone's memory never grows, a device that lost its GPU gets a lighter page |
| 0048 | A network failure is retried for a budget of the page's visible time, never decided at once |
| 0054 | A planner's design is read on the device, never uploaded, placed by its coordinates or by hand, and stands in for the buildings it covers |
| 0055 | What the twin knows is baked as files for agents; walks are written ahead, checked against the data, their narration marked as Claude's |
| 0056 | Frag die Stadt runs on the visitor's own key through one stateless function with a fixed prompt and fixed tools; the key stays in the browser, the answers are marked |
| 0057 | The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does |
| 0059 | Every file a bake hands over to TypeScript has one strict zod schema; the build parses it and fails on a mismatch, a test parses every committed file, the viewer takes the types only |
| 0060 | Glass fronts are read from street photos of any camera by an open image model at fetch time, never in the viewer; the photos' glass is the material where no source names one |
| 0061 | The scene runs in a worker on an OffscreenCanvas and touches no DOM; the page hosts it; a browser whose worker cannot draw is told so, and the page runs the same server only for debugging (?thread=main, ?inspect=1) |
Numbering
Numbers missing from the index belonged to records merged into others; they are never reused. A new record takes the next number after the highest ever used (0061), checked against main and the open PRs' branches.
Format
# ADR NNNN: Title (a decision, not a topic)
- **Status:** proposed | accepted
- **Date:** when it was decided (month precision is fine)
## Context — the forces, in a few sentences
## Decision — the rule, in the active voice and the present tense
## Consequences — what must now be kept true
## Alternatives — only what someone would otherwise retry, with the reason
Rules:
- An ADR states today's decision. When it changes, rewrite the text; do not append an "Update" or "Amendment". The history is in git.
- A superseded ADR is deleted; code that cited it cites its successor.
- About a page, at most ~600 words. Measurements, constants, file lists and tuning stories belong in code comments or the developer docs.
