# 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