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 0056: Frag die Stadt runs on the visitor's own key, through one stateless function with a fixed prompt and fixed tools

  • Status: accepted
  • Date: 2026-10

Context

A visitor asks about the city in a chat; the answer comes from the twin's knowledge (ADR 0055) and the view goes there. The site pays for no model, the visitor brings a key of any of the usual providers, a generated answer may show if it is marked, and a phone loads nothing of the chat before it is opened. A key cannot go from the browser to every provider directly (CORS, more logs), and the Stadtwissen is too large to load into the browser.

Decision

  1. One stateless server function relays each turn, and the turn is one function. POST /api/frag takes the conversation, the key in the x-frag-key header and the chosen provider and model, and streams the answer as server-sent events. The turn — the request's checks in their order, the run, how it ends — is answerTurn (lib/city/ask-run.ts); the route (app/api/frag/route.ts) only binds it to the provider's adapter (TanStack AI: Anthropic, OpenAI, OpenRouter, the Vercel AI Gateway) or the scripted one, the Stadtwissen and the secret. It keeps no conversation, no key and no log of either. POST /api/schluessel checks a key once without spending tokens and returns a token (an HMAC with the site's FRAG_SECRET, lib/city/ask-token.ts) the chat route requires. Every refusal, and every end the stream would not explain (the turn cap, the deadline, the model's output spent, a filtered answer), carries a code from one table, lib/city/ask-failure.ts, whose words the card shows; the card turns a coded refusal into a stream error, so both reach it alike.
  2. The prompt and the tools are fixed on the server (lib/city/ask-run.ts, ask-prompt.ts, ask-tools.ts): one job (this city, this viewer; facts from the tools with their source; legends as legends; today's date). The Stadtwissen's tools run on the server (ask-knowledge.ts, over a copy the build keeps in .stadtwissen/), the scene's in the browser (app/_components/ask-scene.ts): a scene tool interrupts the run, the browser runs it and resumes. Only curated models are accepted, and a conversation keeps to caps (ASK_LIMITS). A call an earlier answer ended without a result (the visitor stopped it, or the run ended) gets a stand-in result, abgebrochen, before the next question, and arguments cut off mid-stream become {} in every row (withStoppedCallsAnswered): providers refuse a history with either.
  3. The key stays in the visitor's browser, for the tab or, if asked, on the device (frag-die-stadt); the function forwards it to the provider and scrubs it from any error it sends back.
  4. The answer is marked. The card (app/_components/ask-city.tsx, its own chunk) labels every answer KI, says it is generated and can be wrong, and lists the tools the model used.

Consequences

  • The function costs the site function time only and bundles the Stadtwissen of every built site (about 4 MB a site).
  • Abuse is bounded by the token, the caps and the curated models; rate limits, bot protection and the spend limit are host and provider settings, not code.
  • FRAG_SECRET must be set on a production server, or the routes answer 501; every refusal logs a status and reason code, never the key or the conversation. A new reason a turn is refused or ends with is a row in the table; its codes are kebab-case, so a provider's code ("401", max_tokens) is never read as ours. FRAG_FAKE=1 is a scripted model for local tests only and is ignored on Vercel. One request takes at most eight model turns and ends with an error 10 s before its 300 s of function time; one answer, across the requests the scene tools resume, takes at most twelve turns.
  • The privacy page names what is sent, to whom, and the storage key (ADR 0043). Generated answers show in their own card, marked (ADR 0042).
Previous
ADR 0055: What the twin knows is baked as files; walks are written ahead, their narration marked, every claim sourced
Next
ADR 0057: The Sprachführer speaks and listens with the browser's own voice, and the scene rests while it does
Source on GitHub: docs/adr/0056-frag-die-stadt-runs-on-the-visitors-key.md
On this page
  • Context
  • Decision
  • Consequences