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.