City Walk/WissenZum StadtspaziergangViewer
ImpressumDatenschutz
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
    • ADR 0001: Static where possible — no database, no accounts, nothing kept about a visitor
    • ADR 0002: Imperative three.js inside a React shell, not react-three-fiber
    • ADR 0005: Data stays in its provider's UTM zone, under one recenter offset and a rotated world group
    • ADR 0009: Light, shadows and post — soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool
    • ADR 0010: The look — opaque clay on a painted ground, colours within one palette, detail drawn softly
    • ADR 0012: Sources — official data first, OSM and Wikidata for what it lacks, named stand-ins marked per city
    • ADR 0018: Headless tests run a lite profile and count frames; visuals are judged on a real GPU through snapshots
    • ADR 0021: docs/ is published as /wissen, and its diagrams are prerendered SVG
    • ADR 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera
    • ADR 0027: WebGPURenderer and TSL node materials, one path, public API only
    • ADR 0030: The ground — a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules
    • ADR 0032: The camera is never below the ground or inside a building
    • ADR 0034: Picture styles are one post pass over the clay scene, reading the light and the world
    • ADR 0036: Buildings are LoD2; geometry beyond it only where a measurement and a name agree, and roofs that miss the scan are rebuilt in its form
    • ADR 0037: Cities, providers and the pipeline — fetch, bake, build; one deployment, a route per city
    • ADR 0040: Data layers are switches, off at start, drawn as glass; optional features start on first use
    • ADR 0041: Rails, trams and bridges — decks measured in the surface model, every line on a drivable profile solved by the build
    • ADR 0042: The twin answers on demand — facts and provenance ride in the tileset, text appears only when asked
    • ADR 0043: Crash and page reports go to an error tracker without an SDK, and the privacy page says what the code does
    • ADR 0044: Modell — the city in parallel projection, every pass reading the camera through a lens
    • ADR 0047: Every device gets a budget in true bytes, a phone's memory never grows, and a device that lost its GPU gets a lighter page
    • ADR 0048: A network failure is retried for a budget of the page's visible time, never decided at once
    • ADR 0054: A planner's design is loaded on the device, placed by its coordinates or by hand, and stands in for the buildings it covers
    • ADR 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced
    • ADR 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools
    • ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
    • ADR 0059: One schema per file a bake hands over, checked by the build
    • ADR 0060: Glass fronts are read from street photos by an open image model, offline
    • ADR 0061: The scene runs in a worker; the page hosts it
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
  • What the data streams carry that the walker does not use yet
Contents
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
    • ADR 0001: Static where possible — no database, no accounts, nothing kept about a visitor
    • ADR 0002: Imperative three.js inside a React shell, not react-three-fiber
    • ADR 0005: Data stays in its provider's UTM zone, under one recenter offset and a rotated world group
    • ADR 0009: Light, shadows and post — soft PCF redrawn on demand, four concentric rings, a baked horizon for the far field, a fixed lamp pool
    • ADR 0010: The look — opaque clay on a painted ground, colours within one palette, detail drawn softly
    • ADR 0012: Sources — official data first, OSM and Wikidata for what it lacks, named stand-ins marked per city
    • ADR 0018: Headless tests run a lite profile and count frames; visuals are judged on a real GPU through snapshots
    • ADR 0021: docs/ is published as /wissen, and its diagrams are prerendered SVG
    • ADR 0024: The build bakes each city into a 3D Tiles tileset that streams around the camera
    • ADR 0027: WebGPURenderer and TSL node materials, one path, public API only
    • ADR 0030: The ground — a TIN of the native DGM, its static parts baked in, every part meeting it by one set of rules
    • ADR 0032: The camera is never below the ground or inside a building
    • ADR 0034: Picture styles are one post pass over the clay scene, reading the light and the world
    • ADR 0036: Buildings are LoD2; geometry beyond it only where a measurement and a name agree, and roofs that miss the scan are rebuilt in its form
    • ADR 0037: Cities, providers and the pipeline — fetch, bake, build; one deployment, a route per city
    • ADR 0040: Data layers are switches, off at start, drawn as glass; optional features start on first use
    • ADR 0041: Rails, trams and bridges — decks measured in the surface model, every line on a drivable profile solved by the build
    • ADR 0042: The twin answers on demand — facts and provenance ride in the tileset, text appears only when asked
    • ADR 0043: Crash and page reports go to an error tracker without an SDK, and the privacy page says what the code does
    • ADR 0044: Modell — the city in parallel projection, every pass reading the camera through a lens
    • ADR 0047: Every device gets a budget in true bytes, a phone's memory never grows, and a device that lost its GPU gets a lighter page
    • ADR 0048: A network failure is retried for a budget of the page's visible time, never decided at once
    • ADR 0054: A planner's design is loaded on the device, placed by its coordinates or by hand, and stands in for the buildings it covers
    • ADR 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced
    • ADR 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools
    • ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
    • ADR 0059: One schema per file a bake hands over, checked by the build
    • ADR 0060: Glass fronts are read from street photos by an open image model, offline
    • ADR 0061: The scene runs in a worker; the page hosts it
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
  • What the data streams carry that the walker does not use yet
Entwicklung (English)

ADR 0059: One schema per file a bake hands over, checked by the build

  • Status: accepted
  • Date: 2026-11

Context

A Python bake writes a file as a dict literal; TypeScript read it with readJson(path) as T. Its shape was written three or four times — the dict, the pytest asserts, a TypeScript interface, sometimes a viewer guard — and nothing compared the copies. A renamed key, a number turned string or a field whose meaning changed in Python passed every check: the reader saw undefined, and a layer, a card or the Stadtwissen was silently poorer. One such drift was live: the monuments' wikidata names the item their material came from, while the Stadtwissen republished it as the item OSM links the monument to.

The GeoJSON layers and the city mesh's other tile sources were held by features.test.ts, which checks every committed file but not the build's reads; the JSON files the build and the Stadtwissen cast were held by nothing.

Decision

  1. Every JSON file a bake writes and TypeScript reads has one zod schema, in lib/city/<name>-file.ts, its head comment naming its writer, step and readers. Strict (an unknown key is an error), no .transform, .default, .catch or .pipe; readers take its z.infer, and the hand-written interfaces go. A union the viewer has (WallMaterial, MonumentKind …) is the schema's enum, held equal by a test. The city mesh's and the terrain's tile sources came under this in a later pass (doors, dormers, passages, plinths, small buildings, structures, measured roofs, shopfronts, windows, kerbs, walls, stairs, terraces); features.test.ts keeps the value rules a shape does not say (a door's range, a normal's length). A new file takes a schema.
  2. The build parses before it reads. parseBakeFile (lib/city/bake-file.ts) replaces the cast: per tile in the step module that reads the file, site-wide in prepare-data.ts before it publishes the bytes. A mismatch ends the build naming the file, the schema, its writer, the first problems' key paths and the re-bake command. The parse returns its input, never zod's copy: a copy reorders keys, and baked bytes follow the file's order.
  3. Every committed file is parsed by a test (bake-files.test.ts), which also checks that what a schema accepts it returns unchanged.
  4. The viewer takes the types only. app/ and the other lib/city modules import a schema module with import type; zod stays in the Frag die Stadt chunk alone (ADR 0047). The viewer keeps its hand guards for what it fetches, and a test pins each guard to its schema: it accepts every committed file, and refuses what the schema refuses.
  5. A bake that changes a key it writes changes the schema in the same commit, and the committed data is re-baked before that commit merges.

Consequences

  • A drift fails bun run verify or the build, never a layer at runtime; between a schema change and its re-bake, bake-files.test.ts fails.
  • The schema modules and zod's locked version are in the keys of the city, stadtwissen and siteStats bakes and, through scripts/tile-sources.ts and the canopy's and the crowns' readers, of the ground's family and the side bakes: zod is pinned exactly, and a bump re-bakes those artifacts once, byte for byte the same.
  • A new handed-over file gets a schema module, a row in bake-files.test.ts and parseBakeFile where it is read (uncached and site-wide: a NOT_A_BAKE entry too).

Alternatives

  • A hand guard per reader: what drifted; one more copy of the shape.
  • pydantic models with generated TypeScript: a generator in the build, and the truth on the side the browser never runs.
  • protobuf or another IDL: a toolchain; files no longer diffable.
  • pytest against z.toJSONSchema's export: a new Python dependency (jsonschema) for now; the export keeps it a small step later.
Previous
ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
Next
ADR 0060: Glass fronts are read from street photos by an open image model, offline
Source on GitHub: docs/adr/0059-one-schema-per-file-a-bake-hands-over.md
On this page
  • Context
  • Decision
  • Consequences
  • Alternatives