4245e24980
All checks were successful
CI / test-go-consent (push) Successful in 28s
CI / test-python-voice (push) Successful in 29s
CI / go-lint (push) Has been skipped
CI / python-lint (push) Has been skipped
CI / nodejs-lint (push) Has been skipped
CI / test-bqas (push) Successful in 28s
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
# BreakPilot - System-Architektur
|
|
|
|
## Uebersicht
|
|
|
|
BreakPilot ist eine modulare Bildungs- und Compliance-Plattform, aufgeteilt in drei unabhaengige Docker Compose Projekte:
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
│ 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 Actions │ │ │ │ │
|
|
│ ERP (optional) │ │ │ │ │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
└──────────────────┴──────────────────┘
|
|
breakpilot-network
|
|
(gemeinsames Docker-Netzwerk)
|
|
```
|
|
|
|
---
|
|
|
|
## Drei-Projekt-Architektur
|
|
|
|
### breakpilot-core (Shared Infrastructure)
|
|
|
|
Stellt gemeinsam genutzte Infrastruktur bereit. Beide Teams (Lehrer + Compliance) haengen von Core ab.
|
|
|
|
**Container-Prefix:** `bp-core-*`
|
|
|
|
| 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, Gitea Actions (act_runner), Night Scheduler, Mailpit |
|
|
| Kommunikation | Jitsi Meet (5 Container), Synapse (Matrix Chat) |
|
|
| ERP | ERPNext (optional, 9 Container) |
|
|
|
|
### breakpilot-lehrer (Team A: Bildung)
|
|
|
|
Alle Services fuer Lehrkraefte und den Bildungsbereich.
|
|
|
|
**Container-Prefix:** `bp-lehrer-*`
|
|
|
|
| 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) |
|
|
|
|
### breakpilot-compliance (Team B: DSGVO/Compliance)
|
|
|
|
Alle Services fuer das Compliance-Produkt (DSGVO, AI Act, BSI).
|
|
|
|
**Container-Prefix:** `bp-compliance-*`
|
|
|
|
| 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) |
|
|
|
|
---
|
|
|
|
## Netzwerk-Architektur
|
|
|
|
### Gemeinsames Docker-Netzwerk
|
|
|
|
Alle drei Projekte nutzen dasselbe Docker-Netzwerk `breakpilot-network`:
|
|
|
|
```yaml
|
|
# In jedem docker-compose.yml:
|
|
networks:
|
|
breakpilot-network:
|
|
external: true
|
|
```
|
|
|
|
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`
|
|
|
|
### Nginx Routing
|
|
|
|
Der zentrale Nginx in Core routet alle Anfragen an die richtigen Container:
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Sicherheit
|
|
|
|
### Authentifizierung & Autorisierung
|
|
|
|
| Schicht | Komponente | Beschreibung |
|
|
|---------|------------|--------------|
|
|
| **Authentifizierung** | Keycloak (Prod) / Lokales JWT (Dev) | Token-Validierung via JWKS oder HS256 |
|
|
| **Autorisierung** | RBAC (Eigenentwicklung) | Domaenenspezifische Berechtigungen |
|
|
|
|
### Basis-Rollen
|
|
|
|
| Rolle | Beschreibung |
|
|
|-------|--------------|
|
|
| `user` | Normaler Benutzer |
|
|
| `teacher` / `lehrer` | Lehrkraft |
|
|
| `admin` | Administrator |
|
|
| `data_protection_officer` | Datenschutzbeauftragter |
|
|
|
|
### Sicherheitsfeatures
|
|
|
|
- JWT-basierte Authentifizierung (RS256/HS256)
|
|
- 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
|
|
|
|
### Start-Reihenfolge
|
|
|
|
```bash
|
|
# 1. Core zuerst (Infrastruktur)
|
|
docker compose -f breakpilot-core/docker-compose.yml up -d
|
|
|
|
# 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
|
|
|
|
### Neuen Service zu einem Projekt hinzufuegen
|
|
|
|
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
|