Hausheld
Home-help workflow platform for NRW — scheduling, GPS-verified check-in/out, digital signatures, and Entlastungsbetrag tracking. Built with data integrity and EU/GDPR in mind.
Problem
A 200-employee home-help service in NRW faced manual paper schedules, proof of service on paper, and strict regulatory requirements (GDPR, SGB XI) for health data and billing.
Solution
A distributed ecosystem: one FastAPI backend (PostgreSQL + PostGIS), a Next.js PWA for field workers (schedule, GPS check-in/out, client signatures), and a Vite+React admin dashboard (calendar, sick leave, substitute suggestions, budget alerts, SGB XI CSV export, audit log). PostGIS powers distance-based substitute suggestions; a strict shift state machine and append-only audit log support compliance.
Features
- Mobile PWA: Workers see their schedule, check in/out with GPS, capture client signatures (Leistungsnachweis).
- Admin dashboard: Calendar, sick leave, substitute suggestions, client budget alerts, SGB XI CSV export, audit log.
- Substitution engine: Suggests up to 3 replacement workers by distance (PostGIS) and weekly capacity.
- Budget & billing: Per-client monthly budget, 15% alert threshold, CSV export for insurance (SGB XI).
- Audit trail: Append-only log of every access to client (health) data; read-only API.
Architecture
Hausheld is a distributed ecosystem: one API, two frontends. All mutations go through the backend with JWT and role-based access (Admin vs Worker).
flowchart LR
subgraph Clients
PWA["Mobile PWA - Next.js"]
Admin["Admin Dashboard - Vite + React"]
end
subgraph Backend["Backend API"]
API["FastAPI / PostgreSQL + PostGIS"]
end
PWA <-->|JWT| API
Admin <-->|JWT| API- Backend: Single source of truth. FastAPI, SQLAlchemy 2 (async), PostgreSQL + PostGIS, Alembic. Enforces RBAC, encrypts health data, writes to the audit log.
- Mobile: Next.js PWA (German UI). Schedule, check-in/out, signature pad, client list for assigned shifts.
- Admin: Vite + React. Calendar (FullCalendar), workers & sick leave, clients & budget alerts, billing export, audit log, substitute assignment.
Data flow is unidirectional: frontends only call the API; no direct DB access from the client.
Tech stack
| Path | Stack |
|---|---|
| /backend | FastAPI, PostgreSQL, PostGIS, SQLAlchemy 2, Alembic, Pydantic — API, auth, substitutions, budget, audit, SGB XI export |
| /frontend | Next.js, Tailwind, PWA — Mobile worker app |
| /admin | Vite, React, Tailwind, FullCalendar — Desktop admin |
Geospatial & substitution
PostgreSQL/PostGIS powers distance-based substitute suggestions when a shift is unassigned (e.g. worker on sick leave).
- Worker and Client models store a PostGIS point (WGS84): current_location and address_location.
- hausheldPage.geospatialBullet2
- Result: Up to 3 workers with distance (m) and remaining capacity; admin assigns with one click.
GDPR & compliance
| Measure | Implementation |
|---|---|
| Health data encryption | Fernet (AES) for insurance_number and care_level; key via ENCRYPTION_KEY (not in DB). |
| Audit log | Append-only audit_logs: user, action, target, timestamp. Read-only API — no tampering. |
| Soft deletes | Workers, clients, shifts: only deleted_at set; rows kept for audit/legal hold. |
| Data residency | Designed for AWS eu-central-1 (Frankfurt); health data stays in Germany. |
Shift workflow
Shifts follow a strict state machine; GPS and signatures provide verifiable proof of service.
| Status | Meaning |
|---|---|
| Scheduled | Worker assigned; not started. |
| In_Progress | Worker has checked in (GPS + timestamp stored). |
| Completed | Worker has checked out (GPS + client signature); cost set for budget deduction. |
| Unassigned | No worker (e.g. sick leave); admin can use suggest-substitutes and assign. |
| Cancelled | Shift not carried out. |
Scheduled → (check-in) → In_Progress → (check-out + signature) → Completed. GPS-verified check-in/out replaces paper forms for insurers and audits.
API reference
| Area | Endpoints |
|---|---|
| Auth | Auth: POST /auth/dev-login, GET /auth/me |
| Shifts | hausheldPage.apiShifts |
| Workers | hausheldPage.apiWorkers |
| Clients | Clients: GET /clients, budget-status, budget-alerts |
| Billing | Billing: GET /exports/billing?month= (SGB XI CSV) |
| Audit | Audit: GET /audit-logs (Admin, read-only) |