Initial commit: breakpilot-core - Shared Infrastructure

Docker Compose with 24+ services: - PostgreSQL (PostGIS), Valkey, MinIO, Qdrant - Vault (PKI/TLS), Nginx (Reverse Proxy) - Backend Core API, Consent Service, Billing Service - RAG Service, Embedding Service - Gitea, Woodpecker CI/CD - Night Scheduler, Health Aggregator - Jitsi (Web/XMPP/JVB/Jicofo), Mailpit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 23:47:13 +01:00
commit ad111d5e69
244 changed files with 84288 additions and 0 deletions
--- a/docs-src/architecture/system-architecture.md
+++ b/docs-src/architecture/system-architecture.md
@@ -0,0 +1,311 @@
+# 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](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:
+- [Secrets Management](secrets-management.md)
+- [DevSecOps](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