breakpilot-pwa/docs/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

2. 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

3. 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

Abitur-Docs RAG-System

┌─────────────────────────────────────────────────────────────────────┐
│                    Abitur-Docs Admin                                │
│                                                                     │
│  ┌─────────────┐    ┌──────────────────┐    ┌─────────────────┐    │
│  │ ZIP-Import  │───►│ KI-Datei-        │───►│ Metadaten-      │    │
│  │ NiBiS PDFs  │    │ erkennung        │    │ Bestätigung     │    │
│  └─────────────┘    └──────────────────┘    └─────────────────┘    │
│                                                       │            │
│                                                       ▼            │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   Vector Store (ChromaDB)                    │   │
│  │  Indexierung für RAG-Suche nach Fach, Jahr, Niveau          │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

NiBiS-Dateinamen werden automatisch erkannt:

• 2025_Deutsch_eA_I.pdf → Deutsch, erhöhtes Niveau, Aufgabe I
• 2025_Deutsch_eA_I_EWH.pdf → Erwartungshorizont

4. State Engine (Begleiter-Modus)

Das State Engine Modul implementiert proaktive Unterstützung für Lehrkräfte:

state_engine/
├── __init__.py       # Exports
├── models.py         # SchoolYearPhase, TeacherContext, Suggestion
├── rules.py          # 15+ Antizipations-Regeln
└── engine.py         # AnticipationEngine, PhaseService

Schuljahr-Phasen

1. ONBOARDING - Ersteinrichtung
2. SCHOOL_YEAR_START - Schuljahresbeginn
3. TEACHING_SETUP - Unterrichtsvorbereitung
4. PERFORMANCE_1 - 1. Leistungsphase
5. SEMESTER_END - Halbjahreszeugnisse
6. PERFORMANCE_2 - 2. Leistungsphase
7. EXAM_PHASE - Prüfungsphase
8. YEAR_END - Schuljahresende
9. ARCHIVED - Archiviert

Antizipations-Regeln

Regeln evaluieren den TeacherContext und generieren Suggestion-Objekte:

@dataclass
class Rule:
    id: str
    name: str
    phases: List[SchoolYearPhase]
    condition: Callable[[TeacherContext], bool]
    suggestion_builder: Callable[[TeacherContext], Suggestion]

4. 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

5. 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

State Engine Flow

Frontend Companion-Mode aktiviert
    ↓
GET /api/state/dashboard?teacher_id=xxx
    ↓
AnticipationEngine.get_suggestions(context)
    ↓
Rules evaluieren TeacherContext
    ↓
Priorisierte Vorschläge (max 5) zurück
    ↓
User führt Aktion aus
    ↓
POST /api/state/milestone (Meilenstein abschließen)
    ↓
PhaseService.check_and_transition() prüft Phasenübergang

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: docs/architecture/auth-system.md

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:

• docs/architecture/secrets-management.md
• docs/architecture/devsecops.md

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

Neue State Engine Regel:

1. In state_engine/rules.py neue Rule definieren
2. condition und suggestion_builder Funktionen implementieren
3. Zur RULES Liste hinzufügen
4. Passende phases angeben