# 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

```bash
# 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:
```yaml
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

```bash
# 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

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

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

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

### Git

```bash
# 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 |