Benjamin_Boenisch/breakpilot-lehrer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
breakpilot-lehrer/.claude/CLAUDE.md
Benjamin Admin d5f2ce4659
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 25s
Details
CI / test-go-edu-search (push) Successful in 28s
Details
CI / test-python-klausur (push) Failing after 1m46s
Details
CI / test-python-agent-core (push) Successful in 14s
Details
CI / test-nodejs-website (push) Successful in 15s
Details
fix: Fabric.js v6 API compatibility + CLAUDE.md SSH commands 
- Replace setBackgroundImage() with backgroundImage property (v6 breaking change)
- Replace setWidth/setHeight with Canvas constructor options
- Fix opacity handler to use direct property access
- Update CLAUDE.md: use git -C and docker compose -f instead of cd

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-03 23:01:19 +01:00

259 lines
8.5 KiB
Markdown
Raw Permalink 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 |
Reference in New Issue View Git Blame Copy Permalink