breakpilot-core/.claude/CLAUDE.md

BreakPilot Core - Shared Infrastructure

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup + Coolify

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

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

Entwicklungsworkflow (CI/CD — Coolify)

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

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

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

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 Coolify-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	Coolify (automatisch)	Push auf gitea main
breakpilot-compliance	Coolify (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
├── scripts/                  # Helper Scripts
└── docker-compose.yml        # Haupt-Compose (28+ Services)

---

Haeufige Befehle

Deployment (CI/CD — Standardweg)

# Committen und pushen → Coolify deployt automatisch:
git push origin main && git push gitea 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 && git push gitea main

# Remotes:
# origin: lokale Gitea (macmini:3003)
# gitea:  gitea.meghsakha.com

---

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