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

---

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