Benjamin_Boenisch/breakpilot-pwa
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-02-15. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
main
breakpilot-pwa/docs-src/architecture/system-architecture.md
Benjamin Admin 21a844cb8a fix: Restore all files lost during destructive rebase 
A previous `git pull --rebase origin main` dropped 177 local commits,
losing 3400+ files across admin-v2, backend, studio-v2, website,
klausur-service, and many other services. The partial restore attempt
(660295e2) only recovered some files.

This commit restores all missing files from pre-rebase ref 98933f5e
while preserving post-rebase additions (night-scheduler, night-mode UI,
NightModeWidget dashboard integration).

Restored features include:
- AI Module Sidebar (FAB), OCR Labeling, OCR Compare
- GPU Dashboard, RAG Pipeline, Magic Help
- Klausur-Korrektur (8 files), Abitur-Archiv (5+ files)
- Companion, Zeugnisse-Crawler, Screen Flow
- Full backend, studio-v2, website, klausur-service
- All compliance SDKs, agent-core, voice-service
- CI/CD configs, documentation, scripts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 09:51:32 +01:00

312 lines
15 KiB
Markdown
Raw Permalink Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink