Versicherungsplattform

Mandantenfähige, White-Label-fähige Plattform für Versicherungsmakler. Alle Clients (Backoffice, Maklerportal, Kundenportal, Mobile App) konsumieren dieselbe REST-API; Fachlogik existiert ausschließlich im Backend.

Aktueller Stand: Sprint 0 — technisches Fundament. Fachliche Module folgen ab Sprint 1.

Repositorystruktur

Verzeichnis	Inhalt	Stand
backend/	FastAPI, SQLAlchemy 2, Alembic — Modular Monolith	Sprint 0
ai-service/	eigenständiger KI-Dienst (OCR, RAG, Analyse)	ab Sprint 6
frontend-streamlit/	Makler-Backoffice	geplant
frontend-web/	Makler- und Kundenportal (Next.js)	geplant
mobile/	Flutter-App	geplant
shared/	OpenAPI-Spezifikationen, generierte Clients	Sprint 0
infrastructure/	Docker Compose, Traefik-Anbindung	Sprint 0
database/	Rollen-Bootstrap, Seeds	Sprint 0
docs/	ADRs, Architektur, Feature-Spezifikationen	Sprint 0
scripts/	Entwicklungs- und Betriebsskripte	Sprint 0

Schnellstart

1. Voraussetzungen

• Git
• Docker-CLI mit erreichbarem Daemon (lokal oder entfernt, siehe ADR-0006)
• Optional für Arbeit außerhalb der Container: Python 3.12 (py -3.12)

2. Konfiguration

Copy-Item .env.example .env
# Passwörter in .env setzen — die Datei ist per .gitignore ausgeschlossen

3. Starten

Zwei Eigenheiten von Docker Compose, die hier zusammenkommen:

• Das Dev-Overlay wird nur bei der automatischen Dateisuche geladen — sobald -f angegeben ist, nicht mehr.
• .env wird im Projektverzeichnis gesucht, also im Verzeichnis der ersten Compose-Datei. Da unsere .env im Repo-Wurzelverzeichnis liegt, muss sie mit --env-file benannt werden.

Lokal, ohne Traefik:

cd infrastructure/compose
docker compose --env-file ../../.env up -d --build
curl http://localhost:8000/health/ready

Auf Development-, Staging- und Produktionsservern — hinter der vorhandenen Traefik-Instanz, ohne Dev-Overlay. Traefik läuft als eigener PVE-Container mit File-Provider, das Routing wird daher in einem zweiten Schritt ausgerollt:

cd infrastructure/compose
docker compose --env-file ../../.env -f docker-compose.yml -f docker-compose.traefik.yml up -d
cd ../..
./scripts/deploy-traefik-config.sh

Voraussetzung sind die TRAEFIK_*- und BACKEND_BIND_ADDRESS-Werte in .env sowie eine PVE-Firewallregel, die den Backend-Port ausschließlich für die Traefik-IP freigibt. Beides ist in infrastructure/traefik/README.md beschrieben — die Firewallregel ist nicht optional.

Erwartete Antwort:

{"status":"up","version":"0.1.0","environment":"local","checks":{"postgresql":"up","redis":"up"}}

API-Dokumentation: http://localhost:8000/docs (in Produktion abgeschaltet).

4. Entwicklung ohne Container

cd backend
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -e . --group dev

py -m pytest -m "unit or api"   # ohne Infrastruktur lauffähig
py -m ruff check src tests scripts
py -m black --check src tests scripts
py -m mypy
lint-imports

Arbeitsweise

• Ein Feature pro Increment. Nach jedem abgeschlossenen Feature bleibt die Plattform lauffähig.
• Jede strukturelle Entscheidung wird als ADR dokumentiert (docs/adr/), inklusive der verworfenen Alternativen.
• API vor Implementierung: Schema und Route entstehen zuerst, siehe ADR-0004.
• Conventional Commits, Semantic Versioning.
• Direkte Commits auf main/master sind per Pre-Commit-Hook blockiert — Arbeit erfolgt auf Feature-Branches.

pre-commit install --install-hooks
pre-commit install --hook-type commit-msg

Dokumentation

Dokument	Inhalt
Systemübersicht	Analyse, Systemschnitt, Schichten, Mandantenfähigkeit, Identität, Verzeichnisstruktur
API-Konventionen	Fehlerformat, Pagination, Idempotenz, Versionierung, Mandantenkontext
Risikoregister	offene und geschlossene Risiken mit Status
Teststrategie	Testebenen, Werkzeuge, Abnahmekriterien
Roadmap	Reihenfolge der Increments und deren Begründung
Feature-Spezifikationen	je Feature: Ziel, Story, Akzeptanzkriterien, Datenmodell, API, Tests
ADRs	Architekturentscheidungen samt verworfener Alternativen

Arbeitsteilung: Die Architekturdokumente beschreiben, was gilt. Die ADRs begründen, warum — und was aus welchem Grund verworfen wurde.

Architektur in Kürze

Thema	Entscheidung	ADR
Systemschnitt	Modular Monolith, AI-Service separat	0001
Mandantentrennung	Shared Schema + PostgreSQL RLS	0002
Authentifizierung	self-hosted OIDC-Broker, Autorisierung im Backend	0003
API-Vertrag	OpenAPI Contract-Enforced	0004
Laufzeit	Python 3.12	0005
Entwicklungsumgebung	entfernter Docker-Daemon	0006
Reverse Proxy	Traefik, kein anwendungsinternes Nginx	0007