feat(claude): Add comprehensive project context and development rules

- CLAUDE.md: Complete project context with SSH connection, 49 services, all URLs (including SDK modules), tech stack, and core principles - open-source-policy.md: License whitelist, SBOM workflow, dependency checks - compliance-checklist.md: DSGVO/AI Act checklists, 5-question quick check - debug-framework.md: 6-phase systematic debugging with Breakpilot-specific commands Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-08 23:38:37 -08:00
parent 1e68ccd4d0
commit f28244753f
4 changed files with 853 additions and 0 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,376 @@
+# BreakPilot PWA - Projekt-Kontext für Claude
+
+## SSH-Verbindung (WICHTIG - IMMER ZUERST LESEN)
+
+```bash
+# Verbindung zum Mac Mini im lokalen Netzwerk
+ssh macmini
+
+# Projektverzeichnis
+cd /Users/benjaminadmin/Projekte/breakpilot-pwa
+
+# Oder direkt:
+ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && <befehl>"
+```
+
+**Hostname:** `macmini` (im lokalen Netzwerk via Bonjour)
+**User:** `benjaminadmin`
+**Projekt:** `/Users/benjaminadmin/Projekte/breakpilot-pwa`
+
+---
+
+## Kernprinzipien (IMMER BEACHTEN)
+
+### 1. Open Source Policy
+- **NUR Open Source mit kommerziell nutzbarer Lizenz verwenden**
+- Erlaubte Lizenzen: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL
+- **VERBOTEN:** GPL (außer LGPL), AGPL, proprietäre Software, "free for non-commercial use"
+- **Bei jeder neuen Dependency:** SBOM aktualisieren unter https://macmini:3002/infrastructure/sbom
+
+### 2. Testing & Dokumentation
+- **Tests sind Pflicht:** Unit Tests, Integration Tests für jede Änderung
+- **Dokumentation aktualisieren:** https://macmini:3002/development/docs (MKDocs)
+- Siehe `@.claude/rules/testing.md` und `@.claude/rules/documentation.md`
+
+### 3. Architektur & Visualisierung aktualisieren
+Nach größeren Änderungen diese Dashboards aktualisieren:
+- **Architektur:** https://macmini:3002/architecture
+- **Screenflows:** https://macmini:3002/development/screen-flow
+- **Dashboard:** https://macmini:3002/dashboard
+- **Security Tools:** https://macmini:3002/infrastructure/security
+
+### 4. CI/CD Pipeline
+Alle Security-Tools müssen nach der Pipeline durchlaufen:
+- Trivy (Container-Scanning)
+- Semgrep (SAST)
+- Gitleaks (Secret-Detection)
+- SBOM-Generierung
+
+---
+
+## Projektübersicht
+
+**Projektname:** BreakPilot PWA
+**Typ:** DSGVO-konforme EdTech-Plattform für den DACH-Raum
+**Architektur:** Microservices mit Docker Compose
+**Plattform:** Mac Mini M2 (Apple Silicon / ARM64)
+
+---
+
+## Haupt-URLs (HTTPS via Nginx)
+
+| URL | Service | Beschreibung |
+|-----|---------|--------------|
+| https://macmini/ | Studio v2 | Lehrer-/Schüler-Interface |
+| https://macmini:3000/ | Website | Öffentliche Website |
+| https://macmini:3002/ | Admin v2 | **Admin-Dashboard (Hauptzugang)** |
+| https://macmini:8000/ | Backend API | FastAPI Backend |
+| https://macmini:8086/ | Klausur Service | Prüfungs-/Klausurservice |
+| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
+| wss://macmini:8091/ | Voice Service | Spracheingabe WebSocket |
+
+### AI Compliance SDK (DSGVO-Tools)
+
+| URL | Modul | Beschreibung |
+|-----|-------|--------------|
+| https://macmini:3002/sdk | SDK Admin | Haupt-SDK mit allen Modulen |
+| https://macmini:3002/sdk/tom | TOM | Technisch-Organisatorische Maßnahmen |
+| https://macmini:3002/sdk/dsfa | DSFA | Datenschutz-Folgenabschätzung |
+| https://macmini:3002/sdk/vvt | VVT | Verzeichnis von Verarbeitungstätigkeiten |
+| https://macmini:3002/sdk/loeschfristen | Löschfristen | Löschfristen-Verwaltung |
+| https://macmini:3002/developers | Developer Portal | API-Dokumentation für Kunden |
+| https://macmini:8093/ | SDK API | Backend-API für SDK |
+
+### Interne Dienste
+
+| URL | Service |
+|-----|---------|
+| http://macmini:8200/ | Vault UI (Secrets) |
+| http://macmini:8025/ | Mailpit (E-Mail Dev) |
+| http://macmini:9001/ | MinIO Console (S3) |
+| http://macmini:3003/ | Gitea (Git-Server) |
+| http://macmini:8090/ | Woodpecker CI |
+| http://macmini:8089/ | Camunda (BPMN) |
+| http://macmini:8009/ | MkDocs (Projekt-Doku) |
+
+### Studio URLs
+
+| URL | Beschreibung |
+|-----|--------------|
+| https://macmini/korrektur | Lehrer-Korrekturplattform |
+| https://macmini:8000/app | Dashboard (alte Version) |
+
+---
+| http://macmini:8200/ | Vault UI (Secrets) |
+| http://macmini:8025/ | Mailpit (E-Mail Dev) |
+| http://macmini:9001/ | MinIO Console (S3) |
+| http://macmini:3003/ | Gitea (Git-Server) |
+| http://macmini:8090/ | Woodpecker CI |
+| http://macmini:8089/ | Camunda (BPMN) |
+
+---
+
+## Services (49 Container)
+
+### Kern-Applikationen
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `studio-v2` | Next.js | 443 | Lehrer-/Schüler-Studio |
+| `admin-v2` | Next.js | 3002 | Admin-Dashboard |
+| `website` | Next.js | 3000 | Öffentliche Website |
+| `backend` | Python/FastAPI | 8000 | API Backend |
+| `consent-service` | Go/Gin | 8081 | Consent-Management |
+
+### Bildungs-Services
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `klausur-service` | Python/FastAPI | 8086 | Prüfungen, OCR, RAG |
+| `school-service` | Python | 8082 | Schulverwaltung |
+| `edu-search-service` | Python | 8088 | Bildungssuche |
+| `breakpilot-drive` | Node.js | 8087 | Dateiablage (IPFS) |
+| `geo-service` | Python | 8084 | Geo-Daten (PostGIS) |
+| `voice-service` | Python | 8091 | Spracheingabe |
+
+### KI & Compliance
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `ai-compliance-sdk` | Python | 8093 | DSGVO-konforme KI-Nutzung |
+| `embedding-service` | Python | 8083 | Text-Embeddings |
+| `paddleocr-service` | Python | - | OCR für Dokumente |
+| `transcription-worker` | Python | - | Audio-Transkription |
+
+### Kommunikation
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `jitsi-web` | Jitsi | 8443 | Videokonferenzen |
+| `jitsi-xmpp` | Prosody | - | XMPP Server |
+| `jitsi-jicofo` | Jicofo | - | Konferenz-Fokus |
+| `jitsi-jvb` | JVB | 8080 | Video Bridge |
+| `jibri` | Jibri | - | Aufnahme/Streaming |
+| `synapse` | Matrix | 8008 | Chat-Server |
+
+### Datenbanken & Storage
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `postgres` | PostGIS 16 | 5432 | Hauptdatenbank |
+| `valkey` | Valkey 8 | 6379 | Session-Cache (Redis-Fork) |
+| `qdrant` | Qdrant | 6333/6334 | Vektordatenbank |
+| `minio` | MinIO | 9000/9001 | S3-kompatibler Storage |
+
+### Infrastructure & DevOps
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `nginx` | Nginx | 80/443 | Reverse Proxy + TLS |
+| `vault` | HashiCorp Vault | 8200 | Secrets Management |
+| `vault-agent` | Vault | - | Zertifikatserneuerung |
+| `gitea` | Gitea | 3003 | Git-Server |
+| `woodpecker-server` | Woodpecker | 8090 | CI/CD Server |
+| `woodpecker-agent` | Woodpecker | - | CI/CD Agent |
+| `night-scheduler` | Python/FastAPI | 8096 | Auto-Shutdown/Startup |
+| `mailpit` | Mailpit | 8025/1025 | E-Mail (Dev) |
+
+### ERP & Billing
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `erpnext-frontend` | ERPNext | 8009 | ERP Frontend |
+| `erpnext-backend` | ERPNext | - | ERP Backend |
+| `erpnext-db` | MariaDB | - | ERP Datenbank |
+| `billing-service` | Python | - | Abrechnungsservice |
+
+### DSMS (Data Sharing)
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `dsms-node` | Node.js | 4001/5001 | IPFS Node |
+| `dsms-gateway` | Node.js | 8085 | IPFS Gateway |
+
+### Prozesse
+
+| Service | Tech | Port | Beschreibung |
+|---------|------|------|--------------|
+| `camunda` | Camunda | 8089 | BPMN Engine |
+
+---
+
+## Tech-Stack nach Sprache
+
+### Go
+- `consent-service`: Gin, GORM, JWT
+
+### Python
+- `backend`: FastAPI, SQLAlchemy, Pydantic
+- `klausur-service`: FastAPI, PaddleOCR, RAG
+- `ai-compliance-sdk`: FastAPI, Langfuse
+- `embedding-service`: FastAPI, Sentence-Transformers
+- `voice-service`: FastAPI, Whisper
+- `geo-service`: FastAPI, PostGIS
+- `school-service`: FastAPI
+- `night-scheduler`: FastAPI
+
+### TypeScript/Next.js
+- `studio-v2`: Next.js 14, React, TailwindCSS
+- `admin-v2`: Next.js 14, React, TailwindCSS, shadcn/ui
+- `website`: Next.js 14
+
+### Node.js
+- `breakpilot-drive`: Express, IPFS
+- `dsms-node`: IPFS
+- `dsms-gateway`: Express
+
+---
+
+## Verzeichnisstruktur
+
+```
+breakpilot-pwa/
+├── .claude/                  # Claude-Konfiguration
+│   ├── CLAUDE.md            # Diese Datei
+│   ├── rules/               # Automatische Regeln
+│   │   ├── testing.md
+│   │   ├── documentation.md
+│   │   └── night-scheduler.md
+│   └── settings.json
+├── admin-v2/                 # Admin Dashboard (Next.js)
+├── studio-v2/                # Lehrer-/Schüler-Studio (Next.js)
+├── website/                  # Öffentliche Website (Next.js)
+├── backend/                  # Python Backend (FastAPI)
+├── consent-service/          # Go Consent Service
+├── klausur-service/          # Klausur/OCR Service
+├── ai-compliance-sdk/        # KI-Compliance SDK
+├── voice-service/            # Spracheingabe
+├── geo-service/              # Geo-Daten
+├── school-service/           # Schulverwaltung
+├── edu-search-service/       # Bildungssuche
+├── breakpilot-drive/         # Dateiablage
+├── night-scheduler/          # Auto-Shutdown
+├── nginx/                    # Reverse Proxy Config
+├── vault/                    # Vault Config
+├── docs-src/                 # MKDocs Quellen
+├── docs-site/                # MKDocs Build
+├── docker-compose.yml        # Haupt-Docker-Config
+└── mkdocs.yml                # MKDocs Config
+```
+
+---
+
+## Dokumentation (MKDocs)
+
+**Live-URL:** https://macmini:3002/development/docs
+**Quellen:** `/docs-src/`
+**Build:** `/docs-site/`
+**Config:** `mkdocs.yml`
+
+### Dokumentation bearbeiten
+
+```bash
+# MKDocs lokal starten (Live-Reload)
+cd /Users/benjaminadmin/Projekte/breakpilot-pwa
+mkdocs serve -a 0.0.0.0:8008
+
+# Build
+mkdocs build
+```
+
+### Struktur
+
+- `docs-src/index.md` - Startseite
+- `docs-src/architecture/` - Architektur-Docs
+- `docs-src/services/` - Service-Dokumentation
+- `docs-src/api/` - API-Dokumentation
+- `docs-src/development/` - Entwickler-Guides
+
+---
+
+## Häufige Befehle
+
+### Docker
+
+```bash
+# Alle Services starten
+docker compose up -d
+
+# Einzelnen Service neu bauen
+docker compose build --no-cache <service-name>
+docker compose up -d <service-name>
+
+# Logs anzeigen
+docker compose logs -f <service-name>
+
+# Status aller Container
+docker compose ps
+```
+
+### Tests
+
+```bash
+# Go Tests (Consent Service)
+cd consent-service && go test -v ./...
+
+# Python Tests
+cd backend && source venv/bin/activate && pytest -v
+
+# Mit Coverage
+pytest --cov=. --cov-report=html
+```
+
+### Git (via Gitea)
+
+```bash
+# Remote ist localhost weil Gitea im Container läuft
+git remote -v
+# origin  http://localhost:3003/pilotadmin/breakpilot-pwa.git
+```
+
+---
+
+## Rollen & Berechtigungen
+
+| Rolle | Beschreibung |
+|-------|--------------|
+| `user` | Normaler Benutzer (Schüler/Lehrer) |
+| `admin` | Administrator |
+| `data_protection_officer` | Datenschutzbeauftragter |
+| `school_admin` | Schuladministrator |
+
+---
+
+## Compliance & Sicherheit
+
+### DSGVO
+- Consent-Management via `consent-service`
+- Datenexport-Funktionen
+- Löschkonzept implementiert
+
+### AI Act
+- `ai-compliance-sdk` für konforme KI-Nutzung
+- Risikobewertung für KI-Funktionen
+- Audit-Logging
+
+### BSI
+- BSI-TR-03161 Dokumentation vorhanden
+- Security-Scanning in CI/CD
+
+---
+
+## Sensitive Dateien
+
+**NIEMALS ändern oder committen:**
+- `.env`, `.env.local`, `.env.backup`
+- `secrets/`
+- Vault-Tokens
+- SSL-Zertifikate
+
+---
+
+## Ansprechpartner
+
+- **Git-Server:** http://macmini:3003 (Gitea)
+- **CI/CD:** http://macmini:8090 (Woodpecker)
+- **Issue-Tracker:** Gitea Issues
--- a/.claude/rules/compliance-checklist.md
+++ b/.claude/rules/compliance-checklist.md
@@ -0,0 +1,141 @@
+# Compliance-Checkliste
+
+## Wann diese Checkliste anwenden?
+
+**AUTOMATISCH bei:**
+- Neuen Features mit Nutzerdaten
+- Änderungen an Datenflüssen
+- KI/ML-Funktionen
+- Neuen API-Endpoints
+- Datenbankschema-Änderungen
+
+---
+
+## 1. DSGVO-Check (Datenschutz-Grundverordnung)
+
+### Rechtsgrundlage klären
+
+| Rechtsgrundlage | Wann verwenden |
+|-----------------|----------------|
+| **Einwilligung (Art. 6 Abs. 1a)** | Optionale Features, Marketing, Analytics |
+| **Vertragserfüllung (Art. 6 Abs. 1b)** | Kernfunktionen der Plattform |
+| **Berechtigtes Interesse (Art. 6 Abs. 1f)** | Sicherheit, Betrugsprävention |
+| **Rechtliche Verpflichtung (Art. 6 Abs. 1c)** | Aufbewahrungspflichten |
+
+### Datenminimierung
+
+- [ ] Werden nur notwendige Daten erhoben?
+- [ ] Gibt es Felder, die optional sein könnten?
+- [ ] Werden Daten nach Zweckerfüllung gelöscht?
+
+### Besondere Kategorien (Art. 9)
+
+**ACHTUNG bei:**
+- Gesundheitsdaten (Krankheitstage, Atteste)
+- Biometrische Daten (Gesichtserkennung, Stimme)
+- Religiöse Überzeugungen
+- Politische Meinungen
+
+→ **Explizite Einwilligung erforderlich!**
+
+### Minderjährige (Art. 8)
+
+**Breakpilot-spezifisch:**
+- Unter 16 Jahren: Einwilligung der Eltern
+- Altersverifikation implementieren
+- Kindgerechte Datenschutzerklärung
+
+### Betroffenenrechte sicherstellen
+
+- [ ] **Auskunft (Art. 15):** Kann der Nutzer seine Daten einsehen?
+- [ ] **Berichtigung (Art. 16):** Kann der Nutzer Daten korrigieren?
+- [ ] **Löschung (Art. 17):** Kann der Nutzer Löschung beantragen?
+- [ ] **Datenportabilität (Art. 20):** Export in maschinenlesbarem Format?
+
+---
+
+## 2. AI Act Check (KI-Verordnung)
+
+### Risikokategorie bestimmen
+
+| Kategorie | Beispiele | Anforderungen |
+|-----------|-----------|---------------|
+| **Unakzeptabel** | Social Scoring, Manipulation | ❌ VERBOTEN |
+| **Hochrisiko** | Bildungszugang, Prüfungsbewertung | Strenge Auflagen |
+| **Begrenzt** | Chatbots, Empfehlungen | Transparenzpflicht |
+| **Minimal** | Spam-Filter, Autokorrektur | Keine Auflagen |
+
+### Breakpilot KI-Features prüfen
+
+| Feature | Risiko | Maßnahmen |
+|---------|--------|-----------|
+| Klausur-OCR | Begrenzt | Transparenz, Human-in-Loop |
+| KI-Korrekturvorschläge | Hochrisiko | Audit-Log, Erklärbarkeit |
+| Lernempfehlungen | Begrenzt | Transparenz |
+| Spracherkennung | Begrenzt | Consent, Transparenz |
+
+### Hochrisiko-KI Anforderungen
+
+Wenn Hochrisiko:
+- [ ] Risikomanagementsystem dokumentiert
+- [ ] Qualität der Trainingsdaten sichergestellt
+- [ ] Technische Dokumentation vorhanden
+- [ ] Audit-Logging aktiviert
+- [ ] Human Oversight möglich
+- [ ] Genauigkeit/Robustheit getestet
+
+---
+
+## 3. Technische Maßnahmen (TOM)
+
+### Verschlüsselung
+
+- [ ] **Transit:** TLS 1.3 für alle Verbindungen
+- [ ] **Rest:** Datenbank-Verschlüsselung
+- [ ] **Secrets:** Vault für Credentials
+
+### Zugriffskontrollen
+
+- [ ] RBAC implementiert
+- [ ] Least Privilege Prinzip
+- [ ] Session-Timeouts
+
+### Audit-Logging
+
+```python
+# Beispiel: Audit-Event loggen
+audit_log.info({
+    "action": "data_export",
+    "user_id": user.id,
+    "timestamp": datetime.utcnow(),
+    "data_categories": ["grades", "personal"],
+    "legal_basis": "Art. 20 DSGVO"
+})
+```
+
+---
+
+## 4. Dokumentationspflichten
+
+### Bei neuen Features aktualisieren
+
+| Dokument | URL | Wann aktualisieren |
+|----------|-----|-------------------|
+| VVT | https://macmini:3002/sdk/vvt | Neue Verarbeitung |
+| TOM | https://macmini:3002/sdk/tom | Neue Schutzmaßnahme |
+| DSFA | https://macmini:3002/sdk/dsfa | Hochrisiko-Verarbeitung |
+| Löschfristen | https://macmini:3002/sdk/loeschfristen | Neue Datenkategorie |
+
+---
+
+## 5. Schnell-Check (5 Fragen)
+
+Vor jedem Feature diese 5 Fragen beantworten:
+
+1. **WER** sind die Betroffenen? (Schüler, Lehrer, Eltern)
+2. **WAS** für Daten werden verarbeitet?
+3. **WARUM** werden sie verarbeitet? (Rechtsgrundlage)
+4. **WIE LANGE** werden sie gespeichert?
+5. **WER** hat Zugriff?
+
+Können alle 5 Fragen beantwortet werden? → Feature ist dokumentierbar.
--- a/.claude/rules/open-source-policy.md
+++ b/.claude/rules/open-source-policy.md
@@ -0,0 +1,99 @@
+# Open Source Policy
+
+## Lizenzprüfung (AUTOMATISCH BEI JEDER DEPENDENCY)
+
+### Erlaubte Lizenzen ✅
+
+| Lizenz | Typ | Kommerziell OK |
+|--------|-----|----------------|
+| MIT | Permissive | ✅ |
+| Apache-2.0 | Permissive | ✅ |
+| BSD-2-Clause | Permissive | ✅ |
+| BSD-3-Clause | Permissive | ✅ |
+| ISC | Permissive | ✅ |
+| MPL-2.0 | Weak Copyleft | ✅ |
+| LGPL-2.1 / LGPL-3.0 | Weak Copyleft | ✅ (nur linking) |
+| CC0-1.0 | Public Domain | ✅ |
+| Unlicense | Public Domain | ✅ |
+
+### Verbotene Lizenzen ❌
+
+| Lizenz | Grund |
+|--------|-------|
+| GPL-2.0 / GPL-3.0 | Copyleft - infiziert Projekt |
+| AGPL-3.0 | Network Copyleft - SaaS-Killer |
+| SSPL | Server Side Public License |
+| BSL | Business Source License |
+| "Non-Commercial" | Keine kommerzielle Nutzung |
+| "Educational Only" | Nur für Bildung |
+| Proprietary | Keine OSS |
+
+---
+
+## Workflow bei neuer Dependency
+
+### 1. Vor dem Hinzufügen prüfen
+
+```bash
+# NPM Package
+npm view <package> license
+
+# Python Package
+pip show <package> | grep License
+
+# Go Module
+go-licenses check <module>
+```
+
+### 2. Bei Unklarheit
+
+- README.md des Projekts lesen
+- LICENSE-Datei prüfen
+- SPDX-Identifier suchen
+- Im Zweifel: **NICHT verwenden**
+
+### 3. Nach dem Hinzufügen
+
+**SBOM aktualisieren:** https://macmini:3002/infrastructure/sbom
+
+```bash
+# SBOM generieren
+cd /Users/benjaminadmin/Projekte/breakpilot-pwa
+
+# Python
+pip-licenses --format=json > sbom/python-licenses.json
+
+# Node.js
+npx license-checker --json > sbom/node-licenses.json
+
+# Go
+go-licenses csv ./... > sbom/go-licenses.csv
+```
+
+---
+
+## Grenzfälle
+
+### Dual-Licensed Packages
+- Wenn MIT **oder** GPL angeboten wird → MIT wählen
+- Dokumentieren welche Lizenz gewählt wurde
+
+### Transitive Dependencies
+- Auch indirekte Abhängigkeiten prüfen
+- `npm ls`, `pip-tree`, `go mod graph`
+
+### Fonts & Assets
+- Google Fonts: ✅ (OFL)
+- Font Awesome Free: ✅ (CC BY 4.0 / OFL / MIT)
+- Icons8: ❌ (Attribution required, kompliziert)
+
+---
+
+## Checkliste bei PR/Commit
+
+Wenn neue Dependencies hinzugefügt wurden:
+
+- [ ] Lizenz ist in der Whitelist
+- [ ] SBOM wurde aktualisiert
+- [ ] Keine GPL/AGPL-Abhängigkeiten eingeschleppt
+- [ ] Bei Dual-License: MIT/Apache gewählt
--- a/.claude/skills/debug-framework.md
+++ b/.claude/skills/debug-framework.md
@@ -0,0 +1,237 @@
+# Systematisches Debug-Framework
+
+## Trigger
+
+Dieses Skill aktivieren bei:
+- Fehlermeldungen / Exceptions
+- Unerwartetes Verhalten
+- Performance-Probleme
+- "Es funktioniert nicht"
+
+---
+
+## Phase 1: Reproduzieren (5 min max)
+
+### Ziel: Bug in einen Test verwandeln
+
+```bash
+# 1. Exakte Schritte dokumentieren
+# 2. Fehlermeldung/Symptom notieren
+# 3. Umgebung identifizieren
+```
+
+**Fragen:**
+- [ ] Ist der Bug reproduzierbar?
+- [ ] Tritt er nur in bestimmten Umgebungen auf?
+- [ ] Seit wann tritt er auf? (letzter Deploy?)
+
+### Breakpilot-spezifisch: Welcher Service?
+
+```bash
+# Container-Status prüfen
+ssh macmini "docker compose ps | grep -E '(Exit|unhealthy)'"
+
+# Logs der letzten 5 Minuten
+ssh macmini "docker compose logs --since 5m <service-name>"
+```
+
+| Symptom | Wahrscheinlicher Service |
+|---------|-------------------------|
+| Login fehlgeschlagen | consent-service, backend |
+| 502 Bad Gateway | nginx, upstream-service |
+| Langsame Suche | qdrant, embedding-service |
+| Upload-Fehler | minio, backend |
+| OCR-Fehler | paddleocr-service, klausur-service |
+
+---
+
+## Phase 2: Hypothesen bilden (5 min max)
+
+### 3-5 mögliche Ursachen auflisten
+
+| # | Hypothese | Wahrscheinlichkeit | Test |
+|---|-----------|-------------------|------|
+| 1 | | Hoch/Mittel/Niedrig | |
+| 2 | | | |
+| 3 | | | |
+
+### Häufige Ursachen bei Breakpilot
+
+**Container/Docker:**
+- Container nicht gestartet
+- Volume-Mount-Problem
+- Netzwerk zwischen Containern unterbrochen
+- Resource-Limits erreicht
+
+**Datenbank:**
+- Connection Pool erschöpft
+- Migration nicht ausgeführt
+- Deadlock
+
+**API/Backend:**
+- JWT abgelaufen
+- CORS-Fehler
+- Rate-Limit erreicht
+- Falscher Content-Type
+
+**Frontend:**
+- Cache-Problem (Safari!)
+- Build nicht aktualisiert
+- Umgebungsvariable fehlt
+
+---
+
+## Phase 3: Systematisch eliminieren (10 min max)
+
+### Reihenfolge: Schnellste Tests zuerst
+
+```bash
+# 1. Ist der Service überhaupt erreichbar?
+curl -s https://macmini:8000/health | jq
+
+# 2. Container-Logs auf Fehler prüfen
+ssh macmini "docker compose logs --tail 50 <service> 2>&1 | grep -iE '(error|exception|failed|traceback)'"
+
+# 3. Datenbank-Verbindung testen
+ssh macmini "docker exec breakpilot-pwa-postgres pg_isready"
+
+# 4. Redis/Valkey erreichbar?
+ssh macmini "docker exec breakpilot-pwa-valkey valkey-cli ping"
+```
+
+### Hypothese testen
+
+Für jede Hypothese:
+1. **Test definieren** (wie prüfen wir das?)
+2. **Test ausführen**
+3. **Ergebnis:** Bestätigt ✅ / Widerlegt ❌
+
+---
+
+## Phase 4: Root Cause identifizieren
+
+### Nicht das Symptom behandeln!
+
+**Schlecht:** "Ich starte den Container neu"
+**Gut:** "Der Container crashed wegen OOM → Memory-Limit erhöhen"
+
+### 5-Why-Methode
+
+```
+Problem: API gibt 500 zurück
+↓ Warum?
+Datenbank-Query failed
+↓ Warum?
+Connection Pool erschöpft
+↓ Warum?
+Connections werden nicht freigegeben
+↓ Warum?
+Exception vor connection.close()
+↓ Warum?
+Fehlendes try/finally
+→ ROOT CAUSE: Fehlendes Resource-Cleanup
+```
+
+---
+
+## Phase 5: Fix implementieren
+
+### Checkliste vor dem Fix
+
+- [ ] Root Cause verstanden (nicht nur Symptom)
+- [ ] Fix adressiert Root Cause
+- [ ] Keine Seiteneffekte erwartet
+- [ ] Test geschrieben, der Regression verhindert
+
+### Fix-Template
+
+```python
+# VORHER: Bug
+def fetch_data():
+    conn = get_connection()
+    result = conn.query(...)  # Exception hier → Leak!
+    conn.close()
+    return result
+
+# NACHHER: Fix mit Erklärung
+def fetch_data():
+    """Fetch data with proper connection handling.
+    
+    Fixed: Connection leak when query raises exception.
+    See: https://macmini:3003/.../issues/123
+    """
+    conn = get_connection()
+    try:
+        result = conn.query(...)
+        return result
+    finally:
+        conn.close()  # Immer ausgeführt
+```
+
+---
+
+## Phase 6: Regression verhindern
+
+### Test schreiben
+
+```python
+def test_connection_released_on_error():
+    """Regression test for connection leak bug.
+    
+    Issue: #123
+    Root cause: Missing finally block in fetch_data()
+    """
+    initial_connections = get_pool_size()
+    
+    with pytest.raises(DatabaseError):
+        fetch_data_with_bad_query()
+    
+    # Connection should be returned to pool
+    assert get_pool_size() == initial_connections
+```
+
+### Dokumentieren
+
+```bash
+# Was haben wir gelernt?
+# → docs-src/development/debugging-notes.md ergänzen
+```
+
+---
+
+## Quick Reference: Breakpilot Debug Commands
+
+```bash
+# Alle Container-Status
+ssh macmini "docker compose ps"
+
+# Logs eines Services (live)
+ssh macmini "docker compose logs -f <service>"
+
+# In Container einloggen
+ssh macmini "docker exec -it breakpilot-pwa-<service> sh"
+
+# PostgreSQL Query
+ssh macmini "docker exec breakpilot-pwa-postgres psql -U breakpilot -d breakpilot_db -c 'SELECT 1'"
+
+# Netzwerk-Debug
+ssh macmini "docker exec breakpilot-pwa-backend curl -s http://consent-service:8081/health"
+
+# Resource-Nutzung
+ssh macmini "docker stats --no-stream"
+
+# Vault-Status
+ssh macmini "docker exec breakpilot-pwa-vault vault status"
+```
+
+---
+
+## Anti-Patterns vermeiden
+
+| ❌ Nicht machen | ✅ Stattdessen |
+|-----------------|----------------|
+| Random Code ändern | Hypothese bilden, dann testen |
+| console.log überall | Gezielt an verdächtigen Stellen |
+| Container neustarten und hoffen | Root Cause finden |
+| Stundenlang alleine debuggen | Nach 30 min Hilfe holen |
+| Fix ohne Test | Immer Regression-Test schreiben |