Benjamin_Boenisch/breakpilot-lehrer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
37db47fcd9e8cfddda3bd94e30f9bce7a5b6bac0
breakpilot-lehrer/.claude/CLAUDE.md
Benjamin Admin 7ff9860c69
Some checks failed
CI / go-lint (push) Has been skipped
Details
CI / python-lint (push) Has been skipped
Details
CI / nodejs-lint (push) Has been skipped
Details
CI / test-go-school (push) Successful in 59s
Details
CI / test-go-edu-search (push) Successful in 45s
Details
CI / test-python-klausur (push) Failing after 3m7s
Details
CI / test-python-agent-core (push) Successful in 24s
Details
CI / test-nodejs-website (push) Successful in 31s
Details
Add Vocabulary Learning Platform (Phase 1: DB + API + Editor) 
Strategic pivot: Studio-v2 becomes a language learning platform.
Compliance guardrail added to CLAUDE.md — no scan/OCR of third-party
content in customer frontend. Upload of OWN materials remains allowed.

Phase 1.1 — vocabulary_db.py: PostgreSQL model for 160k+ words
with english, german, IPA, syllables, examples, images, audio,
difficulty, tags, translations (multilingual). Trigram search index.

Phase 1.2 — vocabulary_api.py: Search, browse, filters, bulk import,
learning unit creation from word selection. Creates QA items with
enhanced fields (IPA, syllables, image, audio) for flashcards.

Phase 1.3 — /vocabulary page: Search bar with POS/difficulty filters,
word cards with audio buttons, unit builder sidebar. Teacher selects
words → creates learning unit → redirects to flashcards.

Sidebar: Added "Woerterbuch" (/vocabulary) and "Lernmodule" (/learn).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-24 13:36:28 +02:00

323 lines
11 KiB
Markdown
Raw Blame History

# 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 |
---
## 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
bash scripts/check-loc.sh --changed # nur geaenderte Dateien
bash scripts/check-loc.sh --all # alle Dateien (zeigt alle Violations)
```
Reference in New Issue View Git Blame Copy Permalink