Initial design

CLAUDE.md

@@ -0,0 +1,76 @@
+# Amateurfunk — BNetzA Question Catalog Downloader
+
+A small Python tool that downloads the latest German amateur-radio exam
+question catalog ("Fragenkatalog") published by the Bundesnetzagentur
+(BNetzA) and extracts the structured JSON + SVG image assets for further
+use (study apps, flashcards, training tools, etc.).
+
+The full source-discovery notes, JSON schema, and design decisions live
+in `DESIGN.md`. This file is a short orientation for anyone (human or
+agent) opening the project.
+
+## What the catalog is
+
+- Official German amateur-radio exam questions for classes **N, E, A**
+  (German license tiers).
+- Published by the Bundesnetzagentur under the **DL-DE→BY-2.0** open
+  data license (free reuse, attribution required).
+- Distributed as a single ZIP containing one JSON file with the full
+  question tree, plus a `svgs/` folder with figures referenced by
+  individual questions.
+- Current edition at time of writing: **3. Auflage, März 2024**
+  (issued 2024-03-20, valid from 2024-06-24, ~1750 questions).
+
+## Canonical source
+
+- ZIP (machine-readable): `https://www.bundesnetzagentur.de/SharedDocs/Downloads/DE/Sachgebiete/Telekommunikation/Unternehmen_Institutionen/Frequenzen/Amateurfunk/Fragenkatalog/PruefungsfragenZIP.zip?__blob=publicationFile`
+- Landing page (short link): `https://www.bnetza.de/amateurfunk-fragenkatalog`
+- PDF (human-readable, not used by this tool): same path with
+  `Pruefungsfragen.pdf` instead of `PruefungsfragenZIP.zip`.
+
+The ZIP URL is stable across editions — BNetzA replaces the file
+in-place. The `Last-Modified` HTTP header is reliable for change
+detection. The filename inside the ZIP (`fragenkatalog3b.json`) encodes
+the edition (`3b` = 3rd edition, revision b) and will change on new
+editions, so we discover it from the archive rather than hard-coding.
+
+## Scope of the tool (initial)
+
+1. Download the ZIP from the canonical URL.
+2. Verify it is a valid ZIP and contains the expected JSON + SVG files.
+3. Extract to a target directory (default: `./data/<edition>/`).
+4. Emit a small `manifest.json` next to the data: source URL, fetched-at
+   timestamp, `Last-Modified` from the server, JSON edition metadata,
+   sha256 of the ZIP.
+5. Be idempotent — re-running without an upstream change is a no-op.
+   The skip key is the HTTP `Last-Modified` header recorded on the
+   previous manifest; the ZIP is deleted by default after extraction,
+   so the recorded sha256 is provenance, not a re-verification target.
+   See `DESIGN.md` for the full idempotency contract.
+
+Out of scope for v1 (kept for later): rendering LaTeX/SVG, building a
+study app, multi-edition diffing, mirroring the PDF.
+
+## Repo conventions
+
+- Python 3.11+, standard library only where reasonable (`urllib`,
+  `zipfile`, `hashlib`, `json`, `pathlib`). Add deps only if they pay
+  for themselves — none expected for v1.
+- Single-purpose script: `amateurfunk_fetch.py` (or a tiny package if
+  it grows). No framework, no CLI library beyond `argparse`.
+- Downloaded data is treated as a build artifact: kept under `data/`
+  and gitignored.
+- License attribution string (required by DL-DE→BY-2.0) is preserved
+  verbatim from the upstream `README.txt` whenever we redistribute the
+  data.
+
+## Working on this repo
+
+- Start from `DESIGN.md` — it has the JSON schema, the question/answer
+  conventions (answer A is always correct, B/C/D are distractors), the
+  LaTeX-in-questions caveat, and the SVG naming convention.
+- Do not invent new download URLs; the ones in `DESIGN.md` were
+  verified against the live BNetzA site.
+- When BNetzA publishes a new edition, expect a new
+  `fragenkatalog<N><rev>.json` filename inside the ZIP. The downloader
+  must not hard-code the current name.