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
  • 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
  • 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)

docs/ — the project knowledge base

Durable, version-controlled documentation for the 3D city walker (one deployment, a route per built site; Dresden is the reference site, the one whose data is committed): what it shows, where the data comes from, how it is built, which decisions were taken and why, and what is still open. It lives in the repository so it survives across chat threads and contributors.

The site publishes this folder as it is: the guide under /wissen, the rest under /wissen/dev (ADR 0021). Write for GitHub – relative .md links, Mermaid in fenced blocks – and the pages follow.

Start here

You are…Read
a user or a curious non-developerthe guide — in English and German: how it works, where the data comes from, from download to browser, using the viewer, glossary
a developer new to the repoAGENTS.md for stack, commands and the hard rules, then rendering.md and data-pipeline.md; the architecture's decisions are the ADRs, starting with 0024 (the tileset), 0027 (WebGPURenderer, TSL), 0037 (cities and the pipeline) and 0010 (the look)
about to change a data → feature transformationdata-flow.md + transformations.md (and the rule below)
about to render another placeportability.md, the site config (ADR 0037) and plan 017
about to write a walk (the Spaziergänge)walks.md: what makes a walk worth taking, the file, the Stadtwissen to write from, the checks (ADR 0055)
looking at what the scheduled agents do (Sentry, open data, OSM gaps, street photos)routines.md: each routine's skill, script, schedule and the issue it reports to
wondering why something is the way it isadr/, the architecture decision records — including the move to WebGPU + TSL node materials (ADR 0027)
looking for what is planned or was rejectedplans/, the implementation plans, backlog and audit history — open now: 019 (the one GPU checklist), 021 (/wissen on Astro Starlight) and the plans of the 2026-10-01 audit — the index gives their order
looking for data we do not use yetdata-streams.md, a measured survey of every source with a ranking
a coding agent doing rendering, data or perf workthe city-walker skill; for a new layer, bake step or city the checklists in new-scene-layer, new-bake-step, add-city

Map

docs/
├── README.md              this page
├── guide/                 user-facing, EN + DE (no jargon; every term in the glossary)
│   ├── en/  how-it-works · data-sources · data-journey · using-the-viewer · glossary
│   └── de/  the same five pages in German
├── rendering.md           how data becomes pixels: scene graph, visual-encoding codebook, light, post, budget, streaming boot
├── data-pipeline.md       the Python bakes, the tileset build step, artifact contracts, sizes, provenance, regeneration
├── data-flow.md           source → feature provenance diagram + feature table
├── transformations.md     the ledger: every transformation built / experimental / planned / discontinued, with why
├── portability.md         degradation matrix + porting checklist for other locations
├── walks.md               writing a walk: what makes one worth taking, the file, the checks
├── routines.md            the scheduled agents: skills, scripts, what they may and never do
├── data-streams.md        what the sources carry that no bake reads yet (survey, 2026-09-27)
├── adr/                   architecture decision records (one decision per file, numbered)
├── plans/                 implementation plans: open work, condensed history, backlog, audit findings
└── diagrams/              the Mermaid blocks above, rendered to SVG (generated: bun run docs:diagrams)

Roles at a glance: AGENTS.md = orientation and the hard rules, the skills = how the tricky parts are built and the checklists for common additions, ADRs = the decisions and why, the rest of docs/ = what it shows, what maps to what, and what is next. Each fact has one home; the docs-upkeep skill lists them. Personal agent memory is a scratchpad; anything durable belongs here.

Keeping these docs current

Docs are only useful if they do not rot. Treat them as part of "done":

Definition of Done — a change that adds, alters, or drops a data → feature transformation is not complete until:

  1. transformations.md has the entry with the right status (✅ active · 🧪 experimental · 📋 planned · 🗃️ discontinued — and why, especially for discontinued) and, if active or experimental, its method badge (❝taken · =computed · ◎detected · ≈assumed, lib/city/methods.ts); the guide's methods page (EN and DE) and the inquiry card's lineage (lib/city/lineage.ts) say the same;
  2. data-flow.md's diagram and table reflect any new source, feature or edge;
  3. portability.md records the fallback if a new optional source was introduced;
  4. the visual-encoding table in rendering.md and, if a user can see the difference, the guide's layer table (EN and DE) follow.

A change that adds or reshapes a part that stands on the ground (a kerb, a wall, a deck, a shed, a bench …) follows ADR 0030: its feet and edges come from lib/city/ground-join.ts, its builder reports its joins, and scripts/ground-joins.test.ts (baked parts) or its own unit test (runtime parts) checks them.

A change that adds a dataset or edition updates the guide's data-sources page (both languages: download route, strengths and weaknesses, edition, licence) and data-pipeline.md.

A change that sends a visitor's data somewhere new — a request from the browser to a third party (a live feed, a font, an embed), a new field in the crash reports, a new key in the browser's storage — updates the site's privacy page, app/(legal)/datenschutz/page.mdx (ADR 0043).

A decision that constrains future work (a dependency, a format, a rendering approach, a rejected alternative) gets an ADR. A rejected idea is worth as much as a shipped feature: write it down as 🗃️ discontinued in the ledger so the next thread does not retry it blindly.

Numbers in the guide (download sizes, feature counts, dates) are measured, not estimated; data-pipeline.md says how.

A change to a Mermaid diagram re-renders it: bun run docs:diagrams writes the SVG the site shows into diagrams/ and prunes the old one; commit both. bun run verify fails while they disagree.

Plans follow their own lifecycle, described in plans/README.md.

Next
Rendering — how the data becomes pixels
Source on GitHub: docs/README.md
On this page
  • Start here
  • Map
  • Keeping these docs current