breakpilot-core/.claude/CLAUDE.md

BreakPilot Core - Shared Infrastructure

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup + Orca

Geraet	Rolle	Aufgaben
MacBook	Entwicklung	Claude Terminal, Code-Entwicklung, Browser (Frontend-Tests)
Mac Mini	Lokaler Server	Docker fuer lokale Dev/Tests (NICHT fuer Production!)
Orca	Production	Automatisches Build + Deploy bei Push auf gitea

WICHTIG: Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Production-Deployment laeuft automatisch ueber Orca.

Entwicklungsworkflow (CI/CD — Orca)

# 1. Code auf MacBook bearbeiten (dieses Verzeichnis)
# 2. Committen und zu BEIDEN Remotes pushen:
git push origin main

# 3. FERTIG! Push auf gitea triggert automatisch:
#    - Gitea Actions: Tests
#    - Orca: Build → Deploy

NIEMALS manuell in Orca auf "Redeploy" klicken — Gitea Actions triggert Orca automatisch. IMMER auf main pushen — sowohl origin als auch gitea.

TEMPORAER: Compliance-Repo Refactoring (Stand 2026-04-12)

Das Compliance-Repo wird aktuell auf Production (gitea) refakturiert.

• Core + Lehrer: Normal auf main pushen (origin + gitea) ✅
• Compliance auf Mac Mini (origin): Normal auf main pushen ✅
• Compliance auf Production (gitea): NUR Feature Branches, NICHT auf main pushen! ⚠️

# Compliance-Repo — RICHTIG:
git push origin main                                    # Mac Mini OK
git push gitea feature/mein-feature                     # Production: nur Feature Branch!

# Compliance-Repo — FALSCH (waehrend Refactoring):
# git push gitea main                                   # NICHT MACHEN!

Nach Abschluss des Refactorings: Gesamten Compliance-Code einmalig von Production auf Mac Mini uebernehmen. User sagt Bescheid wann es soweit ist.

Post-Push Deploy-Monitoring (PFLICHT nach jedem Push auf gitea)

IMMER wenn Claude auf gitea pusht, MUSS danach automatisch das Deploy-Monitoring laufen:

1. Dem User sofort mitteilen: "Deploy gestartet, ich ueberwache den Status..."
2. Im Hintergrund Health-Checks pollen (alle 20 Sekunden, max 5 Minuten):

   curl -sf https://api-dev.breakpilot.ai/health    # Compliance Backend
   curl -sf https://sdk-dev.breakpilot.ai/health     # AI SDK
   

3. Sobald ALLE Endpoints healthy sind, dem User im Chat melden: "Deploy abgeschlossen! Du kannst jetzt testen."
4. Falls nach 5 Minuten noch nicht healthy → Fehlermeldung mit Hinweis auf Orca-Logs.

Lokale Entwicklung (Mac Mini — optional, nur Dev/Tests)

ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && git pull --no-rebase origin main"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service> && /usr/local/bin/docker compose up -d <service>"

SSH-Verbindung (fuer lokale Docker/Tests)

ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && <cmd>"

---

Projekt-Kontext

breakpilot-core ist das Infrastruktur-Fundament der BreakPilot-Plattform. Es stellt alle gemeinsamen Services bereit, die von breakpilot-lehrer und breakpilot-compliance genutzt werden.

3-Projekt-Architektur

breakpilot-core          (dieses Repo — MUSS ZUERST starten)
  ├── breakpilot-lehrer      (haengt von Core ab)
  └── breakpilot-compliance  (haengt von Core ab)

Alle 3 Projekte teilen sich ein Docker-Netzwerk:

networks:
  breakpilot-network:
    driver: bridge
    name: breakpilot-network   # Fixer Name, kein Auto-Prefix!

Deployment-Modell

Repo	Deployment	Trigger
breakpilot-core	Orca (automatisch)	Push auf gitea main
breakpilot-compliance	Orca (automatisch)	Push auf gitea main
breakpilot-lehrer	Mac Mini (lokal)	Manuell docker compose

---

Haupt-URLs (via Nginx Reverse Proxy)

Core-eigene Services

URL	Service	Beschreibung
https://macmini:8000/	backend-core	Shared APIs (Auth, RBAC, Notifications)
https://macmini:8097/	rag-service	Semantische Suche, Dokument-Upload
https://macmini:8443/	Jitsi Meet	Videokonferenzen
http://macmini:8099/	health-aggregator	Health-Check aller Services

Interne Dienste (kein HTTPS)

URL	Service	Beschreibung
http://macmini:3003/	Gitea	Git-Server (User: pilotadmin)
http://macmini:8090/	Woodpecker CI	CI/CD Server
http://macmini:8200/	Vault	Secrets Management
http://macmini:8025/	Mailpit	E-Mail (Dev)
http://macmini:9001/	MinIO Console	S3 Storage UI
http://macmini:8096/	Night Scheduler	Auto-Shutdown/Startup
http://macmini:8089/	Camunda	BPMN Engine

Nginx-Proxy fuer Lehrer/Compliance (durchgereicht)

URL	Projekt	Service
https://macmini/	Lehrer	Studio v2
https://macmini:3000/	Lehrer	Website
https://macmini:3002/	Lehrer	Admin Lehrer
https://macmini:3007/	Compliance	Admin Compliance
https://macmini:8001/	Lehrer	Backend Lehrer
https://macmini:8002/	Compliance	Backend Compliance
https://macmini:8086/	Lehrer	Klausur-Service
https://macmini:8093/	Compliance	AI Compliance SDK

---

Services (~28 Container)

Infrastruktur

Service	Tech	Port	Container
nginx	Nginx	80/443 + viele	bp-core-nginx
postgres	PostGIS 16	5432	bp-core-postgres
valkey	Valkey 8	6379	bp-core-valkey
vault	HashiCorp Vault	8200	bp-core-vault
vault-agent	Vault	-	bp-core-vault-agent
qdrant	Qdrant	6333/6334	bp-core-qdrant
minio	MinIO	9000/9001	bp-core-minio
mailpit	Mailpit	8025/1025	bp-core-mailpit

Shared Backend-Services

Service	Tech	Port	Container
backend-core	Python/FastAPI	8000	bp-core-backend
rag-service	Python/FastAPI	8097	bp-core-rag-service
embedding-service	Python/FastAPI	8087	bp-core-embedding-service
consent-service	Go/Gin	8081	bp-core-consent-service
billing-service	Go	8083	bp-core-billing-service
health-aggregator	Python/FastAPI	8099	bp-core-health
night-scheduler	Python/FastAPI	8096	bp-core-night-scheduler

Kommunikation

Service	Tech	Container
jitsi-web	Jitsi	bp-core-jitsi-web
jitsi-xmpp	Prosody	bp-core-jitsi-xmpp
jitsi-jicofo	Jicofo	bp-core-jitsi-jicofo
jitsi-jvb	JVB	bp-core-jitsi-jvb
synapse + synapse-db	Matrix	bp-core-synapse (Profil: chat)

DevOps

Service	Tech	Port	Container
gitea	Gitea	3003	bp-core-gitea
gitea-runner	Gitea Actions	-	bp-core-gitea-runner
woodpecker-server	Woodpecker	8090	bp-core-woodpecker-server
woodpecker-agent	Woodpecker	-	bp-core-woodpecker-agent
camunda	Camunda	8089	bp-core-camunda (Profil: bpmn)

Profile (nur bei Bedarf starten)

Profil	Services	Start mit
chat	synapse, synapse-db	--profile chat
erp	erpnext-* (7 Container)	--profile erp
bpmn	camunda	--profile bpmn
docs	docs (MkDocs)	--profile docs
backup	pg-backup	--profile backup

---

Datenbank

3 Schemas (shared PostgreSQL)

Schema	Projekt	Tabellen
core	Core	users, sessions, auth, rbac, notifications, email_templates, billing
lehrer	Lehrer	classroom, units, klausuren, vocab, game, meetings, messenger
compliance	Compliance	compliance_*, dsr, gdpr, sdk_tenants, consent_admin

# DB-Zugang (lokal)
ssh macmini "docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"

---

Verzeichnisstruktur

breakpilot-core/
├── .claude/
│   ├── CLAUDE.md             # Diese Datei
│   └── rules/                # Automatische Regeln
├── backend-core/             # Python/FastAPI (Auth, RBAC, Notifications)
├── rag-service/              # Python/FastAPI (Qdrant, MinIO, Embeddings)
├── embedding-service/        # Python/FastAPI (Sentence-Transformers)
├── consent-service/          # Go/Gin (Consent-Management)
├── billing-service/          # Go (Abrechnungsservice)
├── night-scheduler/          # Python/FastAPI (Auto-Shutdown)
├── nginx/conf.d/             # Nginx Reverse Proxy Config
├── vault/                    # Vault Config + TLS Certs
├── gitea/                    # Gitea Config
├── docs-src/                 # MkDocs Quellen
├── mkdocs.yml                # MkDocs Config
├── control-pipeline/          # RAG/Control Pipeline (Port 8098)
├── scripts/                  # Helper Scripts
└── docker-compose.yml        # Haupt-Compose (28+ Services)

---

Control Pipeline (WICHTIG)

Seit 2026-04-09 liegt die gesamte RAG/Control-Pipeline im Core-Repo (control-pipeline/), NICHT mehr im Compliance-Repo. Alle Arbeiten an der Pipeline (Pass 0a/0b, BatchDedup, Control Generator, Enrichment) finden ausschliesslich hier statt.

• Port: 8098
• Container: bp-core-control-pipeline
• DB: Schreibt ins compliance-Schema der shared PostgreSQL
• Das Compliance-Repo wird NICHT fuer Pipeline-Aenderungen benutzt

# Container auf Mac Mini
ssh macmini "cd ~/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache control-pipeline && /usr/local/bin/docker compose up -d --no-deps control-pipeline"

# Health
ssh macmini "/usr/local/bin/docker exec bp-core-control-pipeline curl -sf http://127.0.0.1:8098/health"

# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-control-pipeline"

---

Haeufige Befehle

Deployment (CI/CD — Standardweg)

# Committen und pushen → Orca deployt automatisch:
git push origin main

Lokale Docker-Befehle (Mac Mini — nur Dev/Tests)

# Alle Core-Services starten
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"

# Einzelnen Service neu bauen
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service>"

# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-<service>"

# Status
ssh macmini "/usr/local/bin/docker ps --filter name=bp-core"

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

Git

# Zu BEIDEN Remotes pushen (PFLICHT!):
git push origin main

# Remotes:

---

Pre-Push Checks (PFLICHT — VOR JEDEM PUSH)

Full detail: .claude/rules/pre-push-checks.md | Stack rules: AGENTS.python.md, AGENTS.go.md, AGENTS.typescript.md

NIEMALS pushen ohne diese Checks. CI-Failures blockieren das gesamte Deploy.

Python (backend-core, rag-service, embedding-service, control-pipeline)

cd <service-dir>
ruff check . && mypy . --ignore-missing-imports --no-error-summary && pytest tests/ -x -q --no-header

Go (consent-service, billing-service)

cd <service-dir>
gofmt -l . | grep -q . && exit 1; go vet ./... && golangci-lint run --timeout=5m && go test -race ./... && go build ./...

TypeScript/Next.js (pitch-deck, admin-v2)

cd pitch-deck   # or admin-v2
npx tsc --noEmit && npm run lint && npm run build

npm run build ist PFLICHT — tsc allein reicht nicht. Syntax-Fehler wie const inside object literal werden nur vom Build gefangen.

---

Code-Qualitaet Guardrails (NON-NEGOTIABLE)

Vollstaendige Details: .claude/rules/architecture.md Ausnahmen: .claude/rules/loc-exceptions.txt

File Size Budget

• Hard Cap: 500 LOC pro Datei
• Wenn eine Aenderung eine Datei ueber 500 LOC bringen wuerde: erst splitten, dann aendern
• Ausnahmen nur mit Begruendung in loc-exceptions.txt + [guardrail-change] Commit-Marker

Architektur

• Go: Handler ≤40 LOC → Service-Layer → Repository-Pattern
• Python: Routes duenn → Business Logic in Services → Persistenz in Repositories
• TypeScript/Next.js: page.tsx duenn → _components/, _hooks/ auslagern

FINGER WEG (laufende RAG Pipeline)

Diese Verzeichnisse duerfen NICHT refaktoriert werden:

• control-pipeline/ — RAG/Control-Extraction Pipeline
• rag-service/ — Semantische Suche
• embedding-service/ — Text-Embeddings
• voice-service/bqas/ — RAG Quality Assessment

LOC-Check ausfuehren

bash scripts/check-loc.sh --changed   # nur geaenderte Dateien
bash scripts/check-loc.sh --all       # alle Dateien (zeigt alle Violations)

Commit-Marker

• [split-required] — Aenderung beginnt mit Datei-Split
• [guardrail-change] — Aenderungen an .claude/**, scripts/check-loc.sh
• [interface-change] — Public API Contracts geaendert

---

Kernprinzipien

1. Open Source Policy

• NUR Open Source mit kommerziell nutzbarer Lizenz
• Erlaubt: MIT, Apache-2.0, BSD, ISC, MPL-2.0, LGPL
• VERBOTEN: GPL (ausser LGPL), AGPL, proprietaer

2. Testing & Dokumentation

• Tests sind Pflicht bei jeder Aenderung
• MkDocs aktualisieren: --profile docs starten

3. Sensitive Dateien

NIEMALS aendern oder committen:

• .env, .env.local, Vault-Tokens, SSL-Zertifikate
• *.pdf, *.docx, kompilierte Binaries, grosse Medien

---

Nginx Port-Zuordnung (Uebersicht)

Port	Ziel-Container	Projekt
443	bp-lehrer-studio-v2	Lehrer
3000	bp-lehrer-website	Lehrer
3002	bp-lehrer-admin	Lehrer
3006	bp-compliance-developer-portal	Compliance
3007	bp-compliance-admin	Compliance
8000	bp-core-backend	Core
8001	bp-lehrer-backend	Lehrer
8002	bp-compliance-backend	Compliance
8086	bp-lehrer-klausur-service	Lehrer
8087	bp-core-embedding-service	Core
8089	bp-core-camunda	Core
8091	bp-lehrer-voice-service	Lehrer
8093	bp-compliance-ai-sdk	Compliance
8097	bp-core-rag-service	Core
8443	bp-core-jitsi-web	Core