FamilienFeierPlaner

Personen-, Kontakt- und Event-Management-System (Gaesteliste & Zahlungsabgleich).

Architektur

• Frontend — SvelteKit (BFF via adapter-cloudflare, Fallback adapter-node) + shadcn-svelte + Tailwind CSS v4 + Orval (API-Typgenerierung)
• Backend — Node.js (Fastify) REST API + Prisma (ORM/Migrationen) + jose (JWT-Validierung) + AES-256-GCM (Application-Layer-Verschluesselung)
• Datenbank — PostgreSQL mit Gruppen/Haushalte, Composite-Rollen, Event-Planning-Mode, Soft-Delete
• Auth — Keycloak (OAuth2 / PKCE) mit Person-User-Trennung, Composite-Realm-Rollen (app-admin, event-admin, template-admin)

Verzeichnisstruktur

├── shared/design-tokens/tokens.css  Gemeinsame CSS-Custom-Properties (Farben, Schriften, Abstaende)
├── frontend/       SvelteKit-App (BFF via adapter-cloudflare) + shadcn-svelte + Tailwind + Orval
├── backend/        Fastify REST API + Prisma + jose + OpenAPI-Spezifikation
├── keycloak/       Keycloak-Realm-Export + Custom Login-Theme (Design-Tokens-konform)
├── scripts/patterns/  Log-Pattern-Dateien fuer den Integrationstest (docker-test.mjs)
└── docs/           Technische Spezifikationen (Design-Dokument)

Erste Schritte

Voraussetzungen: Docker & Docker Compose

# Umgebungsvariablen aus Vorlage kopieren und ENCRYPTION_KEY anpassen
cp .env.example .env

# Backend-Abhaengigkeiten installieren (fuer lokale TypeScript-Entwicklung)
cd backend && npm install

# Vollen Stack starten
docker compose up --build

Damit werden gestartet:

• PostgreSQL (Port 5432) — relationale Datenbank
• Keycloak (Port 8080, Admin: admin / admin) — Authentifizierung
• Fastify-Backend (Port 3000) — REST API inkl. Swagger-UI (/docs) mit OAuth2-Integration (HTTP/1.1; mit TLS-Zertifikaten in ./certs/ automatisch HTTP/2 + HTTPS)
• Frontend (Port 5173 Dev / Port 8788 wrangler pages dev) — SvelteKit + Tailwind + shadcn-svelte

Keycloak-Provisioning

Beim ersten Backend-Start wird Keycloak automatisch vorkonfiguriert:

1. Realm-Import via --import-realm: Realm familienfeierplaner, Clients (backend-api, frontend-app, swagger-ui) und Realm-Rollen (app-admin, event-admin, template-admin) werden angelegt.
2. Benutzer-Provisioning via Keycloak Admin API: Fuenf Testbenutzer werden mit zufaelligen 12-Zeichen-Passwoertern angelegt und die Passwoerter auf der Konsole ausgegeben.

Alle Benutzer erhalten beim Anlegen in Keycloak automatisch locale=de als User-Locale (gesteuert ueber DEFAULT_USER_LOCALE in backend/src/lib/i18n-config.ts).

Benutzer	Rolle
Max Mustermann	App-Admin
Petra Musterfrau	App-Benutzer
Thomas Koenig	App-Benutzer
Lisa Winter	App-Benutzer
Anna Schmidt	App-Benutzer

Frontend-Entwicklung

Das Frontend ist eine SvelteKit-App mit Tailwind CSS und shadcn-svelte:

cd frontend

# Abhaengigkeiten installieren (nach dem ersten Klonen)
npm install

# TypeScript-Typen aus der OpenAPI-Spezifikation generieren
npm run generate:api

# Dev-Server starten (Port 5173, HMR via Vite)
npm run dev

# Produktions-Build (adapter-cloudflare)
npm run build

# Cloudflare-Pages-Preview (Build + wrangler pages dev, Port 8788)
npm run preview:pages

wrangler pages dev: Fuer den Production-Preview benoetigt wrangler eigene Umgebungsvariablen — siehe .dev.vars.example (Kopie als .dev.vars).

Integrationstest

Ein automatisiertes Skript baut den gesamten Container-Stack, startet ihn und scannt Build-Output sowie Container-Logs auf Fehler und Warnungen. Anschliessend werden Playwright-E2E-Tests ausgefuehrt:

npm run test:integration

Das Skript erkennt automatisch, ob docker oder podman installiert ist. Mit Podman kann auch via Umgebungsvariable explizit gesteuert werden:

CONTAINER_CMD=podman npm run test:integration

Voraussetzung: Docker & Docker Compose (bzw. Podman + podman-compose), laufende Container-Engine.

Fuer reine Backend-Build-Tests (Lint + Kompilieren + Unit-Tests, ohne Container):

npm --prefix backend run test:build

E2E-Tests (Playwright)

Nach dem Health-Check fuehrt npm run test:integration automatisch Playwright-E2E-Tests aus.

Die E2E-Tests koennen auch manuell gestartet werden:

docker compose --profile integration-test run --rm e2e-runner npx playwright test

Health-Check pruefen:

curl http://localhost:3000/health
# {"status":"ok","database":"connected","keycloak":"reachable"}

Fahrplan

Der aktuelle Fortschritt wird in Gitea Milestones getrackt. Einzelne Aufgaben sind als Gitea Issues hinterlegt.

Sicherheit & Betrieb

Details zu Verschluesselung, Authentifizierung, Autorisierung, Audit-Log und Backup: → Authentifizierung & Security → Autorisierungsmatrix → Betrieb & Wartung

Technisches Design

→ docs/design.md

API-Spezifikation

Die gesamte REST-API ist als OpenAPI 3.1-Spezifikation dokumentiert:

→ backend/openapi.yaml

Konventionen

→ AGENTS.md