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 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced

  • Status: accepted
  • Date: 2026-10

Context

The twin should tell the city, not only answer what a clicked thing is. An agent (writing walks now, the chat of ADR 0056 later) needs what the twin knows as searchable text, with a name joined to a place and a source. Generated text must not pass for data (ADR 0042), and a phone's memory and first load must not grow (ADR 0047).

Decision

  1. The Stadtwissen is baked, not served. prepare-data.ts publishes per tile a directory of every root Building that OSM names or addresses, that is listed or part of a landmark (gml:id, name, address, decoded use and roof, height, storeys, position, Q-id) and the tile's named monuments (name, kind, material, position, the Wikidata item OSM links it to — wd — and the item its material comes from — materialWd; stadtwissen_<tile>.json, scripts/prepare/stadtwissen.ts), and a site index stadtwissen.json: the landmarks, an excerpt of Wikidata's statements about each in words, the sources with their licences. The excerpt is fetched once (bun scripts/fetch-stadtwissen.ts <site>, CC0) and committed as data/<site>/wissen/wikidata.json, so the build stays offline. lib/city/stadtwissen.ts is its shape and search, bun scripts/stadtwissen.ts its command line. The viewer never loads it.
  2. Walks are written ahead and committed (data/<site>/walks/*.json, lib/city/walks.ts, the guide docs/walks.md): stops with an eye on the measured ground, the hour, an optional picture style (never Modell: a walk is seen, and the jump into it broke the glide), the narration, notes for days and seasons, and the facts it rests on — each a sentence with an https source or a Stadtwissen id. walks.test.ts holds them to the data; the build bundles them into walks.json, which the HUD fetches when it lists the walks.
  3. The narration is marked, the facts are sourced. Every stop's card says it was told by Claude (KI) and when, and folds the claims out with their sources. A legend is told as a legend; a claim in facts is one a source states.
  4. A walk is told on the way. Each stop glides at 2.2× the usual pace, so the stop's story starts on the way, and the light glides to the next stop's hour with it; a stop's text fits a phone screen (560 characters). A look from the air or the street does not stop the glide: the stop still lands. On a phone the card is a bottom sheet that starts folded, so the scene stays in view.
  5. The text points only at what the model draws; a photo shows the rest. The model has masses, roofs as planes, towers, bridges, the river and the ground; a statue is a generic figure, and reliefs, inscriptions, colours and interiors are not there. A sentence that sends the eye to look ("Schau …", "Sieh …") points at the stop's photo, which walks.test.ts checks. The photo is a Wikimedia Commons file the stop names, copied once by bun scripts/walks.ts <site> photos as an 800 px WebP into data/<site>/walks/photos/, committed and served by the site itself with its author, licence and link on the card: the viewer asks no third party for it.

Consequences

  • An agent reads the city through one module and a few files, the source beside each value; serving it (an API, an MCP server) is not needed.
  • A walk is checked numerically (ground, extent, references); its look with bun scripts/walks.ts <site> shots and bun run shots when it is written or the scene changes.
  • Another city's walks are a writing task, not a code change.
  • A photo is a few dozen kilobytes in the repository and loads only with its stop's card.
  • Text other than the inquiry card's shows in the viewer, in the walk card only, marked as narration (amends ADR 0042).
Previous
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
Next
ADR 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools
Source on GitHub: docs/adr/0055-stadtwissen-and-written-walks.md
On this page
  • Context
  • Decision
  • Consequences