breakpilot-core/docs-src/architecture/system-architecture.md

BreakPilot - System-Architektur

Uebersicht

BreakPilot ist eine modulare Bildungs- und Compliance-Plattform, aufgeteilt in drei unabhaengige Docker Compose Projekte:

┌────────────────────────────────────────────────────────────────────────────┐
│                              Browser                                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Studio v2    │  │ Admin Lehrer │  │ Admin Compl. │  │ Dev Portal   │  │
│  │ (443)        │  │ (3002)       │  │ (3007)       │  │ (3006)       │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
└─────────┼──────────────────┼──────────────────┼──────────────────┼─────────┘
          │                  │                  │                  │
          ▼                  ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        bp-core-nginx (Reverse Proxy + TLS)                  │
│                   Ports: 80, 443, 3000-3008, 8000-8097                      │
└────────┬──────────────────┬──────────────────┬──────────────────────────────┘
         │                  │                  │
         ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ breakpilot-core │ │breakpilot-lehrer│ │breakpilot-compl.│
│   (Shared)      │ │   (Team A)      │ │   (Team B)      │
│                 │ │                 │ │                 │
│ PostgreSQL      │ │ Studio v2       │ │ Admin Compliance│
│ Valkey          │ │ Admin Lehrer    │ │ Developer Portal│
│ Vault           │ │ Website         │ │ Backend Compl.  │
│ Qdrant          │ │ Backend Lehrer  │ │ AI Compliance   │
│ MinIO           │ │ Klausur Service │ │   SDK (Go)      │
│ Embedding       │ │ Voice Service   │ │ DSMS (IPFS)     │
│ RAG Service     │ │ School Service  │ │ Document Crawler│
│ Consent (Go)    │ │ Geo Service     │ │                 │
│ Billing (Go)    │ │ PaddleOCR       │ │                 │
│ Backend Core    │ │ Agent Core      │ │                 │
│ Admin Core      │ │ Transcription   │ │                 │
│ Jitsi (5x)      │ │ BreakPilot Drive│ │                 │
│ Night Scheduler │ │                 │ │                 │
│ Health Agg.     │ │                 │ │                 │
│ Gitea Actions  │ │                 │ │                 │
│ ERP (optional)  │ │                 │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
         │                  │                  │
         └──────────────────┴──────────────────┘
                    breakpilot-network
                  (gemeinsames Docker-Netzwerk)

---

Drei-Projekt-Architektur

breakpilot-core (Shared Infrastructure)

Stellt gemeinsam genutzte Infrastruktur bereit. Beide Teams (Lehrer + Compliance) haengen von Core ab.

Container-Prefix: bp-core-*

Kategorie	Services
Datenbank & Cache	PostgreSQL (PostGIS 16), Valkey
Security	Vault, Vault-Init, Vault-Agent
AI/ML	Embedding Service, RAG Service, Qdrant
Storage	MinIO (S3)
Business Logic	Consent Service (Go), Billing Service (Go), Backend Core (Python)
Frontend	Admin Core (Next.js, Port 3008)
Networking	Nginx (Reverse Proxy + TLS)
Monitoring	Health Aggregator
DevOps	Gitea, Gitea Actions (act_runner), Night Scheduler, Mailpit
Kommunikation	Jitsi Meet (5 Container), Synapse (Matrix Chat)
ERP	ERPNext (optional, 9 Container)

breakpilot-lehrer (Team A: Bildung)

Alle Services fuer Lehrkraefte und den Bildungsbereich.

Container-Prefix: bp-lehrer-*

Service	Container	Port	Beschreibung
Admin Lehrer	bp-lehrer-admin	3002	Lehrer-Dashboard (Next.js)
Studio v2	bp-lehrer-studio-v2	443	Lehrer-/Schueler-Studio (Next.js)
Website	bp-lehrer-website	3000	Oeffentliche Website (Next.js)
Backend Lehrer	bp-lehrer-backend	8001	API Backend (Python/FastAPI)
Klausur Service	bp-lehrer-klausur-service	8086	Pruefungen, OCR, RAG (Python)
School Service	bp-lehrer-school-service	8084	Schulverwaltung (Go)
Voice Service	bp-lehrer-voice-service	8091	Spracheingabe (Python)
Geo Service	bp-lehrer-geo-service	8088	Geo-Daten/PostGIS (Python)
PaddleOCR	bp-lehrer-paddleocr	-	OCR Engine (Profil: ocr)
BreakPilot Drive	bp-lehrer-breakpilot-drive	-	Lernspiel (Profil: game)
Agent Core	bp-lehrer-agent-core	-	Multi-Agent System (Profil: dev)
Transcription Worker	bp-lehrer-transcription	-	Audio-Transkription (Profil: recording)

breakpilot-compliance (Team B: DSGVO/Compliance)

Alle Services fuer das Compliance-Produkt (DSGVO, AI Act, BSI).

Container-Prefix: bp-compliance-*

Service	Container	Port	Beschreibung
Admin Compliance	bp-compliance-admin	3007	Compliance-Dashboard (Next.js)
Developer Portal	bp-compliance-developer-portal	3006	API-Dokumentation (Next.js)
Backend Compliance	bp-compliance-backend	8002	Compliance API (Python/FastAPI)
AI Compliance SDK	bp-compliance-ai-sdk	8090/8093	DSGVO-konforme KI (Go)
DSMS Node	bp-compliance-dsms-node	4001/5001	IPFS Node
DSMS Gateway	bp-compliance-dsms-gateway	8082	IPFS Gateway (Node.js)
Document Crawler	bp-compliance-document-crawler	8098	Web-Crawler (Python)

---

Netzwerk-Architektur

Gemeinsames Docker-Netzwerk

Alle drei Projekte nutzen dasselbe Docker-Netzwerk breakpilot-network:

# In jedem docker-compose.yml:
networks:
  breakpilot-network:
    external: true

Container koennen sich gegenseitig ueber ihre Container-Namen erreichen:

• bp-lehrer-backend → bp-core-postgres:5432
• bp-compliance-ai-sdk → bp-core-qdrant:6333
• bp-core-nginx → bp-lehrer-studio-v2:3001

Nginx Routing

Der zentrale Nginx in Core routet alle Anfragen an die richtigen Container:

Port	Upstream	Projekt
443	bp-lehrer-studio-v2:3001 + Jitsi	Lehrer + Core
3000	bp-lehrer-website:3000	Lehrer
3002	bp-lehrer-admin:3000	Lehrer
3006	bp-compliance-developer-portal:3000	Compliance
3007	bp-compliance-admin:3000	Compliance
3008	bp-core-admin:3000	Core
8000	bp-core-backend:8000	Core
8001	bp-lehrer-backend:8001	Lehrer
8002	bp-compliance-backend:8002	Compliance
8086	bp-lehrer-klausur-service:8086	Lehrer
8091	bp-lehrer-voice-service:8091	Lehrer
8093	bp-compliance-ai-sdk:8090	Compliance
8443	bp-core-jitsi-web:80	Core

---

Sicherheit

Authentifizierung & Autorisierung

Schicht	Komponente	Beschreibung
Authentifizierung	Keycloak (Prod) / Lokales JWT (Dev)	Token-Validierung via JWKS oder HS256
Autorisierung	RBAC (Eigenentwicklung)	Domaenenspezifische Berechtigungen

Basis-Rollen

Rolle	Beschreibung
user	Normaler Benutzer
teacher / lehrer	Lehrkraft
admin	Administrator
data_protection_officer	Datenschutzbeauftragter

Sicherheitsfeatures

• JWT-basierte Authentifizierung (RS256/HS256)
• CORS konfiguriert pro Service
• DSGVO-konformes Consent-Management (Core)
• HashiCorp Vault fuer Secrets-Management
• DevSecOps Pipeline mit Trivy, Semgrep, Gitleaks

Siehe:

• Auth-System
• Secrets Management
• DevSecOps

---

Deployment

Start-Reihenfolge

# 1. Core zuerst (Infrastruktur)
docker compose -f breakpilot-core/docker-compose.yml up -d

# 2. Lehrer-Stack
docker compose -f breakpilot-lehrer/docker-compose.yml up -d

# 3. Compliance-Stack
docker compose -f breakpilot-compliance/docker-compose.yml up -d

Health-Checks

# Core Health (alle Infrastruktur-Services)
curl https://macmini:8099/health

# Lehrer Backend
curl https://macmini:8001/health

# Compliance Backend
curl https://macmini:8002/health

# AI SDK
curl https://macmini:8093/health

---

Erweiterung

Neuen Service zu einem Projekt hinzufuegen

1. Service-Definition in das jeweilige docker-compose.yml hinzufuegen
2. Container-Name mit dem richtigen Prefix versehen (bp-core-*, bp-lehrer-*, bp-compliance-*)
3. Netzwerk breakpilot-network zuweisen
4. Falls HTTPS noetig: Nginx-Route in breakpilot-core/nginx/conf.d/default.conf hinzufuegen
5. Dokumentation in der jeweiligen MkDocs-Instanz aktualisieren