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

BreakPilot PWA - System-Architektur

Übersicht

BreakPilot ist eine modulare Bildungsplattform für Lehrkräfte mit folgenden Hauptkomponenten:

┌─────────────────────────────────────────────────────────────────────┐
│                           Browser                                    │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                  Frontend (Studio UI)                          │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │  │
│  │  │Dashboard │ │Worksheets│ │Correction│ │Letters/Companion │  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────────────┘
                            │ HTTP/REST
                            ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Python Backend (FastAPI)                          │
│                         Port 8000                                    │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                      API Layer                                  │ │
│  │  /api/worksheets  /api/corrections  /api/letters  /api/state   │ │
│  │  /api/school      /api/certificates /api/messenger /api/jitsi  │ │
│  └────────────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                    Service Layer                                │ │
│  │  FileProcessor │ PDFService │ ContentGenerators │ StateEngine  │ │
│  └────────────────────────────────────────────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
┌─────────────────┐ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│  Go Consent     │ │  PostgreSQL   │ │  LLM Gateway │ │  HashiCorp   │
│  Service        │ │  Database     │ │  (optional)  │ │  Vault       │
│  Port 8081      │ │  Port 5432    │ │              │ │  Port 8200   │
└─────────────────┘ └───────────────┘ └──────────────┘ └──────────────┘

Komponenten

1. Admin Frontend (Next.js Website)

Das Admin Frontend ist eine vollständige Next.js 15 Anwendung für Developer und Administratoren:

Technologie: Next.js 15, React 18, TypeScript, Tailwind CSS

Container: breakpilot-pwa-website auf Port 3000

Verzeichnis: /website

Modul	Route	Beschreibung
Dashboard	/admin	Übersicht & Statistiken
GPU Infrastruktur	/admin/gpu	vast.ai GPU Management
Consent Verwaltung	/admin/consent	Rechtliche Dokumente & Versionen
Datenschutzanfragen	/admin/dsr	DSGVO Art. 15-21 Anfragen
DSMS	/admin/dsms	Datenschutz-Management-System
Education Search	/admin/edu-search	Bildungsquellen & Crawler
Personensuche	/admin/staff-search	Uni-Mitarbeiter & Publikationen
Uni-Crawler	/admin/uni-crawler	Universitäts-Crawling Orchestrator
LLM Vergleich	/admin/llm-compare	KI-Provider Vergleich
PCA Platform	/admin/pca-platform	Bot-Erkennung & Monetarisierung
Production Backlog	/admin/backlog	Go-Live Checkliste
Developer Docs	/admin/docs	API & Architektur Dokumentation
Kommunikation	/admin/communication	Matrix & Jitsi Monitoring
Security	/admin/security	DevSecOps Dashboard, Scans, Findings
SBOM	/admin/sbom	Software Bill of Materials

2. Lehrer Frontend (Studio UI)

Das Lehrer Frontend ist ein Single-Page-Application-ähnliches System für Lehrkräfte, das in Python-Modulen organisiert ist:

Modul	Datei	Beschreibung
Base	frontend/modules/base.py	TopBar, Sidebar, Theme, Login
Dashboard	frontend/modules/dashboard.py	Übersichtsseite
Worksheets	frontend/modules/worksheets.py	Lerneinheiten-Generator
Correction	frontend/modules/correction.py	OCR-Klausurkorrektur
Letters	frontend/modules/letters.py	Elternkommunikation
Companion	frontend/modules/companion.py	Begleiter-Modus mit State Engine
School	frontend/modules/school.py	Schulverwaltung
Gradebook	frontend/modules/gradebook.py	Notenbuch
ContentCreator	frontend/modules/content_creator.py	H5P Content Creator
ContentFeed	frontend/modules/content_feed.py	Content Discovery
Messenger	frontend/modules/messenger.py	Matrix Messenger
Jitsi	frontend/modules/jitsi.py	Videokonferenzen
KlausurKorrektur	frontend/modules/klausur_korrektur.py	Abitur-Klausurkorrektur (15-Punkte-System)
AbiturDocsAdmin	frontend/modules/abitur_docs_admin.py	Admin für Abitur-Dokumente (NiBiS)

Jedes Modul exportiert:

• get_css() - CSS-Styles
• get_html() - HTML-Template
• get_js() - JavaScript-Logik

3. Python Backend (FastAPI)

API-Router

Router	Präfix	Beschreibung
worksheets_api	/api/worksheets	Content-Generatoren (MC, Cloze, Mindmap, Quiz)
correction_api	/api/corrections	OCR-Pipeline für Klausurkorrektur
letters_api	/api/letters	Elternbriefe mit GFK-Integration
state_engine_api	/api/state	Begleiter-Modus Phasen & Vorschläge
school_api	/api/school	Schulverwaltung (Proxy zu school-service)
certificates_api	/api/certificates	Zeugniserstellung
messenger_api	/api/messenger	Matrix Messenger Integration
jitsi_api	/api/jitsi	Jitsi Meeting-Einladungen
consent_api	/api/consent	DSGVO Consent-Verwaltung
gdpr_api	/api/gdpr	GDPR-Export
klausur_korrektur_api	/api/klausur-korrektur	Abitur-Klausuren (15-Punkte, Gutachten, Fairness)
abitur_docs_api	/api/abitur-docs	NiBiS-Dokumentenverwaltung für RAG

Services

Service	Datei	Beschreibung
FileProcessor	services/file_processor.py	OCR mit PaddleOCR
PDFService	services/pdf_service.py	PDF-Generierung
ContentGenerators	services/content_generators/	MC, Cloze, Mindmap, Quiz
StateEngine	state_engine/	Phasen-Management & Antizipation

4. Klausur-Korrektur System (Abitur)

Das Klausur-Korrektur-System implementiert die vollständige Abitur-Bewertungspipeline:

┌─────────────────────────────────────────────────────────────────────┐
│                    Klausur-Korrektur Modul                          │
│                                                                     │
│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐    │
│  │ Modus-Wahl  │───►│ Text-Quellen &   │───►│ Erwartungs-     │    │
│  │ LandesAbi/  │    │ Rights-Gate      │    │ horizont        │    │
│  │ Vorabitur   │    └──────────────────┘    └─────────────────┘    │
│  └─────────────┘                                      │            │
│                                                       ▼            │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   Schülerarbeiten-Pipeline                   │   │
│  │  Upload → OCR → KI-Bewertung → Gutachten → 15-Punkte-Note   │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                       │            │
│                                                       ▼            │
│  ┌────────────────────┐    ┌──────────────────────────────────┐   │
│  │ Erst-/Zweitprüfer  │───►│ Fairness-Analyse & PDF-Export   │   │
│  └────────────────────┘    └──────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

15-Punkte-Notensystem

Das System verwendet den deutschen Abitur-Notenschlüssel:

Punkte	Prozent	Note
15-13	95-85%	1+/1/1-
12-10	80-70%	2+/2/2-
9-7	65-55%	3+/3/3-
6-4	50-40%	4+/4/4-
3-1	33-20%	5+/5/5-
0	<20%	6

Bewertungskriterien

Kriterium	Gewicht	Beschreibung
Rechtschreibung	15%	Orthografie
Grammatik	15%	Grammatik & Syntax
Inhalt	40%	Inhaltliche Qualität (höchste Gewichtung)
Struktur	15%	Aufbau & Gliederung
Stil	15%	Ausdruck & Stil

5. Go Consent Service

Verwaltet DSGVO-Einwilligungen:

consent-service/
├── cmd/server/        # Main entry point
├── internal/
│   ├── handlers/      # HTTP Handler
│   ├── services/      # Business Logic
│   ├── models/        # Data Models
│   └── middleware/    # Auth Middleware
└── migrations/        # SQL Migrations

6. LLM Gateway (Optional)

Wenn LLM_GATEWAY_ENABLED=true:

llm_gateway/
├── routes/
│   ├── chat.py            # Chat-Completion API
│   ├── communication.py   # GFK-Validierung
│   ├── edu_search_seeds.py # Bildungssuche
│   └── legal_crawler.py   # Schulgesetz-Crawler
└── services/
    └── communication_service.py

Datenfluss

Worksheet-Generierung

User Input → Frontend (worksheets.py)
    ↓
POST /api/worksheets/generate/multiple-choice
    ↓
worksheets_api.py → MCGenerator (services/content_generators/)
    ↓
Optional: LLM für erweiterte Generierung
    ↓
Response: WorksheetContent → Frontend rendert Ergebnis

Klausurkorrektur

File Upload → Frontend (correction.py)
    ↓
POST /api/corrections/ (erstellen)
POST /api/corrections/{id}/upload (Datei)
    ↓
Background Task: OCR via FileProcessor
    ↓
Poll GET /api/corrections/{id} bis status="ocr_complete"
    ↓
POST /api/corrections/{id}/analyze
    ↓
Review Interface → PUT /api/corrections/{id} (Anpassungen)
    ↓
GET /api/corrections/{id}/export-pdf

Sicherheit

Authentifizierung & Autorisierung

BreakPilot verwendet einen Hybrid-Ansatz:

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

Siehe: Auth-System

Basis-Rollen

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

Erweiterte Rollen (rbac.py)

15+ domaenenspezifische Rollen fuer Klausurkorrektur und Zeugnisse:

• erstkorrektor, zweitkorrektor, drittkorrektor
• klassenlehrer, fachlehrer, fachvorsitz
• schulleitung, zeugnisbeauftragter, sekretariat

Sicherheitsfeatures

• JWT-basierte Authentifizierung (RS256/HS256)
• CORS konfiguriert für Frontend-Zugriff
• DSGVO-konformes Consent-Management
• HashiCorp Vault fuer Secrets-Management (keine hardcodierten Secrets)
• Bundesland-spezifische Policy-Sets
• DevSecOps Pipeline mit automatisierten Security-Scans (SAST, SCA, Secrets Detection)

Siehe:

• Secrets Management
• DevSecOps

Deployment

services:
  backend:
    build: ./backend
    ports: ["8000:8000"]
    environment:
      - DATABASE_URL=postgresql://...
      - LLM_GATEWAY_ENABLED=false

  consent-service:
    build: ./consent-service
    ports: ["8081:8081"]

  postgres:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data

Erweiterung

Neues Frontend-Modul hinzufügen:

1. Modul erstellen: frontend/modules/new_module.py
2. Klasse mit get_css(), get_html(), get_js() implementieren
3. In frontend/modules/__init__.py importieren und exportieren
4. Optional: Zugehörige API in new_module_api.py erstellen
5. In main.py Router registrieren