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-developer | the 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 repo | AGENTS.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 transformation | data-flow.md + transformations.md (and the rule below) |
| about to render another place | portability.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 is | adr/, the architecture decision records — including the move to WebGPU + TSL node materials (ADR 0027) |
| looking for what is planned or was rejected | plans/, 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 yet | data-streams.md, a measured survey of every source with a ranking |
| a coding agent doing rendering, data or perf work | the 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:
- 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;- data-flow.md's diagram and table reflect any new source, feature or edge;
- portability.md records the fallback if a new optional source was introduced;
- 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, andscripts/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:diagramswrites the SVG the site shows intodiagrams/and prunes the old one; commit both.bun run verifyfails while they disagree.
Plans follow their own lifecycle, described in plans/README.md.
