Add README.md for OpenBudget.DE monorepo

2025-10-21 11:03:40 +02:00
parent 06a312d5e9
commit 4c6d7fe5b3
1 changed files with 166 additions and 0 deletions
--- a/README.md
+++ 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.