bundeshaushalt/README.md

OpenBudget.DE – Monorepo (App Scaffold + Data Extractor)

This repository contains:

• A modern React + Vite TypeScript single‑page application scaffold located in openbudget-app-scaffold/.
• A Python utility script to extract and transform official German federal budget (Bundeshaushalt) XML data into JSON, located at the repository root.

The goal is to make the federal budget searchable, explorable, and comparable using open data and reproducible tooling.

Stack detection

• Language(s):
  • TypeScript/JavaScript (frontend)
  • Python 3 (data extraction helper)
• Frameworks & tooling (frontend):
  • React 18, React Router 6
  • Vite 7 (dev server/build/preview)
  • Tailwind CSS 3 (via PostCSS + Autoprefixer)
  • Zustand, TanStack Table, Recharts, Framer Motion, i18next, zod
  • Vitest (configured via test script)
• Package manager: npm (packageManager set to npm@11.6.1)
• Entry points (frontend):
  • HTML: openbudget-app-scaffold/index.html (mounts #root)
  • App bootstrap: openbudget-app-scaffold/src/main.tsx
  • Router: openbudget-app-scaffold/src/app/routes.tsx
  • Layout shell: openbudget-app-scaffold/src/design-system/layout/AppShell.tsx
• Dev server: Vite, default port set to 5173 in vite.config.ts.

Requirements

• Node.js 18+ (recommended) and npm (repo expects npm v11 as per packageManager)
• Python 3.9+ (for running the extract_hh2026.py helper)
• Optional: lxml Python package for XML parsing (required by the script)

Setup and run (frontend app)

From the openbudget-app-scaffold/ directory:

1. Install dependencies

   • npm i

2. Start the dev server

   • npm run dev
   • App runs at http://localhost:5173

3. Build for production

   • npm run build

4. Preview the production build locally

   • npm run preview

Quick start (as seen in the app scaffold README):

• npm i
• npm run dev
• Upload HH2026_titel_eur.json in the Explorer (once you generated it; see Data section below).

NPM scripts (frontend)

Defined in openbudget-app-scaffold/package.json:

• dev — Start Vite dev server
• build — Build the app with Vite
• preview — Preview the built app
• test — Run tests with Vitest

Environment variables

• No usage of import.meta.env or .env files was detected in the codebase.
• TODO: If the app will require configuration (e.g., data endpoints), introduce Vite env variables (e.g., VITE_API_URL) and document them here.

Testing

• Test runner: Vitest (configured via npm test).
• No test files were found in the repository at the time of writing.
• TODO: Add unit/integration tests under openbudget-app-scaffold/src/**/__tests__ or *.test.ts(x) and update this section with guidance.

Data: Bundeshaushalt extraction helper

The repository includes a Python script for converting the federal budget XML (e.g., Regierungsentwurf 2026) into JSON suitable for exploration in the app.

Script: extract_hh2026.py

Capabilities:

• Parses hierarchy: Einzelplan → Kapitel → Titel
• Converts values to EUR (XML uses thousands of EUR)
• Optional category tagging via keyword rules
• Outputs JSON files such as:
  • HH2026_titel_eur.json (full titles)
  • EP01_24_Summen_Mrd.json (EP 01–24 totals)
  • EP{EP}_TopN_Titel.json (per-EP top N list)

Usage (from repo root):

python extract_hh2026.py --xml regierungsentwurf_2026.xml --outdir ./out --topN 50 --tag

Arguments (see --help for the full list):

• --xml Path to the input XML
• --outdir Output directory (e.g., ./out)
• --topN Optional top-N per Einzelplan
• --tag Enable category tagging based on keywords

Generated files can be uploaded/ingested by the app (e.g., upload HH2026_titel_eur.json in the Explorer view).

Python dependencies:

• Requires lxml. Install via:

pip install lxml

Project structure (high level)

/ (repo root)
├─ README.md                  # This file
├─ extract_hh2026.py          # Python helper to convert XML → JSON
├─ HH2026_titel_eur.json      # Example/expected data file (output of the script)
├─ out/                       # Example output directory (generated JSON)
└─ openbudget-app-scaffold/   # Frontend web app
   ├─ README.md               # App-specific quick start (kept)
   ├─ index.html              # Vite HTML entry (mounts #root)
   ├─ vite.config.ts          # Vite config (alias @ → src, port 5173)
   ├─ package.json            # npm scripts/dev deps
   ├─ postcss.config.js       # Tailwind + Autoprefixer
   ├─ tailwind.config.ts      # Tailwind config (incl. Deutschland colors)
   └─ src/
      ├─ main.tsx             # App bootstrap
      ├─ styles.css           # Tailwind directives + utilities
      ├─ app/
      │  ├─ routes.tsx       # React Router routes
      │  ├─ providers.tsx    # App providers
      │  └─ ErrorBoundary.tsx
      ├─ design-system/
      │  └─ layout/AppShell.tsx   # Navigation shell + footer
      └─ features/
         ├─ landing/pages/LandingPage.tsx      # Landing (route index)
         ├─ explorer/pages/ExplorerPage.tsx    # Data explorer (expects JSON)
         ├─ reform/pages/ReformDesignerPage.tsx
         ├─ convert/pages/ConvertPage.tsx
         ├─ compare/pages/ComparePage.tsx
         └─ about/pages/AboutPage.tsx          # About (mentions MIT / amtliche Werke)

Note: Some feature files are referenced by the router. If any are missing in your local clone, create placeholders or pull the latest changes.

Development notes

• Aliases: @ resolves to openbudget-app-scaffold/src (see vite.config.ts). You can import like import X from '@/path/to/X'.
• Styling: Tailwind CSS is enabled. Utility classes are used extensively; see tailwind.config.ts and src/styles.css.
• Routing: See src/app/routes.tsx for routes including /convert, /explorer, /reform, /compare, /about, and a 404 fallback. The layout is provided by AppShell.

License

• Code: The About page mentions MIT for code.
  • TODO: Add an explicit LICENSE file (MIT) at the repository root and in the app package if desired.
• Data: “Amtliche Werke” (official works). Confirm exact data licensing/usage conditions for redistributed datasets and document here.

Contributing

• TODO: Add contribution guidelines, code style, and branching strategy.

FAQ / Troubleshooting

• Dev server port: If 5173 is occupied, either stop the other process or change server.port in vite.config.ts.
• Node version: If you encounter install issues, ensure Node 18+ and npm 11.x are used.
• Missing JSON: Generate data with extract_hh2026.py and upload it via the Explorer page in the app.

Changelog

• TODO: Add basic release notes once versions are tagged.