BreakPilot Portal

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.

SSH-Zugang testen

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

Repos klonen

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

Browser oeffnen

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

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

BreakPilot Portal

Admin Lehrer

Studio v2

Website

Dokumentation

Compliance SDK

Comply Website

Pitch Deck

Dokumentation

Admin Core

Dokumentation

Architektur-Uebersicht

Die 3 Projekte

Frontends

Backend-APIs

Interne Dienste

Git Repositories

Was hat sich gegenueber dem Monorepo geaendert?

Routing (Nginx)

Hardware (Mac Mini M4 Pro)

KI-Modelle (Ollama)

Entwickler-Schnelleinstieg

1. Voraussetzungen

SSH-Zugang testen

Repos klonen

Browser oeffnen

Dokumentation lesen

2. Tech Stack

Core Infrastruktur

Lehrer EdTech

Compliance GRC

3. Entwicklungs-Workflow

4. Docker-Compose Pfade

5. Haeufige Stolpersteine

6. Zugaenge & Secrets

7. Regeln & Konventionen

Open Source Policy

Tests sind Pflicht

DSGVO-Compliance

8. Ansprechpartner & Hilfe