From 4c6d7fe5b306d876094601000ecf9683d18a727a Mon Sep 17 00:00:00 2001 From: "stephan.kasdorf" Date: Tue, 21 Oct 2025 11:03:40 +0200 Subject: [PATCH] Add README.md for OpenBudget.DE monorepo --- README.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c5855b1 --- /dev/null +++ b/README.md @@ -0,0 +1,166 @@ +# 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.