From 2d2690887fe0c4a01391daddc3bd1ba5b973b252 Mon Sep 17 00:00:00 2001
From: Benjamin Boenisch <benjamin@breakpilot.de>
Date: Sat, 14 Feb 2026 19:51:12 +0100
Subject: [PATCH] docs: update MkDocs index with full service table and
 architecture overview

- Add complete service table with containers, ports, and tech stack
- Add Core dependency table
- Add URLs section with Lehrer-Tools
- Add deployment and git instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs-src/index.md | 119 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 113 insertions(+), 6 deletions(-)

diff --git a/docs-src/index.md b/docs-src/index.md
index 791409a..f51cfc7 100644
--- a/docs-src/index.md
+++ b/docs-src/index.md
@@ -1,21 +1,128 @@
 # BreakPilot Lehrer - Dokumentation
 
-Willkommen zur Dokumentation der **BreakPilot Lehrer KI-Plattform**.
+Willkommen zur Dokumentation des **BreakPilot Lehrer**-Stacks (Team A: Bildung).
 
-## Module
+## Drei-Projekt-Architektur
 
-- **Klausur-Service**: OCR, Korrektur, Vokabel-Worksheets
-- **Voice-Service**: Spracheingabe und Transkription
-- **Agent-Core**: Multi-Agent System
-- **KI-Daten-Pipeline**: Datenverarbeitung
+BreakPilot besteht aus drei unabhaengigen Projekten:
+
+| Projekt | Beschreibung | Docs |
+|---------|-------------|------|
+| **breakpilot-core** | Shared Infrastructure (DB, Cache, Vault, Nginx) | Port 8009 |
+| **breakpilot-lehrer** (dieses Projekt) | Bildungs-Stack | Port 8010 |
+| **breakpilot-compliance** | DSGVO/Compliance-Stack | Port 8011 |
+
+Lehrer haengt von Core ab (PostgreSQL, Valkey, Vault, Qdrant, MinIO, Embedding, RAG).
+
+---
+
+## Services
+
+| Service | Container | Port | Tech | Beschreibung |
+|---------|-----------|------|------|--------------|
+| Admin Lehrer | bp-lehrer-admin | 3002 | Next.js | Lehrer-Dashboard |
+| Studio v2 | bp-lehrer-studio-v2 | 443 | Next.js | Lehrer-/Schueler-Interface |
+| Website | bp-lehrer-website | 3000 | Next.js | Oeffentliche Website |
+| Backend Lehrer | bp-lehrer-backend | 8001 | Python/FastAPI | API Backend |
+| Klausur Service | bp-lehrer-klausur-service | 8086 | Python/FastAPI | Pruefungen, OCR, Vokabel-Worksheets |
+| School Service | bp-lehrer-school-service | 8084 | Go/Gin | Schulverwaltung |
+| Voice Service | bp-lehrer-voice-service | 8091 | Python/FastAPI | Spracheingabe (WebSocket) |
+| Geo Service | bp-lehrer-geo-service | 8088 | Python/FastAPI | Geo-Daten (PostGIS) |
+
+### Optionale Services (Docker Profiles)
+
+| Service | Container | Profil | Beschreibung |
+|---------|-----------|--------|--------------|
+| PaddleOCR | bp-lehrer-paddleocr | `ocr` | OCR Engine fuer Dokumentenerkennung |
+| BreakPilot Drive | bp-lehrer-breakpilot-drive | `game` | Lernspiel (Unity WebGL) |
+| Agent Core | bp-lehrer-agent-core | `dev` | Multi-Agent System |
+| Transcription Worker | bp-lehrer-transcription | `recording` | Audio-Transkription |
+
+---
+
+## URLs
+
+| URL | Service | Beschreibung |
+|-----|---------|--------------|
+| https://macmini/ | Studio v2 | Lehrer-/Schueler-Interface |
+| https://macmini:3000/ | Website | Oeffentliche Website |
+| https://macmini:3002/ | Admin Lehrer | Dashboard fuer Lehrkraefte |
+| https://macmini:8001/ | Backend API | REST API |
+| https://macmini:8086/ | Klausur Service | Pruefungs-API |
+| wss://macmini:8091/ | Voice Service | Spracheingabe WebSocket |
+
+### Lehrer-Tools (Studio v2)
+
+| URL | Tool |
+|-----|------|
+| https://macmini/vocab-worksheet | Vokabel-Arbeitsblatt Generator |
+| https://macmini/korrektur | Abiturklausur-Korrektur |
+| https://macmini/dashboard-experimental | Experimental Dashboard |
+
+---
+
+## Abhaengigkeiten zu Core
+
+Lehrer-Services nutzen folgende Core-Infrastruktur:
+
+| Core Service | Genutzt von | Zweck |
+|-------------|-------------|-------|
+| PostgreSQL (5432) | Alle | Zentrale Datenbank |
+| Valkey (6379) | Backend, Studio | Session Cache |
+| Vault (8200) | Alle | Secrets Management |
+| Qdrant (6333) | Klausur Service | RAG Vector-Suche |
+| MinIO (9000) | Klausur Service, Voice | Datei-Storage |
+| Embedding (8087) | Klausur Service | Text-Embeddings |
+| RAG Service (8097) | Klausur Service | Retrieval Augmented Generation |
+| Nginx | Alle | HTTPS Reverse Proxy |
+
+---
 
 ## Architektur
 
 - [Multi-Agent System](architecture/multi-agent.md)
 - [Zeugnis-System](architecture/zeugnis-system.md)
 
+## Services-Dokumentation
+
+- [Klausur Service](services/klausur-service/index.md)
+- [Voice Service](services/voice-service/index.md)
+- [Agent Core](services/agent-core/index.md)
+- [KI-Daten-Pipeline](services/ki-daten-pipeline/index.md)
+
 ## Entwicklung
 
 - [Testing](development/testing.md)
 - [Dokumentation](development/documentation.md)
 - [CI/CD Pipeline](development/ci-cd-pipeline.md)
+
+---
+
+## Deployment
+
+```bash
+# Voraussetzung: breakpilot-core muss laufen
+
+# Alle Lehrer-Services starten
+docker compose -f breakpilot-lehrer/docker-compose.yml up -d
+
+# Einzelnen Service neu bauen
+docker compose -f breakpilot-lehrer/docker-compose.yml build --no-cache <service>
+docker compose -f breakpilot-lehrer/docker-compose.yml up -d <service>
+
+# Mit optionalen Profilen
+docker compose -f breakpilot-lehrer/docker-compose.yml --profile ocr up -d
+```
+
+---
+
+## Git
+
+```bash
+# Zwei Remotes - IMMER zu beiden pushen:
+git push origin main && git push gitea main
+
+# Remotes:
+# origin: http://macmini:3003/pilotadmin/breakpilot-lehrer.git
+# gitea:  git@gitea.meghsakha.com:Benjamin_Boenisch/breakpilot-lehrer.git
+```