breakpilot-pwa/.claude/CLAUDE.md

BreakPilot PWA - Projekt-Kontext für Claude

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup

Gerät	Rolle	Aufgaben
MacBook	Client	Claude Terminal, Browser (Frontend-Tests)
Mac Mini	Server	Docker, alle Services, Code-Ausführung, Tests, Git

WICHTIG: Die Entwicklung findet vollständig auf dem Mac Mini statt!

• Alle Befehle (docker, git, tests, builds) per SSH auf dem Mac Mini ausführen
• Das MacBook dient nur als Terminal und Browser für Frontend-Tests
• Dateien werden auf dem Mac Mini bearbeitet, nicht lokal auf dem MacBook

SSH-Verbindung

# Verbindung zum Mac Mini im lokalen Netzwerk
ssh macmini

# Projektverzeichnis auf Mac Mini
cd /Users/benjaminadmin/Projekte/breakpilot-pwa

# Oder direkt (BEVORZUGT für einzelne Befehle):
ssh macmini "<befehl>"

Hostname: macmini (im lokalen Netzwerk via Bonjour) User: benjaminadmin Projekt: /Users/benjaminadmin/Projekte/breakpilot-pwa

Beispiele für korrekte Befehlsausführung

# ✅ RICHTIG: Befehle auf Mac Mini ausführen
ssh macmini "docker compose ps"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && git status"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/backend && source venv/bin/activate && pytest -v"

# ❌ FALSCH: Lokale Befehle auf MacBook (Docker/Services laufen dort nicht!)
docker compose ps
pytest -v

Browser-Tests (auf MacBook)

Frontend im Browser testen via:

• https://macmini/ (Studio)
• https://macmini:3002/ (Admin)
• https://macmini:3000/ (Website)

---

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)

---

Drei Docker Compose Projekte (WICHTIG!)

Das System besteht aus drei separaten Docker Compose Projekten auf dem Mac Mini:

Projekt	Pfad	Container-Prefix	Beschreibung
breakpilot-pwa	/Users/benjaminadmin/Projekte/breakpilot-pwa/	breakpilot-pwa-*	Haupt-Repo: Studio, Admin, Backend, alle Services
breakpilot-core	/Users/benjaminadmin/Projekte/breakpilot-core/	bp-core-*	Nginx Reverse Proxy (bp-core-nginx)
breakpilot-compliance	/Users/benjaminadmin/Projekte/breakpilot-compliance/	bp-compliance-*	Compliance-System: Developer Portal, Admin, Backend, AI SDK

Wichtige Hinweise zu den Compose-Projekten

• Nginx (bp-core-nginx) läuft in breakpilot-core, NICHT in breakpilot-pwa
• Developer Portal (bp-compliance-developer-portal) läuft in breakpilot-compliance
• Wenn ein Container in breakpilot-pwa nicht existiert, prüfe die anderen Projekte!

# breakpilot-pwa Container verwalten
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml <cmd>"

# breakpilot-core Container verwalten (Nginx)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml <cmd>"

# breakpilot-compliance Container verwalten (Developer Portal, Compliance)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml <cmd>"

---

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
https://macmini:3002/infrastructure/night-mode	Night Mode	Nachtabschaltung UI

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

Developer Portal (Compliance-Dokumentation)

URL	Beschreibung
https://macmini:3006/	Developer Portal Startseite
https://macmini:3006/development/docs	Systemdokumentation Compliance Service
https://macmini:3006/sdk	SDK Dokumentation
https://macmini:3006/api	API Referenz
https://macmini:3006/guides	Guides
https://macmini:3006/changelog	Changelog

Hinweis: Das Developer Portal läuft als bp-compliance-developer-portal im Compose-Projekt breakpilot-compliance auf Port 3006 (via bp-core-nginx).

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:8096/	Night Scheduler API
http://macmini:8009/	MkDocs (Projekt-Doku)

AI Tools (Admin v2)

URL	Tool	Beschreibung
https://macmini:3002/ai/llm-compare	LLM Vergleich	KI-Provider vergleichen
https://macmini:3002/ai/ocr-compare	OCR Vergleich	OCR-Methoden & Vokabel-Extraktion
https://macmini:3002/ai/ocr-labeling	OCR Labeling	Trainingsdaten erstellen
https://macmini:3002/ai/test-quality	Test Quality (BQAS)	Golden Suite & Tests
https://macmini:3002/ai/gpu	GPU Infrastruktur	vast.ai Management
https://macmini:3002/ai/rag-pipeline	RAG Pipeline	Retrieval Augmented Generation
https://macmini:3002/ai/magic-help	Magic Help	KI-Assistent

Lehrer-Tools (Studio v2)

URL	Tool	Beschreibung
https://macmini/vocab-worksheet	Vokabel-Arbeitsblatt	OCR-Scan & Arbeitsblatt-Generator
https://macmini/korrektur	Korrekturplattform	Abiturklausur-Korrektur
https://macmini:8000/app	Dashboard (alt)	Altes Dashboard

---

Services

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
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

Compliance (breakpilot-compliance Projekt)

Service	Tech	Port	Container
developer-portal	Next.js	3006	bp-compliance-developer-portal
compliance-admin	Next.js	-	bp-compliance-admin
compliance-backend	Go	-	bp-compliance-backend
compliance-ai-sdk	Go	8090	bp-compliance-ai-sdk

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 (in breakpilot-core!)
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

Service	Tech	Port	Beschreibung
erpnext-frontend	ERPNext	8009	ERP Frontend
erpnext-backend	ERPNext	-	ERP Backend
erpnext-db	MariaDB	-	ERP Datenbank

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 15, React, TailwindCSS
• admin-v2: Next.js 15, React, TailwindCSS
• website: Next.js 14
• developer-portal: Next.js, React, TailwindCSS (in breakpilot-compliance)

Node.js

• 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
│   │   ├── open-source-policy.md
│   │   ├── compliance-checklist.md
│   │   ├── abiturkorrektur.md
│   │   ├── vocab-worksheet.md
│   │   ├── multi-agent-architecture.md
│   │   └── experimental-dashboard.md
│   └── settings.json
├── admin-v2/                 # Admin Dashboard (Next.js)
├── studio-v2/                # Lehrer-/Schüler-Studio (Next.js)
├── website/                  # Öffentliche Website (Next.js)
├── developer-portal/         # Developer Portal (Next.js, auch in breakpilot-compliance)
├── backend/                  # Python Backend (FastAPI)
├── consent-service/          # Go Consent Service
├── klausur-service/          # Klausur/OCR Service
├── ai-compliance-sdk/        # KI-Compliance SDK
├── breakpilot-compliance-sdk/ # Compliance SDK (Monorepo)
├── voice-service/            # Spracheingabe
├── geo-service/              # Geo-Daten
├── school-service/           # Schulverwaltung
├── edu-search-service/       # Bildungssuche
├── 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

Entfernte/nicht mehr aktive Verzeichnisse (in .gitignore blockiert):

• BreakpilotDrive/ — altes Unity-Projekt, nicht mehr in Entwicklung
• billing-service/ — nicht benötigt

---

Dokumentation (MKDocs)

Live-URL: https://macmini:3002/development/docs Quellen: /docs-src/ Build: /docs-site/ Config: mkdocs.yml

Dokumentation bearbeiten

# 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 (via SSH auf Mac Mini)

# Alle Services starten (breakpilot-pwa)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml up -d"

# Einzelnen Service neu bauen & starten
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml build --no-cache <service-name>"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml up -d <service-name>"

# Logs anzeigen
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml logs -f <service-name>"

# Status aller Container
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml ps"

# Developer Portal (in breakpilot-compliance!)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml build --no-cache developer-portal"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml up -d developer-portal"

# Nginx (in breakpilot-core!)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml restart nginx"

WICHTIG: Docker-Pfad auf Mac Mini ist /usr/local/bin/docker (nicht im Standard-PATH bei SSH).

Tests (via SSH)

# Go Tests (Consent Service)
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/consent-service && go test -v ./..."

# Python Tests
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/backend && source venv/bin/activate && pytest -v"

Git

# Zwei Remotes konfiguriert - IMMER zu beiden pushen!
# origin: http://macmini:3003/pilotadmin/breakpilot-pwa.git (lokale Gitea auf Mac Mini)
# gitea:  git@gitea.meghsakha.com:Benjamin_Boenisch/breakpilot-pwa.git (externer Gitea-Server)

# Push zu beiden Remotes (PFLICHT bei jedem Push):
git push origin main && git push gitea main

# Git-Befehle auf Mac Mini ausfuehren (ohne cd):
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-pwa status"
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-pwa pull --no-rebase origin main"

---

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

NIEMALS ins Git laden (via .gitignore blockiert):

• *.pdf, *.docx, *.xlsx, *.pptx — Dokumente bleiben nur lokal auf dem Mac Mini
• Kompilierte Go-Binaries (consent-service/server, etc.)
• Große Mediendateien (Videos, Audio, Bilder >1 MB)
• BreakpilotDrive/ — altes Unity-Projekt
• billing-service/ — nicht benötigt

Hinweis: Die Git-History wurde am 2026-02-12 mit git-filter-repo bereinigt. Alle PDFs, Word-/Excel-Dateien, BreakpilotDrive/ und billing-service/ wurden aus der gesamten History entfernt. Das Repo ging dadurch von 1.7 GB auf 11 MB.

---

Ansprechpartner

• Git-Server: http://macmini:3003 (Gitea)
• CI/CD: http://macmini:8090 (Woodpecker)
• Issue-Tracker: Gitea Issues