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.
Challenge
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.
Approach
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 with sidebar-only navigation: calendar, workers, clients, Map page (heatmap + worker pins, Mapbox + Deck.gl), Recharts analytics, 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.
- Backend: Single source of truth. FastAPI, SQLAlchemy 2 (async), PostgreSQL + PostGIS, Alembic. Enforces RBAC, encrypts health data, writes to the audit log; geo heatmap and dashboard stats APIs.
- Mobile: Next.js PWA (German UI). Schedule, check-in/out, signature pad, client list for assigned shifts.
- Admin: Vite + React. Dashboard (KPIs + Recharts analytics), calendar (FullCalendar), workers & sick leave, clients & budget alerts, Map (heatmap + worker pins, Mapbox + Deck.gl), billing export, audit log, substitute assignment. Navigation via sidebar only.
Data flow is unidirectional: frontends only call the API; no direct DB access from the client.
Result
Paper-based planning was replaced with a mobile-first workflow: GPS-verified check-in/out, digital signatures, real-time coordination, and audit-ready proof of service. Admins get visibility via dashboards, maps, and alerts — so the team spends less time on bureaucracy and more time on care.
Technical details
Features
- Mobile PWA: Workers see their schedule, check in/out with GPS, capture client signatures (Leistungsnachweis).
- Admin dashboard: Calendar, workers, clients, map (heatmap + worker pins), billing, audit log — all via sidebar; dashboard shows KPIs and premium analytics (Recharts).
- Geo map: Map page: shift-density heatmap and worker locations (Mapbox + Deck.gl); data from demo seed.
- 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.
Tech stack
| Path | Stack |
|---|---|
| /backend | FastAPI, PostgreSQL, PostGIS, SQLAlchemy 2, Alembic, Pydantic — API, auth, geo heatmap, dashboard stats, substitutions, budget, audit, SGB XI export |
| /frontend | Next.js, Tailwind, PWA — Mobile worker app |
| /admin | Vite, React, Tailwind, FullCalendar, Recharts, Mapbox, Deck.gl — Desktop admin; premium analytics and map |
Geospatial & substitution
PostgreSQL/PostGIS powers distance-based substitute suggestions when a shift is unassigned (e.g. worker on sick leave). Admin Map uses Geo API (v1) for heatmap and worker pins.
- Worker and Client models store a PostGIS point (WGS84): current_location and address_location.
- Endpoint: GET /shifts/{id}/suggest-substitutes (Admin only). Ranks candidates by ST_Distance (client ↔ worker), excludes overlapping shifts and workers over weekly contract_hours.
- Result: Up to 3 workers with distance (m) and remaining capacity; admin assigns with one click.
- GET /api/v1/geo/heatmap — GeoJSON FeatureCollection for shift-density heatmap; workers with current_location shown as pins via GET /workers.
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 |
| Geo (v1) | Geo (v1): GET /api/v1/geo/heatmap (GeoJSON for map heatmap) |
| Stats (v1) | Stats (v1): GET /api/v1/stats/dashboard-summary (weekly trends, city distribution, KPIs, top workers) |
| Shifts | Shifts: GET/PATCH /shifts, check-in, check-out, GET /shifts/{id}/suggest-substitutes |
| Workers | Workers: GET /workers, POST /workers/{id}/sick-leave |
| 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) |