Benjamin_Boenisch/breakpilot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update MkDocs for 3-project architecture (core/lehrer/compliance)

Browse Source 
- Rewrite system-architecture.md with new 3-project diagram
- Update index.md with Core services table and nginx routing
- Replace service docs that moved to lehrer/compliance with redirects
  (klausur-service, voice-service, agent-core, ki-daten-pipeline -> lehrer)
  (ai-compliance-sdk -> compliance)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
2026-02-14 19:51:09 +01:00
parent f2a24d7341
commit fdfe38b61a
7 changed files with 260 additions and 1414 deletions
Download Patch File Download Diff File Expand all files Collapse all files

408
docs-src/architecture/system-architecture.md
View File

@@ -1,254 +1,163 @@
# BreakPilot PWA - System-Architektur
# BreakPilot - System-Architektur
## Übersicht
## Uebersicht
BreakPilot ist eine modulare Bildungsplattform für Lehrkräfte mit folgenden Hauptkomponenten:
BreakPilot ist eine modulare Bildungs- und Compliance-Plattform, aufgeteilt in drei unabhaengige Docker Compose Projekte:
```
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────┘ └───────────────┘ └──────────────┘ └──────────────┘
┌────────────────────────────────────────────────────────────────────────────┐
│ Browser │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Studio v2 │ │ Admin Lehrer │ │ Admin Compl. │ │ Dev Portal │ │
│ │ (443) │ │ (3002) │ │ (3007) │ │ (3006) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼──────────────────┼──────────────────┼──────────────────┼─────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ bp-core-nginx (Reverse Proxy + TLS) │
│ Ports: 80, 443, 3000-3008, 8000-8097 │
└────────┬──────────────────┬──────────────────┬──────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ breakpilot-core │ │breakpilot-lehrer│ │breakpilot-compl.│
│ (Shared) │ │ (Team A) │ │ (Team B) │
│ │ │ │ │ │
│ PostgreSQL │ │ Studio v2 │ │ Admin Compliance│
│ Valkey │ │ Admin Lehrer │ │ Developer Portal│
│ Vault │ │ Website │ │ Backend Compl. │
│ Qdrant │ │ Backend Lehrer │ │ AI Compliance │
│ MinIO │ │ Klausur Service │ │ SDK (Go) │
│ Embedding │ │ Voice Service │ │ DSMS (IPFS) │
│ RAG Service │ │ School Service │ │ Document Crawler│
│ Consent (Go) │ │ Geo Service │ │ │
│ Billing (Go) │ │ PaddleOCR │ │ │
│ Backend Core │ │ Agent Core │ │ │
│ Admin Core │ │ Transcription │ │ │
│ Jitsi (5x) │ │ BreakPilot Drive│ │ │
│ Night Scheduler │ │ │ │ │
│ Health Agg. │ │ │ │ │
│ Gitea/Woodpecker│ │ │ │ │
│ ERP (optional) │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└──────────────────┴──────────────────┘
breakpilot-network
(gemeinsames Docker-Netzwerk)
```
## Komponenten
---
### 1. Admin Frontend (Next.js Website)
## Drei-Projekt-Architektur
Das **Admin Frontend** ist eine vollständige Next.js 15 Anwendung für Developer und Administratoren:
### breakpilot-core (Shared Infrastructure)
**Technologie:** Next.js 15, React 18, TypeScript, Tailwind CSS
Stellt gemeinsam genutzte Infrastruktur bereit. Beide Teams (Lehrer + Compliance) haengen von Core ab.
**Container:** `breakpilot-pwa-website` auf **Port 3000**
**Container-Prefix:** `bp-core-*`
**Verzeichnis:** `/website`
| Kategorie | Services |
|-----------|----------|
| Datenbank & Cache | PostgreSQL (PostGIS 16), Valkey |
| Security | Vault, Vault-Init, Vault-Agent |
| AI/ML | Embedding Service, RAG Service, Qdrant |
| Storage | MinIO (S3) |
| Business Logic | Consent Service (Go), Billing Service (Go), Backend Core (Python) |
| Frontend | Admin Core (Next.js, Port 3008) |
| Networking | Nginx (Reverse Proxy + TLS) |
| Monitoring | Health Aggregator |
| DevOps | Gitea, Woodpecker CI/CD, Night Scheduler, Mailpit |
| Kommunikation | Jitsi Meet (5 Container), Synapse (Matrix Chat) |
| ERP | ERPNext (optional, 9 Container) |
| 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 |
### breakpilot-lehrer (Team A: Bildung)
### 2. Lehrer Frontend (Studio UI)
Alle Services fuer Lehrkraefte und den Bildungsbereich.
Das **Lehrer Frontend** ist ein Single-Page-Application-ähnliches System für Lehrkräfte, das in Python-Modulen organisiert ist:
**Container-Prefix:** `bp-lehrer-*`
| 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)** |
| Service | Container | Port | Beschreibung |
|---------|-----------|------|--------------|
| Admin Lehrer | bp-lehrer-admin | 3002 | Lehrer-Dashboard (Next.js) |
| Studio v2 | bp-lehrer-studio-v2 | 443 | Lehrer-/Schueler-Studio (Next.js) |
| Website | bp-lehrer-website | 3000 | Oeffentliche Website (Next.js) |
| Backend Lehrer | bp-lehrer-backend | 8001 | API Backend (Python/FastAPI) |
| Klausur Service | bp-lehrer-klausur-service | 8086 | Pruefungen, OCR, RAG (Python) |
| School Service | bp-lehrer-school-service | 8084 | Schulverwaltung (Go) |
| Voice Service | bp-lehrer-voice-service | 8091 | Spracheingabe (Python) |
| Geo Service | bp-lehrer-geo-service | 8088 | Geo-Daten/PostGIS (Python) |
| PaddleOCR | bp-lehrer-paddleocr | - | OCR Engine (Profil: ocr) |
| BreakPilot Drive | bp-lehrer-breakpilot-drive | - | Lernspiel (Profil: game) |
| Agent Core | bp-lehrer-agent-core | - | Multi-Agent System (Profil: dev) |
| Transcription Worker | bp-lehrer-transcription | - | Audio-Transkription (Profil: recording) |
Jedes Modul exportiert:
- `get_css()` - CSS-Styles
- `get_html()` - HTML-Template
- `get_js()` - JavaScript-Logik
### breakpilot-compliance (Team B: DSGVO/Compliance)
### 3. Python Backend (FastAPI)
Alle Services fuer das Compliance-Produkt (DSGVO, AI Act, BSI).
#### API-Router
**Container-Prefix:** `bp-compliance-*`
| 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** |
| Service | Container | Port | Beschreibung |
|---------|-----------|------|--------------|
| Admin Compliance | bp-compliance-admin | 3007 | Compliance-Dashboard (Next.js) |
| Developer Portal | bp-compliance-developer-portal | 3006 | API-Dokumentation (Next.js) |
| Backend Compliance | bp-compliance-backend | 8002 | Compliance API (Python/FastAPI) |
| AI Compliance SDK | bp-compliance-ai-sdk | 8090/8093 | DSGVO-konforme KI (Go) |
| DSMS Node | bp-compliance-dsms-node | 4001/5001 | IPFS Node |
| DSMS Gateway | bp-compliance-dsms-gateway | 8082 | IPFS Gateway (Node.js) |
| Document Crawler | bp-compliance-document-crawler | 8098 | Web-Crawler (Python) |
#### 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 |
## Netzwerk-Architektur
### 4. Klausur-Korrektur System (Abitur)
### Gemeinsames Docker-Netzwerk
Das Klausur-Korrektur-System implementiert die vollständige Abitur-Bewertungspipeline:
Alle drei Projekte nutzen dasselbe Docker-Netzwerk `breakpilot-network`:
```
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────┘ └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```yaml
# In jedem docker-compose.yml:
networks:
breakpilot-network:
external: true
```
#### 15-Punkte-Notensystem
Container koennen sich gegenseitig ueber ihre Container-Namen erreichen:
- `bp-lehrer-backend` → `bp-core-postgres:5432`
- `bp-compliance-ai-sdk` → `bp-core-qdrant:6333`
- `bp-core-nginx` → `bp-lehrer-studio-v2:3001`
Das System verwendet den deutschen Abitur-Notenschlüssel:
### Nginx Routing
| 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 |
Der zentrale Nginx in Core routet alle Anfragen an die richtigen Container:
#### Bewertungskriterien
| Port | Upstream | Projekt |
|------|----------|---------|
| 443 | bp-lehrer-studio-v2:3001 + Jitsi | Lehrer + Core |
| 3000 | bp-lehrer-website:3000 | Lehrer |
| 3002 | bp-lehrer-admin:3000 | Lehrer |
| 3006 | bp-compliance-developer-portal:3000 | Compliance |
| 3007 | bp-compliance-admin:3000 | Compliance |
| 3008 | bp-core-admin:3000 | Core |
| 8000 | bp-core-backend:8000 | Core |
| 8001 | bp-lehrer-backend:8001 | Lehrer |
| 8002 | bp-compliance-backend:8002 | Compliance |
| 8086 | bp-lehrer-klausur-service:8086 | Lehrer |
| 8091 | bp-lehrer-voice-service:8091 | Lehrer |
| 8093 | bp-compliance-ai-sdk:8090 | Compliance |
| 8443 | bp-core-jitsi-web:80 | Core |
| 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)
| **Autorisierung** | RBAC (Eigenentwicklung) | Domaenenspezifische Berechtigungen |
### Basis-Rollen
@@ -259,53 +168,60 @@ Siehe: [Auth-System](auth-system.md)
| `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)
- CORS konfiguriert pro Service
- DSGVO-konformes Consent-Management (Core)
- **HashiCorp Vault** fuer Secrets-Management
- **DevSecOps Pipeline** mit Trivy, Semgrep, Gitleaks
Siehe:
- [Auth-System](auth-system.md)
- [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
### Start-Reihenfolge
consent-service:
build: ./consent-service
ports: ["8081:8081"]
```bash
# 1. Core zuerst (Infrastruktur)
docker compose -f breakpilot-core/docker-compose.yml up -d
postgres:
image: postgres:15
volumes:
- pgdata:/var/lib/postgresql/data
# 2. Lehrer-Stack
docker compose -f breakpilot-lehrer/docker-compose.yml up -d
# 3. Compliance-Stack
docker compose -f breakpilot-compliance/docker-compose.yml up -d
```
### Health-Checks
```bash
# Core Health (alle Infrastruktur-Services)
curl https://macmini:8099/health
# Lehrer Backend
curl https://macmini:8001/health
# Compliance Backend
curl https://macmini:8002/health
# AI SDK
curl https://macmini:8093/health
```
---
## Erweiterung
Neues Frontend-Modul hinzufügen:
### Neuen Service zu einem Projekt hinzufuegen
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
1. Service-Definition in das jeweilige `docker-compose.yml` hinzufuegen
2. Container-Name mit dem richtigen Prefix versehen (`bp-core-*`, `bp-lehrer-*`, `bp-compliance-*`)
3. Netzwerk `breakpilot-network` zuweisen
4. Falls HTTPS noetig: Nginx-Route in `breakpilot-core/nginx/conf.d/default.conf` hinzufuegen
5. Dokumentation in der jeweiligen MkDocs-Instanz aktualisieren