breakpilot-lehrer/.claude/CLAUDE.md

BreakPilot Lehrer - KI-Bildungsplattform

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup

Geraet	Rolle	Aufgaben
MacBook	Entwicklung	Claude Terminal, Code-Entwicklung, Browser (Frontend-Tests)
Mac Mini	Server	Docker, alle Services, Tests, Builds, Deployment

WICHTIG: Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Docker und Services laufen auf dem Mac Mini.

Entwicklungsworkflow

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

# 3. Auf Mac Mini pullen und Container neu bauen:
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-lehrer pull --no-rebase origin main"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml build --no-cache <service>"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml up -d <service>"

SSH-Verbindung (fuer Docker/Tests)

WICHTIG: cd in SSH-Kommandos funktioniert NICHT zuverlaessig! Stattdessen:

• Git: git -C /Users/benjaminadmin/Projekte/breakpilot-lehrer <cmd>
• Docker: /usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml <cmd>
• Logs: /usr/local/bin/docker logs -f bp-lehrer-<service>

---

Voraussetzung

breakpilot-core MUSS laufen! Dieses Projekt nutzt Core-Services:

• PostgreSQL (Schema: lehrer, core)
• Valkey (Session-Cache)
• Vault (Secrets)
• RAG-Service (Vektorsuche)
• Embedding-Service (Text-Embeddings)
• Nginx (Reverse Proxy)

Pruefen: curl -sf http://macmini:8099/health

---

Haupt-URLs (Browser auf MacBook)

Frontends

URL	Service	Beschreibung
https://macmini/	Studio v2	Lehrer-/Schueler-Interface
https://macmini:3000/	Website	Oeffentliche Website
https://macmini:3002/	Admin Lehrer	Dashboard, AI-Tools, Architektur

Backend-APIs

URL	Service	Beschreibung
https://macmini:8001/	Backend Lehrer	Classroom, Units, Meetings, State Engine
https://macmini:8086/	Klausur-Service	Pruefungen, OCR, Vokabel-Worksheets, RAG
wss://macmini:8091/	Voice-Service	Spracheingabe WebSocket

Admin Lehrer Module (https://macmini:3002/)

Pfad	Modul
/dashboard	Dashboard + Catalog-Manager
/ai/llm-compare	LLM Vergleich
/ai/ocr-compare	OCR Vergleich
/ai/ocr-labeling	OCR Trainingsdaten
/ai/test-quality	Test Quality (BQAS)
/ai/gpu	GPU Infrastruktur (vast.ai)
/ai/rag-pipeline	RAG Pipeline
/ai/magic-help	KI-Assistent
/education	Bildungsmodule
/communication	Messenger, Meetings
/development	Entwickler-Tools, Docs
/infrastructure	Night-Mode, Security, SBOM
/architecture	Architektur-Visualisierung
/rbac	Rollenverwaltung
/website	Website-Management

Lehrer-Tools (Studio v2 - https://macmini/)

Pfad	Tool	Beschreibung
/vocab-worksheet	Vokabel-Arbeitsblatt	OCR-Scan + Arbeitsblatt-Generator
/korrektur	Korrekturplattform	Abiturklausur-Korrektur

---

Services (~12 Container)

Service	Tech	Port	Container
admin-lehrer	Next.js 15	3002 (via nginx)	bp-lehrer-admin
studio-v2	Next.js 15	443 (via nginx)	bp-lehrer-studio-v2
website	Next.js 14	3000 (via nginx)	bp-lehrer-website
backend-lehrer	Python/FastAPI	8001	bp-lehrer-backend
klausur-service	Python/FastAPI	8086	bp-lehrer-klausur-service
school-service	Python	8082	bp-lehrer-school-service
voice-service	Python/FastAPI	8091	bp-lehrer-voice-service
geo-service	Python/FastAPI	8084	bp-lehrer-geo-service
breakpilot-drive	Node.js	-	bp-lehrer-drive (Profil: game)
paddleocr-service	Python	-	bp-lehrer-paddleocr (Profil: ocr)
agent-core	Python	-	bp-lehrer-agent-core (Profil: dev)

Profile (nur bei Bedarf)

Profil	Services	Start mit
game	breakpilot-drive	--profile game
ocr	paddleocr-service	--profile ocr
dev	agent-core	--profile dev
recording	transcription-worker	--profile recording

Docker-Netzwerk

Nutzt das externe Core-Netzwerk:

networks:
  breakpilot-network:
    external: true
    name: breakpilot-network

Container-Naming: bp-lehrer-*

DB search_path: lehrer,core,public

---

Verzeichnisstruktur

breakpilot-lehrer/
├── .claude/
│   ├── CLAUDE.md             # Diese Datei
│   └── rules/                # Automatische Regeln
├── admin-lehrer/             # Next.js Admin Dashboard
│   ├── app/(admin)/          # 12 Route-Groups
│   ├── components/           # UI-Komponenten
│   └── lib/                  # Utilities, Navigation
├── studio-v2/                # Next.js Lehrer-/Schueler-Studio
├── website/                  # Next.js Oeffentliche Website
├── backend-lehrer/           # Python/FastAPI Backend
│   ├── classroom_api.py
│   ├── state_engine_api.py
│   ├── worksheets_api.py
│   ├── correction_api.py
│   ├── meetings_api.py
│   ├── messenger_api.py
│   └── ...
├── klausur-service/          # Klausur/OCR/RAG Service
├── school-service/           # Schulverwaltung
├── voice-service/            # Spracheingabe (Whisper)
├── geo-service/              # Geo-Daten (PostGIS)
├── agent-core/               # Multi-Agent System
├── breakpilot-drive/         # Dateiablage (IPFS)
├── scripts/                  # Helper Scripts
└── docker-compose.yml        # Lehrer Compose (~12 Services)

---

Haeufige Befehle

Docker

# Lehrer-Services starten (Core muss laufen!)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml up -d"

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

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

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

WICHTIG: Docker-Pfad auf Mac Mini ist /usr/local/bin/docker (nicht im Standard-SSH-PATH). WICHTIG: Immer -f mit vollem Pfad zur docker-compose.yml nutzen, cd in SSH funktioniert nicht!

Frontend-Entwicklung

# Admin Lehrer im Browser testen:
# https://macmini:3002/

# Studio v2 im Browser testen:
# https://macmini/

# Website im Browser testen:
# https://macmini:3000/

Git

# Zu BEIDEN Remotes pushen (PFLICHT!):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-lehrer && git push all main"

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

---

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
• Dokumentation aktualisieren in MkDocs

3. Sensitive Dateien

NIEMALS aendern oder committen:

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

---

Tech-Stack

Sprache	Services
Python/FastAPI	backend-lehrer, klausur-service, voice-service, geo-service
TypeScript/Next.js	admin-lehrer, studio-v2, website
Node.js	breakpilot-drive
Python	agent-core, paddleocr-service

---

Stundenplan + Schulkalender (Mai 2026, alle Phasen deployed)

Zwei groesse Feature-Strange, vollstaendig live auf Mac Mini:

Pfad	Beschreibung
/stundenplan (studio-v2)	Lehrer-UI mit 9 Tabs (Plan + 7 Stammdaten + Regeln), 15 Constraint-Editoren, Pin/Unpin im Wochengrid
/schulkalender (studio-v2)	Bundesland-Wizard, Monatsansicht mit Ferien (16 BL × 3 Jahre), Schul-Events, Schuljahres-Rollover, Eltern-Manager
/eltern (studio-v2)	Eltern-Sicht: Wochengrid des eigenen Kindes in Eltern-Sprache, Magic-Link-Login
school-service (Go, :8084)	Beide Backends — 30+ Tabellen, JWT-Auth (Dev-Bypass aktiv), Cron fuer Notifications
timetable-solver-service (Python+JVM, :8095)	Timefold-basierter Solver, 14 Constraints implementiert

Wichtigste Memo-Dateien fuer Wiedereinstieg:

• ~/.claude/projects/-Users-benjaminadmin-Projekte-breakpilot-lehrer/memory/session_summary_2026_05_22.md — vollstaendiges Inventar
• ~/.claude/projects/-Users-benjaminadmin/memory/project_timetable_scheduler.md — Stundenplan-Status
• ~/.claude/projects/-Users-benjaminadmin-Projekte-breakpilot-lehrer/memory/project_schulkalender.md — Schulkalender-Status

Pitfalls (vermeidet diese):

• Timefold Python-Package heisst timefold (NICHT timefold-solver), v1.24.0b0
• Production-Auth + Matrix/Email-Services baut Kollege — Frontend-Hooks nutzen, kein eigener Service-Code
• JSX-Attribute mit deutschen Quotes „X" brechen, Loesung: description={"..."} Expression-Form
• LOC-Budget 500 pro File — bei specs mit shared Helpers arbeiten (e2e/_helpers.ts)

Test-Status (Stand 2026-05-22): 89 Go + 21 Playwright im Schulkalender + 42 Playwright im Stundenplan = 152 grun

Offen: Seed-Daten fuer Demo-Schule, Vollschuljahr-ICS mit RRULE+EXDATE, Untis-Import (Phase 4 geparkt).

---

Wichtige Dateien (Referenz)

Datei	Beschreibung
klausur-service/backend/main.py	Haupt-API: Klausuren, OCR, Vocab
klausur-service/backend/nru_worksheet_generator.py	NRU Arbeitsblatt-Generator
klausur-service/backend/hybrid_vocab_extractor.py	OCR-Extraktion
admin-lehrer/app/(admin)/	Alle 12 Admin Route-Groups
admin-lehrer/lib/navigation.ts	Sidebar-Navigation
studio-v2/app/vocab-worksheet/page.tsx	Vokabel-Arbeitsblatt UI
website/app/admin/klausur-korrektur/	Korrektur-Workspace
backend-lehrer/classroom_api.py	Classroom Engine
backend-lehrer/state_engine_api.py	State Engine

---

Compliance: Kein Scan/OCR im Kunden-Frontend (NON-NEGOTIABLE)

Studio-v2 (Kunden-Frontend, Port 443) darf KEINE Features enthalten die:

• Buchseiten/Schulbuecher von Dritten rekonstruieren oder reproduzieren
• Aktiv zum Upload fremder urheberrechtlich geschuetzter Werke auffordern

Erlaubt in studio-v2:

• Upload eigener Dokumente durch Lehrer (eigene Arbeitsblaetter, Tests, Materialien)
• OCR/Verarbeitung von Dokumenten bei denen der Lehrer Urheber ist
• Manuelle Vokabeleingabe durch Lehrer
• Vorschlagslisten aus eigenem Woerterbuch (160k MIT-lizenzierte Woerter)
• Lernunit-Erstellung aus eigenen/ausgewaehlten Inhalten
• Audio/Bild/Quiz/Karteikarten-Generierung

Erweiterte OCR/Scan Features (z.B. Vision-LLM Fusion, A/B Testing Toggles) bleiben im Admin-Frontend (admin-lehrer, Port 3002) fuer Entwicklung und Testing.

Hintergrund: Urheberrechtliche Haftung der GmbH. Das System ist eine Didaktik-Engine (Transformation + Lernen), KEIN Content-Reconstruction-Tool.

---

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

• Python: Routes duenn → Business Logic in Services → Persistenz in Repositories
• Go: Handler ≤40 LOC → Service-Layer → Repository-Pattern
• TypeScript/Next.js: page.tsx duenn → Server Actions, Queries, Components auslagern
• Types: Monolithische types.ts frueh splitten, types.ts + types/ Shadowing vermeiden

Workflow (bei jeder Aenderung)

1. Datei lesen + LOC pruefen
2. Wenn nahe am Budget → erst splitten
3. Minimale kohaerente Aenderung
4. Verifikation (Tests + Lint)
5. Zusammenfassung: Was geaendert, was verifiziert, Restrisiko

Commit-Marker

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

LOC-Check ausfuehren

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