ms-haushalt/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project intent

Build an interactive treemap-based viewer of the City of Münster budget so non-experts can navigate where money comes from and where it goes. The 2026/2027 draft (Haushaltsplanentwurf) is the primary target; prior years and historical actuals are included for trend/context views.

No application code exists yet — this repo currently holds only source data.

Data layout

data/
  2023/                       Haushaltsplan 2023            (xlsx + csv)
  2024/                       Haushaltsplan 2024-2027       (xlsx + csv)
  2025/                       Haushaltsplan 2025-2028       (xlsx + csv)  ← latest machine-readable plan
  jahresabschluesse/          Jahresabschlüsse 2008-2022    (xlsx + csv)  historical actuals
docs/sources/
  2024/  2025/  2026_2027/    Original PDFs (Bände 1+2, Satzung, Reden)

Source: opendata.stadt-muenster.de (CSV/XLSX) and stadt-muenster.de (PDFs). License: Datenlizenz Deutschland Namensnennung 2.0.

The 2026/2027 draft is not yet on the open-data portal — only PDF. The 2025 file does include 2026/2027/2028 planning values, which is the closest machine-readable forward projection until the new draft is published as data.

Data schema (the part you must read multiple files to understand)

CSV files share one shape across all years:

• Separator: ; — encoding: UTF-8 with BOM
• Number format: German — . thousands, , decimal (e.g. -733.670.000,00)
• Sign convention: revenues are negative, expenses are positive (NRW kameral/doppik convention). Normalize/flip before display.
• Hierarchy keys: Produktbereich → Produktgruppe. Both can take the literal value Gesamt to denote a roll-up row — those rows are subtotals/totals, not leaves. Filter or use them deliberately; never sum them alongside leaves.
• Time key: Geschäftsjahr — each plan file contains multiple years (current + 3 planning years), so a single CSV is long-format across years.
• Categories (columns): ~19 fixed financial line items. Revenue side includes Steuern und ähnliche Abgaben, Zuwendungen und allgemeine Umlagen, Öffentlich-rechtliche Leistungsentgelte, etc. Expense side includes Personalaufwendungen, Aufwendungen für Sach- und Dienstleistungen, Transferaufwendungen, Bilanzielle Abschreibungen, etc. The plan files have one extra column Globaler Minderaufwand that the Jahresabschluss file doesn't.
• Header typo to preserve: Öffentlich-rechtliche Leistunngsentgelte (double-n) appears in the source — don't "fix" it on read; map it.
• Spelling drift across files: 2025 plan uses algemeine Umlagen (single-l), Jahresabschluss uses allgemeine. Treat as the same field.

The two-level Produktbereich/Produktgruppe hierarchy is the natural treemap nesting; the ~19 category columns are switchable views (revenue vs expense, or a single category drilled across products).

Design Context

(Mirror of .impeccable.md. The full design brief lives in docs/design-brief.md.)

Users

Engaged Münster citizens and journalists. German-speaking, intelligent, time-pressured. Mixed familiarity with budget docs. Many will share findings or cite specific numbers, so deep-linking and quoteable figures matter. Treat them like adults — no pictograms, no hand-holding tone.

Brand Personality

Editorial, generous, opinionated. A piece of civic data journalism, not a municipal portal and not a dashboard. Voice: composed, curious, never cute. Numbers presented with precision and context, never as "look at this big number" hero stats.

Aesthetic Direction

Print-rooted editorial. Strong serif/slab display type, asymmetric grid, generous whitespace, off-white "paper" background tinted slightly warm. The treemap is the protagonist; everything else frames it like a magazine spread frames its lead photograph. Lean toward NYT/SZ/ZEIT graphics-desk references, the Pudding's longer pieces, Vignelli-grade typographic confidence.

Anti-references (do not look like): generic SaaS dashboards, German municipal portals, AI-slop hero pages (gradient text, glassmorphism, purple-blue gradients), PowerPoint infographics.

Theme & Language

Light only, paper-feeling. German only.

Design Principles

1. The treemap is the page. Layout, type, color, and motion all serve reading it.
2. Print logic first. Asymmetric, typographic, quiet. Sunday-paper-supplement-grade.
3. Numbers in context, never alone. Every figure paired with its share, change, or what it pays for.
4. Data does the talking. Where copy exists, it points at data — never competes with it.
5. Restraint is the accent. One display face, one body face, one accent system, one motion vocabulary.

Color decided

Two-hue system: Aufwendungen and Erträge each get a hue family in OKLCH on the warm-paper background. Tile lightness/chroma encodes value within a flow. No red/green moralizing. Specific hues to be auditioned during craft.

Stack decided

Astro + D3 islands. Static-first. Deep-linkable URLs. SSR for share targets.

When extending

• Re-downloading data: see the URLs in conversation history or fetch the dataset pages on opendata.stadt-muenster.de (/dataset/haushaltsplan-YYYY-der-stadt-münster). Watch for the 2026/2027 plan to appear there — that should replace the 2025 file as the primary source.
• PDFs in docs/sources/ are the authoritative narrative; the CSVs are the data. Don't try to OCR the PDFs while structured data exists.