# 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.