fdfe38b61a
- 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>
10 KiB
10 KiB
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/Woodpecker│ │ │ │ │
│ 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, Woodpecker CI/CD, 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:
# 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:5432bp-compliance-ai-sdk→bp-core-qdrant:6333bp-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:
Deployment
Start-Reihenfolge
# 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
# 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
- Service-Definition in das jeweilige
docker-compose.ymlhinzufuegen - Container-Name mit dem richtigen Prefix versehen (
bp-core-*,bp-lehrer-*,bp-compliance-*) - Netzwerk
breakpilot-networkzuweisen - Falls HTTPS noetig: Nginx-Route in
breakpilot-core/nginx/conf.d/default.confhinzufuegen - Dokumentation in der jeweiligen MkDocs-Instanz aktualisieren