# BreakPilot PWA - Projekt-Kontext für Claude

## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

### Zwei-Rechner-Setup

| Gerät | Rolle | Aufgaben |
|-------|-------|----------|
| **MacBook** | Client | Claude Terminal, Browser (Frontend-Tests) |
| **Mac Mini** | Server | Docker, alle Services, Code-Ausführung, Tests, Git |

**WICHTIG:** Die Entwicklung findet vollständig auf dem **Mac Mini** statt!
- Alle Befehle (docker, git, tests, builds) per SSH auf dem Mac Mini ausführen
- Das MacBook dient nur als Terminal und Browser für Frontend-Tests
- Dateien werden auf dem Mac Mini bearbeitet, nicht lokal auf dem MacBook

### SSH-Verbindung

```bash
# Verbindung zum Mac Mini im lokalen Netzwerk
ssh macmini

# Projektverzeichnis auf Mac Mini
cd /Users/benjaminadmin/Projekte/breakpilot-pwa

# Oder direkt (BEVORZUGT für einzelne Befehle):
ssh macmini "<befehl>"
```

**Hostname:** `macmini` (im lokalen Netzwerk via Bonjour)
**User:** `benjaminadmin`
**Projekt:** `/Users/benjaminadmin/Projekte/breakpilot-pwa`

### Beispiele für korrekte Befehlsausführung

```bash
# ✅ RICHTIG: Befehle auf Mac Mini ausführen
ssh macmini "docker compose ps"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && git status"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/backend && source venv/bin/activate && pytest -v"

# ❌ FALSCH: Lokale Befehle auf MacBook (Docker/Services laufen dort nicht!)
docker compose ps
pytest -v
```

### Browser-Tests (auf MacBook)

Frontend im Browser testen via:
- https://macmini/ (Studio)
- https://macmini:3002/ (Admin)
- https://macmini:3000/ (Website)

---
## Kernprinzipien (IMMER BEACHTEN)

### 1. Open Source Policy
- **NUR Open Source mit kommerziell nutzbarer Lizenz verwenden**
- Erlaubte Lizenzen: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL
- **VERBOTEN:** GPL (außer LGPL), AGPL, proprietäre Software, "free for non-commercial use"
- **Bei jeder neuen Dependency:** SBOM aktualisieren unter https://macmini:3002/infrastructure/sbom

### 2. Testing & Dokumentation
- **Tests sind Pflicht:** Unit Tests, Integration Tests für jede Änderung
- **Dokumentation aktualisieren:** https://macmini:3002/development/docs (MKDocs)
- Siehe `@.claude/rules/testing.md` und `@.claude/rules/documentation.md`

### 3. Architektur & Visualisierung aktualisieren
Nach größeren Änderungen diese Dashboards aktualisieren:
- **Architektur:** https://macmini:3002/architecture
- **Screenflows:** https://macmini:3002/development/screen-flow
- **Dashboard:** https://macmini:3002/dashboard
- **Security Tools:** https://macmini:3002/infrastructure/security

### 4. CI/CD Pipeline
Alle Security-Tools müssen nach der Pipeline durchlaufen:
- Trivy (Container-Scanning)
- Semgrep (SAST)
- Gitleaks (Secret-Detection)
- SBOM-Generierung

---

## Projektübersicht

**Projektname:** BreakPilot PWA
**Typ:** DSGVO-konforme EdTech-Plattform für den DACH-Raum
**Architektur:** Microservices mit Docker Compose
**Plattform:** Mac Mini M2 (Apple Silicon / ARM64)

---

## Drei Docker Compose Projekte (WICHTIG!)

Das System besteht aus **drei separaten Docker Compose Projekten** auf dem Mac Mini:

| Projekt | Pfad | Container-Prefix | Beschreibung |
|---------|------|-------------------|--------------|
| **breakpilot-pwa** | `/Users/benjaminadmin/Projekte/breakpilot-pwa/` | `breakpilot-pwa-*` | Haupt-Repo: Studio, Admin, Backend, alle Services |
| **breakpilot-core** | `/Users/benjaminadmin/Projekte/breakpilot-core/` | `bp-core-*` | Nginx Reverse Proxy (`bp-core-nginx`) |
| **breakpilot-compliance** | `/Users/benjaminadmin/Projekte/breakpilot-compliance/` | `bp-compliance-*` | Compliance-System: Developer Portal, Admin, Backend, AI SDK |

### Wichtige Hinweise zu den Compose-Projekten

- **Nginx** (`bp-core-nginx`) läuft in `breakpilot-core`, NICHT in `breakpilot-pwa`
- **Developer Portal** (`bp-compliance-developer-portal`) läuft in `breakpilot-compliance`
- Wenn ein Container in `breakpilot-pwa` nicht existiert, prüfe die anderen Projekte!

```bash
# breakpilot-pwa Container verwalten
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml <cmd>"

# breakpilot-core Container verwalten (Nginx)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml <cmd>"

# breakpilot-compliance Container verwalten (Developer Portal, Compliance)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml <cmd>"
```

---

## Haupt-URLs (HTTPS via Nginx)

| URL | Service | Beschreibung |
|-----|---------|--------------|
| https://macmini/ | Studio v2 | Lehrer-/Schüler-Interface |
| https://macmini:3000/ | Website | Öffentliche Website |
| https://macmini:3002/ | Admin v2 | **Admin-Dashboard (Hauptzugang)** |
| https://macmini:8000/ | Backend API | FastAPI Backend |
| https://macmini:8086/ | Klausur Service | Prüfungs-/Klausurservice |
| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
| wss://macmini:8091/ | Voice Service | Spracheingabe WebSocket |
| https://macmini:3002/infrastructure/night-mode | Night Mode | Nachtabschaltung UI |

### AI Compliance SDK (DSGVO-Tools)

| URL | Modul | Beschreibung |
|-----|-------|--------------|
| https://macmini:3002/sdk | SDK Admin | Haupt-SDK mit allen Modulen |
| https://macmini:3002/sdk/tom | TOM | Technisch-Organisatorische Maßnahmen |
| https://macmini:3002/sdk/dsfa | DSFA | Datenschutz-Folgenabschätzung |
| https://macmini:3002/sdk/vvt | VVT | Verzeichnis von Verarbeitungstätigkeiten |
| https://macmini:3002/sdk/loeschfristen | Löschfristen | Löschfristen-Verwaltung |
| https://macmini:3002/developers | Developer Portal | API-Dokumentation für Kunden |
| https://macmini:8093/ | SDK API | Backend-API für SDK |

### Developer Portal (Compliance-Dokumentation)

| URL | Beschreibung |
|-----|--------------|
| https://macmini:3006/ | Developer Portal Startseite |
| https://macmini:3006/development/docs | **Systemdokumentation Compliance Service** |
| https://macmini:3006/sdk | SDK Dokumentation |
| https://macmini:3006/api | API Referenz |
| https://macmini:3006/guides | Guides |
| https://macmini:3006/changelog | Changelog |

**Hinweis:** Das Developer Portal läuft als `bp-compliance-developer-portal` im Compose-Projekt `breakpilot-compliance` auf Port 3006 (via `bp-core-nginx`).

### Interne Dienste

| URL | Service |
|-----|---------|
| http://macmini:8200/ | Vault UI (Secrets) |
| http://macmini:8025/ | Mailpit (E-Mail Dev) |
| http://macmini:9001/ | MinIO Console (S3) |
| http://macmini:3003/ | Gitea (Git-Server) |
| http://macmini:8090/ | Woodpecker CI |
| http://macmini:8089/ | Camunda (BPMN) |
| http://macmini:8096/ | Night Scheduler API |
| http://macmini:8009/ | MkDocs (Projekt-Doku) |

### AI Tools (Admin v2)

| URL | Tool | Beschreibung |
|-----|------|--------------|
| https://macmini:3002/ai/llm-compare | LLM Vergleich | KI-Provider vergleichen |
| https://macmini:3002/ai/ocr-compare | OCR Vergleich | OCR-Methoden & Vokabel-Extraktion |
| https://macmini:3002/ai/ocr-labeling | OCR Labeling | Trainingsdaten erstellen |
| https://macmini:3002/ai/test-quality | Test Quality (BQAS) | Golden Suite & Tests |
| https://macmini:3002/ai/gpu | GPU Infrastruktur | vast.ai Management |
| https://macmini:3002/ai/rag-pipeline | RAG Pipeline | Retrieval Augmented Generation |
| https://macmini:3002/ai/magic-help | Magic Help | KI-Assistent |

### Lehrer-Tools (Studio v2)

| URL | Tool | Beschreibung |
|-----|------|--------------|
| https://macmini/vocab-worksheet | Vokabel-Arbeitsblatt | OCR-Scan & Arbeitsblatt-Generator |
| https://macmini/korrektur | Korrekturplattform | Abiturklausur-Korrektur |
| https://macmini:8000/app | Dashboard (alt) | Altes Dashboard |

---

## Services

### Kern-Applikationen

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `studio-v2` | Next.js | 443 | Lehrer-/Schüler-Studio |
| `admin-v2` | Next.js | 3002 | Admin-Dashboard |
| `website` | Next.js | 3000 | Öffentliche Website |
| `backend` | Python/FastAPI | 8000 | API Backend |
| `consent-service` | Go/Gin | 8081 | Consent-Management |

### Bildungs-Services

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `klausur-service` | Python/FastAPI | 8086 | Prüfungen, OCR, RAG |
| `school-service` | Python | 8082 | Schulverwaltung |
| `edu-search-service` | Python | 8088 | Bildungssuche |
| `geo-service` | Python | 8084 | Geo-Daten (PostGIS) |
| `voice-service` | Python | 8091 | Spracheingabe |

### KI & Compliance

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `ai-compliance-sdk` | Python | 8093 | DSGVO-konforme KI-Nutzung |
| `embedding-service` | Python | 8083 | Text-Embeddings |
| `paddleocr-service` | Python | - | OCR für Dokumente |
| `transcription-worker` | Python | - | Audio-Transkription |

### Compliance (breakpilot-compliance Projekt)

| Service | Tech | Port | Container |
|---------|------|------|-----------|
| `developer-portal` | Next.js | 3006 | `bp-compliance-developer-portal` |
| `compliance-admin` | Next.js | - | `bp-compliance-admin` |
| `compliance-backend` | Go | - | `bp-compliance-backend` |
| `compliance-ai-sdk` | Go | 8090 | `bp-compliance-ai-sdk` |

### Kommunikation

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `jitsi-web` | Jitsi | 8443 | Videokonferenzen |
| `jitsi-xmpp` | Prosody | - | XMPP Server |
| `jitsi-jicofo` | Jicofo | - | Konferenz-Fokus |
| `jitsi-jvb` | JVB | 8080 | Video Bridge |
| `jibri` | Jibri | - | Aufnahme/Streaming |
| `synapse` | Matrix | 8008 | Chat-Server |

### Datenbanken & Storage

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `postgres` | PostGIS 16 | 5432 | Hauptdatenbank |
| `valkey` | Valkey 8 | 6379 | Session-Cache (Redis-Fork) |
| `qdrant` | Qdrant | 6333/6334 | Vektordatenbank |
| `minio` | MinIO | 9000/9001 | S3-kompatibler Storage |

### Infrastructure & DevOps

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `nginx` | Nginx | 80/443 | Reverse Proxy + TLS (in breakpilot-core!) |
| `vault` | HashiCorp Vault | 8200 | Secrets Management |
| `vault-agent` | Vault | - | Zertifikatserneuerung |
| `gitea` | Gitea | 3003 | Git-Server |
| `woodpecker-server` | Woodpecker | 8090 | CI/CD Server |
| `woodpecker-agent` | Woodpecker | - | CI/CD Agent |
| `night-scheduler` | Python/FastAPI | 8096 | Auto-Shutdown/Startup |
| `mailpit` | Mailpit | 8025/1025 | E-Mail (Dev) |

### ERP

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `erpnext-frontend` | ERPNext | 8009 | ERP Frontend |
| `erpnext-backend` | ERPNext | - | ERP Backend |
| `erpnext-db` | MariaDB | - | ERP Datenbank |

### DSMS (Data Sharing)

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `dsms-node` | Node.js | 4001/5001 | IPFS Node |
| `dsms-gateway` | Node.js | 8085 | IPFS Gateway |

### Prozesse

| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `camunda` | Camunda | 8089 | BPMN Engine |

---

## Tech-Stack nach Sprache

### Go
- `consent-service`: Gin, GORM, JWT

### Python
- `backend`: FastAPI, SQLAlchemy, Pydantic
- `klausur-service`: FastAPI, PaddleOCR, RAG
- `ai-compliance-sdk`: FastAPI, Langfuse
- `embedding-service`: FastAPI, Sentence-Transformers
- `voice-service`: FastAPI, Whisper
- `geo-service`: FastAPI, PostGIS
- `school-service`: FastAPI
- `night-scheduler`: FastAPI

### TypeScript/Next.js
- `studio-v2`: Next.js 15, React, TailwindCSS
- `admin-v2`: Next.js 15, React, TailwindCSS
- `website`: Next.js 14
- `developer-portal`: Next.js, React, TailwindCSS (in breakpilot-compliance)

### Node.js
- `dsms-node`: IPFS
- `dsms-gateway`: Express

---

## Verzeichnisstruktur

```
breakpilot-pwa/
├── .claude/                  # Claude-Konfiguration
│   ├── CLAUDE.md            # Diese Datei
│   ├── rules/               # Automatische Regeln
│   │   ├── testing.md
│   │   ├── documentation.md
│   │   ├── night-scheduler.md
│   │   ├── open-source-policy.md
│   │   ├── compliance-checklist.md
│   │   ├── abiturkorrektur.md
│   │   ├── vocab-worksheet.md
│   │   ├── multi-agent-architecture.md
│   │   └── experimental-dashboard.md
│   └── settings.json
├── admin-v2/                 # Admin Dashboard (Next.js)
├── studio-v2/                # Lehrer-/Schüler-Studio (Next.js)
├── website/                  # Öffentliche Website (Next.js)
├── developer-portal/         # Developer Portal (Next.js, auch in breakpilot-compliance)
├── backend/                  # Python Backend (FastAPI)
├── consent-service/          # Go Consent Service
├── klausur-service/          # Klausur/OCR Service
├── ai-compliance-sdk/        # KI-Compliance SDK
├── breakpilot-compliance-sdk/ # Compliance SDK (Monorepo)
├── voice-service/            # Spracheingabe
├── geo-service/              # Geo-Daten
├── school-service/           # Schulverwaltung
├── edu-search-service/       # Bildungssuche
├── night-scheduler/          # Auto-Shutdown
├── nginx/                    # Reverse Proxy Config
├── vault/                    # Vault Config
├── docs-src/                 # MKDocs Quellen
├── docs-site/                # MKDocs Build
├── docker-compose.yml        # Haupt-Docker-Config
└── mkdocs.yml                # MKDocs Config
```

**Entfernte/nicht mehr aktive Verzeichnisse (in .gitignore blockiert):**
- `BreakpilotDrive/` — altes Unity-Projekt, nicht mehr in Entwicklung
- `billing-service/` — nicht benötigt

---

## Dokumentation (MKDocs)

**Live-URL:** https://macmini:3002/development/docs
**Quellen:** `/docs-src/`
**Build:** `/docs-site/`
**Config:** `mkdocs.yml`

### Dokumentation bearbeiten

```bash
# MKDocs lokal starten (Live-Reload)
cd /Users/benjaminadmin/Projekte/breakpilot-pwa
mkdocs serve -a 0.0.0.0:8008

# Build
mkdocs build
```

### Struktur

- `docs-src/index.md` - Startseite
- `docs-src/architecture/` - Architektur-Docs
- `docs-src/services/` - Service-Dokumentation
- `docs-src/api/` - API-Dokumentation
- `docs-src/development/` - Entwickler-Guides

---

## Häufige Befehle

### Docker (via SSH auf Mac Mini)

```bash
# Alle Services starten (breakpilot-pwa)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml up -d"

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

# Logs anzeigen
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml logs -f <service-name>"

# Status aller Container
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml ps"

# Developer Portal (in breakpilot-compliance!)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml build --no-cache developer-portal"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml up -d developer-portal"

# Nginx (in breakpilot-core!)
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml restart nginx"
```

**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-PATH bei SSH).

### Tests (via SSH)

```bash
# Go Tests (Consent Service)
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/consent-service && go test -v ./..."

# Python Tests
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/backend && source venv/bin/activate && pytest -v"
```

### Git

```bash
# Zwei Remotes konfiguriert - IMMER zu beiden pushen!
# origin: http://macmini:3003/pilotadmin/breakpilot-pwa.git (lokale Gitea auf Mac Mini)
# gitea:  git@gitea.meghsakha.com:Benjamin_Boenisch/breakpilot-pwa.git (externer Gitea-Server)

# Push zu beiden Remotes (PFLICHT bei jedem Push):
git push origin main && git push gitea main

# Git-Befehle auf Mac Mini ausfuehren (ohne cd):
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-pwa status"
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-pwa pull --no-rebase origin main"
```

---

## Rollen & Berechtigungen

| Rolle | Beschreibung |
|-------|--------------|
| `user` | Normaler Benutzer (Schüler/Lehrer) |
| `admin` | Administrator |
| `data_protection_officer` | Datenschutzbeauftragter |
| `school_admin` | Schuladministrator |

---

## Compliance & Sicherheit

### DSGVO
- Consent-Management via `consent-service`
- Datenexport-Funktionen
- Löschkonzept implementiert

### AI Act
- `ai-compliance-sdk` für konforme KI-Nutzung
- Risikobewertung für KI-Funktionen
- Audit-Logging

### BSI
- BSI-TR-03161 Dokumentation vorhanden
- Security-Scanning in CI/CD

---

## Sensitive Dateien

**NIEMALS ändern oder committen:**
- `.env`, `.env.local`, `.env.backup`
- `secrets/`
- Vault-Tokens
- SSL-Zertifikate

**NIEMALS ins Git laden (via .gitignore blockiert):**
- `*.pdf`, `*.docx`, `*.xlsx`, `*.pptx` — Dokumente bleiben nur lokal auf dem Mac Mini
- Kompilierte Go-Binaries (`consent-service/server`, etc.)
- Große Mediendateien (Videos, Audio, Bilder >1 MB)
- `BreakpilotDrive/` — altes Unity-Projekt
- `billing-service/` — nicht benötigt

**Hinweis:** Die Git-History wurde am 2026-02-12 mit `git-filter-repo` bereinigt. Alle PDFs, Word-/Excel-Dateien, BreakpilotDrive/ und billing-service/ wurden aus der gesamten History entfernt. Das Repo ging dadurch von 1.7 GB auf 11 MB.

---

## Ansprechpartner

- **Git-Server:** http://macmini:3003 (Gitea)
- **CI/CD:** http://macmini:8090 (Woodpecker)
- **Issue-Tracker:** Gitea Issues