# BreakPilot Portal

Projekt-Frontends & Dokumentation

Projekte
Lehrer

### Admin Lehrer

Verwaltung, AI Tools, Klausuren

macmini:3002

### Studio v2

Lehrer- und Schueler-Interface

macmini

### Website

Oeffentliche BreakPilot Website

macmini:3000

### Dokumentation

Klausur, Voice, Agent-Core, Studio

macmini:8010
Compliance

### Compliance SDK

DSGVO, Audit, GRC — Alle SDK-Module

macmini:3007/sdk

### Comply Website

Marketing-Website fuer den KI Compliance Hub

macmini:3010/compliance-hub

### Pitch Deck

Interaktives Investor Pitch Deck — ComplAI

macmini:3012

### Dokumentation

AI-SDK, Auditor-Doku, SBOM

macmini:8011
Core

### Admin Core

Infrastruktur, Services, Monitoring

macmini:3008/dashboard

### Dokumentation

Architektur, Auth, DevSecOps, RAG

macmini:8009

## Architektur-Uebersicht

BreakPilot besteht aus zwei Plattformen:

- Lehrer KI-Plattform fuer Lehrer — Unterrichtsvorbereitung, Klausurkorrektur, Sprachassistenz, OCR-Tools
- Compliance KI Compliance Hub fuer Unternehmen — umfasst:
  - DSGVO-Compliance-SDK (VVT, DSFA, TOM, Loeschfristen, Vendor-Compliance)
  - Datenschutzkonformer KI-Chat auf europaeischen Servern
  - Edge-Hardware-Loesung zum Self-Hosting (Mac Mini / Mac Studio)
  - Software-Compliance fuer automatisierte Risikobeurteilungen (Anlagen- & Maschinensoftware / Firmware) — in Entwicklung
  - Integrierter KI Embedded Code Assistant — in Entwicklung

Technisch aufgeteilt in 3 Projekte mit insgesamt ~35 Docker-Containern auf einem Mac Mini M4 Pro.

### Die 3 Projekte

Core `breakpilot-core`

Infrastruktur & gemeinsame Dienste: PostgreSQL, Valkey, MinIO, Qdrant, Vault, Nginx, Gitea, Woodpecker CI, Jitsi, Embedding-Service, RAG-Service, Night-Scheduler, Health-Aggregator.

~25 Container
Lehrer `breakpilot-lehrer`

Lehrer- & Schueler-Funktionen: Studio v2, Admin Lehrer, Website, Klausur-Service (OCR, Korrektur, Vocab), School-Service, Backend Lehrer.

~7 Container
Compliance `breakpilot-compliance`

Datenschutz & GRC: Admin Compliance (SDK), Backend Compliance, AI Compliance SDK, DSFA, VVT, TOM, Loeschfristen, Vendor-Compliance.

~3 Container

### Frontends

URL | Projekt | Beschreibung
--- | --- | ---
macmini | Lehrer | Studio v2 (Lehrer-/Schueler-Interface)
macmini:3000 | Lehrer | Website (oeffentlich)
macmini:3002 | Lehrer | Admin Lehrer (Dashboard, AI-Tools, Architektur)
macmini:3008 | Core | Admin Core (Infrastruktur, Services, Monitoring)
macmini:3007 | Compliance | Admin Compliance (SDK, DSFA, VVT, TOM)
macmini:8443 | Core | Jitsi Meet (Videokonferenzen)

### Backend-APIs

URL | Projekt | Beschreibung
--- | --- | ---
macmini:8000 | Core | Backend Core (Auth, RBAC, Notifications)
macmini:8001 | Lehrer | Backend Lehrer (Classroom, Units, Meetings)
macmini:8002 | Compliance | Backend Compliance (DSGVO, DSR, Consent)
macmini:8086 | Lehrer | Klausur-Service (OCR, Korrektur, Vocab)
macmini:8093 | Compliance | AI Compliance SDK API
macmini:8097 | Core | RAG-Service (Vektorsuche)

### Interne Dienste

URL | Beschreibung
--- | ---
macmini:3003 | Gitea (Git-Server)
macmini:8090 | Woodpecker CI
macmini:8200 | Vault (Secrets)
macmini:8025 | Mailpit (E-Mail Dev)
macmini:9001 | MinIO Console (S3)
macmini:8096 | Night Scheduler API
macmini:8099 | Health Aggregator

### Git Repositories

Repository | Lokal (Gitea) | Extern (Gitea)
--- | --- | ---
breakpilot-core | macmini:3003/.../breakpilot-core | gitea.meghsakha.com/.../breakpilot-core
breakpilot-lehrer | macmini:3003/.../breakpilot-lehrer | gitea.meghsakha.com/.../breakpilot-lehrer
breakpilot-compliance | macmini:3003/.../breakpilot-compliance | gitea.meghsakha.com/.../breakpilot-compliance

### Was hat sich gegenueber dem Monorepo geaendert?

:3002 = Admin (Lehrer + SDK) → :3002 = Nur Lehrer, :3007 = Compliance (eigenes Frontend)
1 Backend auf :8000 → 3 Backends: :8000 (Core), :8001 (Lehrer), :8002 (Compliance)
RAG war im Klausur-Service → :8097 = Eigener RAG-Service
1 MkDocs auf :8009 → 3 MkDocs: :8009 (Core), :8010 (Lehrer), :8011 (Compliance)
Kein Health-Monitoring → :8099 = Health Aggregator (NEU)

### Routing (Nginx)

Alle HTTPS-Ports laufen ueber `bp-core-nginx` (aus breakpilot-core). Nginx terminiert TLS mit Vault-Zertifikaten und leitet an die jeweiligen Container weiter. Die internen Dienste (Gitea, Mailpit, MinIO etc.) sind nur ueber HTTP erreichbar.

### Hardware (Mac Mini M4 Pro)

System

Chip | Apple M4 Pro
CPU-Kerne | 14 (10 Performance + 4 Efficiency)
GPU-Kerne | 20 (Metal 3)
RAM | 64 GB Unified Memory
SSD | 1,8 TB (davon ~1,5 TB frei)
macOS | Darwin 24.6.0

Ressourcen-Verteilung

Die 64 GB Unified Memory werden geteilt zwischen Docker (~35 Container), Ollama (LLM-Inference) und dem System. Bei grossen Modellen (32B+ Parameter) belegt Ollama ~20 GB RAM waehrend der Inference.

Der M4 Pro nutzt Unified Memory — CPU und GPU teilen sich den RAM. Das ermoeglicht grosse LLM-Modelle ohne dedizierte GPU.

### KI-Modelle (Ollama)

Lokal auf dem Mac Mini via `http://macmini:11434`. Modelle werden ueber die Ollama API geladen.

Modell | Parameter | Groesse | Quantisierung | Einsatz
--- | --- | --- | --- | ---
qwen3:30b-a3b | 30,5 Mrd. (3,3 Mrd. aktiv) | 17,3 GB | Q4_K_M | Compliance Haupt-LLM fuer Advisor, SDK, DSFA, VVT (MoE)
qwen2.5vl:32b | 33,5 Mrd. | 19,7 GB | Q4_K_M | Lehrer Vision-Language-Modell fuer Bildanalyse
llama3.2-vision:11b | 10,7 Mrd. | 7,3 GB | Q4_K_M | Lehrer Vision-Modell fuer OCR, Bildanalyse
llama3.2:latest | 3,2 Mrd. | 1,9 GB | Q4_K_M | Leichtgewichtig, Schnelltests, Fallback

Gesamt-Speicherbedarf aller Modelle: ~54,6 GB auf Disk. Waehrend der Inference wird jeweils nur das aktive Modell in den RAM geladen. Bei gleichzeitiger Nutzung mehrerer Modelle steigt der RAM-Bedarf entsprechend.

# Modelle verwalten curl http://macmini:11434/api/tags # Installierte Modelle anzeigen curl http://macmini:11434/api/pull -d '{"name":"model:tag"}' # Neues Modell laden curl http://macmini:11434/api/delete -d '{"name":"model:tag"}'# Modell entfernen

## Entwickler-Schnelleinstieg

Alles was du brauchst, um in 15 Minuten produktiv zu sein.

### 1. Voraussetzungen

Du brauchst nur ein MacBook im lokalen Netzwerk. Alle Services laufen auf dem Mac Mini.

1

#### SSH-Zugang testen

Terminal oeffnen und `ssh macmini` ausfuehren. Kein Passwort noetig (Key-Auth).

2

#### Repos klonen

Auf dem Mac Mini unter `/Users/benjaminadmin/Projekte/` liegen alle 3 Projekte.

3

#### Browser oeffnen

HTTPS-Zertifikate sind selbstsigniert — beim ersten Besuch im Browser akzeptieren.

4

#### Dokumentation lesen

Jedes Projekt hat ein `CLAUDE.md` und `.claude/rules/` mit allen Details.

# Repos klonen (auf Mac Mini) cd /Users/benjaminadmin/Projekte git clone http://localhost:3003/pilotadmin/breakpilot-core.git git clone http://localhost:3003/pilotadmin/breakpilot-lehrer.git git clone http://localhost:3003/pilotadmin/breakpilot-compliance.git

### 2. Tech Stack

#### Core Infrastruktur

Python / FastAPI Go / Gin PostgreSQL 16 Valkey (Redis) Qdrant MinIO (S3) Vault Nginx

#### Lehrer EdTech

Next.js 15 React TailwindCSS Python / FastAPI PaddleOCR Whisper

#### Compliance GRC

Next.js 15 React TailwindCSS Go / Gin Ollama / qwen2.5 RAG

### 3. Entwicklungs-Workflow

Der typische Zyklus: Code aendern → Container bauen → deployen → testen.

# WICHTIG: Docker-Pfad auf Mac Mini ist /usr/local/bin/docker # Kurzform: DC = docker compose mit Pfad # ── Beispiel: Aenderung am Compliance-Admin deployen ── # 1. Container bauen ssh macmini "/usr/local/bin/docker compose \ -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml \ build --no-cache admin-compliance" # 2. Container deployen ssh macmini "/usr/local/bin/docker compose \ -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml \ up -d admin-compliance" # 3. Logs pruefen ssh macmini "/usr/local/bin/docker compose \ -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml \ logs -f admin-compliance"
# ── Git Workflow (IMMER zu beiden Remotes pushen!) ── # Status pruefen ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-compliance status" # Commit & Push zu beiden Remotes ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && \ git add -A && \ git commit -m 'feat: Beschreibung' && \ git push all main" # Pull (IMMER --no-rebase!) ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-compliance pull --no-rebase origin main"
# ── Nuetzliche Befehle ── # Alle Container anzeigen ssh macmini "/usr/local/bin/docker ps --format 'table {{.Names}}\t{{.Status}}'" # Container eines Projekts ssh macmini "/usr/local/bin/docker ps --format '{{.Names}} {{.Status}}' | grep bp-compliance" # In Container einloggen ssh macmini "/usr/local/bin/docker exec -it bp-compliance-admin sh" # Datenbank-Zugriff ssh macmini "/usr/local/bin/docker exec -it bp-core-postgres psql -U breakpilot -d breakpilot"

### 4. Docker-Compose Pfade

Projekt | Pfad
--- | ---
Core | `/Users/benjaminadmin/Projekte/breakpilot-core/docker-compose.yml`
Lehrer | `/Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml`
Compliance | `/Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml`

### 5. Haeufige Stolpersteine

- ⚠
  `docker: command not found` via SSH

  Docker ist nicht im SSH-PATH. Immer den vollen Pfad nutzen.

  Fix: `/usr/local/bin/docker` statt `docker`
- ⚠
  `cd` funktioniert nicht direkt via SSH

  Jeder SSH-Befehl startet in einer neuen Shell.

  Fix: `ssh macmini "cd /pfad && befehl"` oder `git -C /pfad`
- ⚠
  Ollama aus Docker-Containern nicht erreichbar

  Container koennen `localhost` des Hosts nicht direkt ansprechen.

  Fix: `http://host.docker.internal:11434` statt `http://localhost:11434`
- ⚠
  `git pull` zerstoert lokale Commits

  Rebase auf main mit vielen lokalen Commits fuehrt zu Datenverlust.

  Fix: Immer `git pull --no-rebase origin main`
- ⚠
  Healthcheck schlaegt fehl mit `localhost`

  IPv6-Aufloesung von `localhost` kann in Docker fehlschlagen.

  Fix: `127.0.0.1` statt `localhost` in Healthchecks
- ⚠
  Keine PDFs, DOCX oder Binaerdateien committen

  Das Repo wurde von 1.7 GB auf Normalgroesse bereinigt. Bitte sauber halten.

  Fix: `.gitignore` blockiert *.pdf, *.docx, *.xlsx, kompilierte Binaries

### 6. Zugaenge & Secrets

Alle Secrets liegen im HashiCorp Vault (macmini:8200). Niemals Passwoerter, Tokens oder API-Keys in Code oder Git committen.

Dienst | Zugang
--- | ---
Gitea (Git) | macmini:3003 — Credentials: siehe Vault unter `secret/gitea`
PostgreSQL | Via Container: `docker exec -it bp-core-postgres psql -U breakpilot`
MinIO (S3) | macmini:9001 — Credentials: siehe Vault unter `secret/minio`
Mailpit | macmini:8025 — Kein Login erforderlich (Dev-Tool)
Ollama (LLM) | `http://macmini:11434` — Kein Login, lokale Instanz

### 7. Regeln & Konventionen

#### Open Source Policy

Nur Lizenzen mit kommerzieller Nutzung erlaubt: MIT, Apache-2.0, BSD, ISC, MPL-2.0, LGPL. Verboten: GPL, AGPL, SSPL, proprietaer. Bei neuen Dependencies SBOM aktualisieren.

#### Tests sind Pflicht

Jede Code-Aenderung braucht Tests. Go: `go test ./...`, Python: `pytest -v`. Details in `.claude/rules/testing.md`.

#### DSGVO-Compliance

Bei neuen Features mit Nutzerdaten immer die Compliance-Checkliste durchgehen: Rechtsgrundlage, Datenminimierung, Betroffenenrechte. Siehe `.claude/rules/compliance-checklist.md`.

### 8. Ansprechpartner & Hilfe

Projekt-Owner: Benjamin Boenisch
Issues: Gitea Issues in den jeweiligen Repos
CI/CD: Woodpecker CI — Pipelines werden bei Push automatisch ausgefuehrt
Monitoring: Health Aggregator — Zeigt den Status aller Services