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:

```python
@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](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](secrets-management.md)
- [docs/architecture/devsecops.md](devsecops.md)

## Deployment

```yaml
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