# BreakPilot Core - Shared Infrastructure

## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

### Zwei-Rechner-Setup + Orca

| Geraet | Rolle | Aufgaben |
|--------|-------|----------|
| **MacBook** | Entwicklung | Claude Terminal, Code-Entwicklung, Browser (Frontend-Tests) |
| **Mac Mini** | Lokaler Server | Docker fuer lokale Dev/Tests (NICHT fuer Production!) |
| **Orca** | Production | Automatisches Build + Deploy bei Push auf gitea |

**WICHTIG:** Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Production-Deployment laeuft automatisch ueber Orca.

### Entwicklungsworkflow (CI/CD — Orca)

```bash
# 1. Code auf MacBook bearbeiten (dieses Verzeichnis)
# 2. Committen und zu BEIDEN Remotes pushen:
git push origin main

# 3. FERTIG! Push auf gitea triggert automatisch:
#    - Gitea Actions: Tests
#    - Orca: Build → Deploy
```

**NIEMALS** manuell in Orca auf "Redeploy" klicken — Gitea Actions triggert Orca automatisch.
**IMMER auf `main` pushen** — sowohl origin als auch gitea.

### TEMPORAER: Compliance-Repo Refactoring (Stand 2026-04-12)

**Das Compliance-Repo wird aktuell auf Production (gitea) refakturiert.**

- **Core + Lehrer:** Normal auf `main` pushen (origin + gitea) ✅
- **Compliance auf Mac Mini (origin):** Normal auf `main` pushen ✅
- **Compliance auf Production (gitea):** **NUR Feature Branches**, NICHT auf `main` pushen! ⚠️

```bash
# Compliance-Repo — RICHTIG:
git push origin main                                    # Mac Mini OK
git push gitea feature/mein-feature                     # Production: nur Feature Branch!

# Compliance-Repo — FALSCH (waehrend Refactoring):
# git push gitea main                                   # NICHT MACHEN!
```

**Nach Abschluss des Refactorings:** Gesamten Compliance-Code einmalig von Production auf Mac Mini uebernehmen. User sagt Bescheid wann es soweit ist.

### Post-Push Deploy-Monitoring (PFLICHT nach jedem Push auf gitea)

**IMMER wenn Claude auf gitea pusht, MUSS danach automatisch das Deploy-Monitoring laufen:**

1. Dem User sofort mitteilen: "Deploy gestartet, ich ueberwache den Status..."
2. Im Hintergrund Health-Checks pollen (alle 20 Sekunden, max 5 Minuten):
   ```bash
   curl -sf https://api-dev.breakpilot.ai/health    # Compliance Backend
   curl -sf https://sdk-dev.breakpilot.ai/health     # AI SDK
   ```
3. Sobald ALLE Endpoints healthy sind, dem User im Chat melden:
   **"Deploy abgeschlossen! Du kannst jetzt testen."**
4. Falls nach 5 Minuten noch nicht healthy → Fehlermeldung mit Hinweis auf Orca-Logs.

### Lokale Entwicklung (Mac Mini — optional, nur Dev/Tests)

```bash
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && git pull --no-rebase origin main"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service> && /usr/local/bin/docker compose up -d <service>"
```

### SSH-Verbindung (fuer lokale Docker/Tests)

```bash
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && <cmd>"
```

---

## Projekt-Kontext

**breakpilot-core** ist das Infrastruktur-Fundament der BreakPilot-Plattform. Es stellt alle gemeinsamen Services bereit, die von **breakpilot-lehrer** und **breakpilot-compliance** genutzt werden.

### 3-Projekt-Architektur

```
breakpilot-core          (dieses Repo — MUSS ZUERST starten)
  ├── breakpilot-lehrer      (haengt von Core ab)
  └── breakpilot-compliance  (haengt von Core ab)
```

Alle 3 Projekte teilen sich ein Docker-Netzwerk:
```yaml
networks:
  breakpilot-network:
    driver: bridge
    name: breakpilot-network   # Fixer Name, kein Auto-Prefix!
```

### Deployment-Modell

| Repo | Deployment | Trigger |
|------|-----------|---------|
| **breakpilot-core** | Orca (automatisch) | Push auf gitea main |
| **breakpilot-compliance** | Orca (automatisch) | Push auf gitea main |
| **breakpilot-lehrer** | Mac Mini (lokal) | Manuell docker compose |

---

## Haupt-URLs (via Nginx Reverse Proxy)

### Core-eigene Services

| URL | Service | Beschreibung |
|-----|---------|--------------|
| https://macmini:8000/ | backend-core | Shared APIs (Auth, RBAC, Notifications) |
| https://macmini:8097/ | rag-service | Semantische Suche, Dokument-Upload |
| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
| http://macmini:8099/ | health-aggregator | Health-Check aller Services |

### Interne Dienste (kein HTTPS)

| URL | Service | Beschreibung |
|-----|---------|--------------|
| http://macmini:3003/ | Gitea | Git-Server (User: pilotadmin) |
| http://macmini:8090/ | Woodpecker CI | CI/CD Server |
| http://macmini:8200/ | Vault | Secrets Management |
| http://macmini:8025/ | Mailpit | E-Mail (Dev) |
| http://macmini:9001/ | MinIO Console | S3 Storage UI |
| http://macmini:8096/ | Night Scheduler | Auto-Shutdown/Startup |
| http://macmini:8089/ | Camunda | BPMN Engine |

### Nginx-Proxy fuer Lehrer/Compliance (durchgereicht)

| URL | Projekt | Service |
|-----|---------|---------|
| https://macmini/ | Lehrer | Studio v2 |
| https://macmini:3000/ | Lehrer | Website |
| https://macmini:3002/ | Lehrer | Admin Lehrer |
| https://macmini:3007/ | Compliance | Admin Compliance |
| https://macmini:8001/ | Lehrer | Backend Lehrer |
| https://macmini:8002/ | Compliance | Backend Compliance |
| https://macmini:8086/ | Lehrer | Klausur-Service |
| https://macmini:8093/ | Compliance | AI Compliance SDK |

---

## Services (~28 Container)

### Infrastruktur

| Service | Tech | Port | Container |
|---------|------|------|-----------|
| nginx | Nginx | 80/443 + viele | bp-core-nginx |
| postgres | PostGIS 16 | 5432 | bp-core-postgres |
| valkey | Valkey 8 | 6379 | bp-core-valkey |
| vault | HashiCorp Vault | 8200 | bp-core-vault |
| vault-agent | Vault | - | bp-core-vault-agent |
| qdrant | Qdrant | 6333/6334 | bp-core-qdrant |
| minio | MinIO | 9000/9001 | bp-core-minio |
| mailpit | Mailpit | 8025/1025 | bp-core-mailpit |

### Shared Backend-Services

| Service | Tech | Port | Container |
|---------|------|------|-----------|
| backend-core | Python/FastAPI | 8000 | bp-core-backend |
| rag-service | Python/FastAPI | 8097 | bp-core-rag-service |
| embedding-service | Python/FastAPI | 8087 | bp-core-embedding-service |
| consent-service | Go/Gin | 8081 | bp-core-consent-service |
| billing-service | Go | 8083 | bp-core-billing-service |
| health-aggregator | Python/FastAPI | 8099 | bp-core-health |
| night-scheduler | Python/FastAPI | 8096 | bp-core-night-scheduler |

### Kommunikation

| Service | Tech | Container |
|---------|------|-----------|
| jitsi-web | Jitsi | bp-core-jitsi-web |
| jitsi-xmpp | Prosody | bp-core-jitsi-xmpp |
| jitsi-jicofo | Jicofo | bp-core-jitsi-jicofo |
| jitsi-jvb | JVB | bp-core-jitsi-jvb |
| synapse + synapse-db | Matrix | bp-core-synapse (Profil: chat) |

### DevOps

| Service | Tech | Port | Container |
|---------|------|------|-----------|
| gitea | Gitea | 3003 | bp-core-gitea |
| gitea-runner | Gitea Actions | - | bp-core-gitea-runner |
| woodpecker-server | Woodpecker | 8090 | bp-core-woodpecker-server |
| woodpecker-agent | Woodpecker | - | bp-core-woodpecker-agent |
| camunda | Camunda | 8089 | bp-core-camunda (Profil: bpmn) |

### Profile (nur bei Bedarf starten)

| Profil | Services | Start mit |
|--------|----------|-----------|
| chat | synapse, synapse-db | `--profile chat` |
| erp | erpnext-* (7 Container) | `--profile erp` |
| bpmn | camunda | `--profile bpmn` |
| docs | docs (MkDocs) | `--profile docs` |
| backup | pg-backup | `--profile backup` |

---

## Datenbank

### 3 Schemas (shared PostgreSQL)

| Schema | Projekt | Tabellen |
|--------|---------|----------|
| `core` | Core | users, sessions, auth, rbac, notifications, email_templates, billing |
| `lehrer` | Lehrer | classroom, units, klausuren, vocab, game, meetings, messenger |
| `compliance` | Compliance | compliance_*, dsr, gdpr, sdk_tenants, consent_admin |

```bash
# DB-Zugang (lokal)
ssh macmini "docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"
```

---

## Verzeichnisstruktur

```
breakpilot-core/
├── .claude/
│   ├── CLAUDE.md             # Diese Datei
│   └── rules/                # Automatische Regeln
├── backend-core/             # Python/FastAPI (Auth, RBAC, Notifications)
├── rag-service/              # Python/FastAPI (Qdrant, MinIO, Embeddings)
├── embedding-service/        # Python/FastAPI (Sentence-Transformers)
├── consent-service/          # Go/Gin (Consent-Management)
├── billing-service/          # Go (Abrechnungsservice)
├── night-scheduler/          # Python/FastAPI (Auto-Shutdown)
├── nginx/conf.d/             # Nginx Reverse Proxy Config
├── vault/                    # Vault Config + TLS Certs
├── gitea/                    # Gitea Config
├── docs-src/                 # MkDocs Quellen
├── mkdocs.yml                # MkDocs Config
├── control-pipeline/          # RAG/Control Pipeline (Port 8098)
├── scripts/                  # Helper Scripts
└── docker-compose.yml        # Haupt-Compose (28+ Services)
```

---

## Control Pipeline (WICHTIG)

**Seit 2026-04-09 liegt die gesamte RAG/Control-Pipeline im Core-Repo** (`control-pipeline/`), NICHT mehr im Compliance-Repo. Alle Arbeiten an der Pipeline (Pass 0a/0b, BatchDedup, Control Generator, Enrichment) finden ausschliesslich hier statt.

- **Port:** 8098
- **Container:** bp-core-control-pipeline
- **DB:** Schreibt ins `compliance`-Schema der shared PostgreSQL
- **Das Compliance-Repo wird NICHT fuer Pipeline-Aenderungen benutzt**

```bash
# Container auf Mac Mini
ssh macmini "cd ~/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache control-pipeline && /usr/local/bin/docker compose up -d --no-deps control-pipeline"

# Health
ssh macmini "/usr/local/bin/docker exec bp-core-control-pipeline curl -sf http://127.0.0.1:8098/health"

# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-control-pipeline"
```

---

## Haeufige Befehle

### Deployment (CI/CD — Standardweg)

```bash
# Committen und pushen → Orca deployt automatisch:
git push origin main
```

### Lokale Docker-Befehle (Mac Mini — nur Dev/Tests)

```bash
# Alle Core-Services starten
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"

# Einzelnen Service neu bauen
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service>"

# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-<service>"

# Status
ssh macmini "/usr/local/bin/docker ps --filter name=bp-core"
```

**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-SSH-PATH).

### Git

```bash
# Zu BEIDEN Remotes pushen (PFLICHT!):
git push origin main

# Remotes:


```

---

## Pre-Push Checks (PFLICHT — VOR JEDEM PUSH)

> Full detail: `.claude/rules/pre-push-checks.md` | Stack rules: `AGENTS.python.md`, `AGENTS.go.md`, `AGENTS.typescript.md`

**NIEMALS pushen ohne diese Checks. CI-Failures blockieren das gesamte Deploy.**

### Python (backend-core, rag-service, embedding-service, control-pipeline)

```bash
cd <service-dir>
ruff check . && mypy . --ignore-missing-imports --no-error-summary && pytest tests/ -x -q --no-header
```

### Go (consent-service, billing-service)

```bash
cd <service-dir>
gofmt -l . | grep -q . && exit 1; go vet ./... && golangci-lint run --timeout=5m && go test -race ./... && go build ./...
```

### TypeScript/Next.js (pitch-deck, admin-v2)

```bash
cd pitch-deck   # or admin-v2
npx tsc --noEmit && npm run lint && npm run build
```

> `npm run build` ist PFLICHT — `tsc` allein reicht nicht. Syntax-Fehler wie `const` inside object literal werden nur vom Build gefangen.

---

## Code-Qualitaet Guardrails (NON-NEGOTIABLE)

> Vollstaendige Details: `.claude/rules/architecture.md`
> Ausnahmen: `.claude/rules/loc-exceptions.txt`

### File Size Budget

- **Hard Cap: 500 LOC** pro Datei
- Wenn eine Aenderung eine Datei ueber 500 LOC bringen wuerde: **erst splitten, dann aendern**
- Ausnahmen nur mit Begruendung in `loc-exceptions.txt` + `[guardrail-change]` Commit-Marker

### Architektur

- **Go:** Handler ≤40 LOC → Service-Layer → Repository-Pattern
- **Python:** Routes duenn → Business Logic in Services → Persistenz in Repositories
- **TypeScript/Next.js:** page.tsx duenn → _components/, _hooks/ auslagern

### FINGER WEG (laufende RAG Pipeline)

Diese Verzeichnisse duerfen NICHT refaktoriert werden:
- `control-pipeline/` — RAG/Control-Extraction Pipeline
- `rag-service/` — Semantische Suche
- `embedding-service/` — Text-Embeddings
- `voice-service/bqas/` — RAG Quality Assessment

### LOC-Check ausfuehren

```bash
bash scripts/check-loc.sh --changed   # nur geaenderte Dateien
bash scripts/check-loc.sh --all       # alle Dateien (zeigt alle Violations)
```

### Commit-Marker

- `[split-required]` — Aenderung beginnt mit Datei-Split
- `[guardrail-change]` — Aenderungen an .claude/**, scripts/check-loc.sh
- `[interface-change]` — Public API Contracts geaendert

---

## Kernprinzipien

### 1. Open Source Policy
- **NUR Open Source mit kommerziell nutzbarer Lizenz**
- Erlaubt: MIT, Apache-2.0, BSD, ISC, MPL-2.0, LGPL
- **VERBOTEN:** GPL (ausser LGPL), AGPL, proprietaer

### 2. Testing & Dokumentation
- Tests sind Pflicht bei jeder Aenderung
- MkDocs aktualisieren: `--profile docs` starten

### 3. Sensitive Dateien
**NIEMALS aendern oder committen:**
- `.env`, `.env.local`, Vault-Tokens, SSL-Zertifikate
- `*.pdf`, `*.docx`, kompilierte Binaries, grosse Medien

---

## Nginx Port-Zuordnung (Uebersicht)

| Port | Ziel-Container | Projekt |
|------|----------------|---------|
| 443 | bp-lehrer-studio-v2 | Lehrer |
| 3000 | bp-lehrer-website | Lehrer |
| 3002 | bp-lehrer-admin | Lehrer |
| 3006 | bp-compliance-developer-portal | Compliance |
| 3007 | bp-compliance-admin | Compliance |
| 8000 | bp-core-backend | Core |
| 8001 | bp-lehrer-backend | Lehrer |
| 8002 | bp-compliance-backend | Compliance |
| 8086 | bp-lehrer-klausur-service | Lehrer |
| 8087 | bp-core-embedding-service | Core |
| 8089 | bp-core-camunda | Core |
| 8091 | bp-lehrer-voice-service | Lehrer |
| 8093 | bp-compliance-ai-sdk | Compliance |
| 8097 | bp-core-rag-service | Core |
| 8443 | bp-core-jitsi-web | Core |
