# BreakPilot PWA - Projekt-Kontext für Claude ## SSH-Verbindung (WICHTIG - IMMER ZUERST LESEN) ```bash # Verbindung zum Mac Mini im lokalen Netzwerk ssh macmini # Projektverzeichnis cd /Users/benjaminadmin/Projekte/breakpilot-pwa # Oder direkt: ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && " ``` **Hostname:** `macmini` (im lokalen Netzwerk via Bonjour) **User:** `benjaminadmin` **Projekt:** `/Users/benjaminadmin/Projekte/breakpilot-pwa` --- ## Kernprinzipien (IMMER BEACHTEN) ### 1. Open Source Policy - **NUR Open Source mit kommerziell nutzbarer Lizenz verwenden** - Erlaubte Lizenzen: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL - **VERBOTEN:** GPL (außer LGPL), AGPL, proprietäre Software, "free for non-commercial use" - **Bei jeder neuen Dependency:** SBOM aktualisieren unter https://macmini:3002/infrastructure/sbom ### 2. Testing & Dokumentation - **Tests sind Pflicht:** Unit Tests, Integration Tests für jede Änderung - **Dokumentation aktualisieren:** https://macmini:3002/development/docs (MKDocs) - Siehe `@.claude/rules/testing.md` und `@.claude/rules/documentation.md` ### 3. Architektur & Visualisierung aktualisieren Nach größeren Änderungen diese Dashboards aktualisieren: - **Architektur:** https://macmini:3002/architecture - **Screenflows:** https://macmini:3002/development/screen-flow - **Dashboard:** https://macmini:3002/dashboard - **Security Tools:** https://macmini:3002/infrastructure/security ### 4. CI/CD Pipeline Alle Security-Tools müssen nach der Pipeline durchlaufen: - Trivy (Container-Scanning) - Semgrep (SAST) - Gitleaks (Secret-Detection) - SBOM-Generierung --- ## Projektübersicht **Projektname:** BreakPilot PWA **Typ:** DSGVO-konforme EdTech-Plattform für den DACH-Raum **Architektur:** Microservices mit Docker Compose **Plattform:** Mac Mini M2 (Apple Silicon / ARM64) --- ## Haupt-URLs (HTTPS via Nginx) | URL | Service | Beschreibung | |-----|---------|--------------| | https://macmini/ | Studio v2 | Lehrer-/Schüler-Interface | | https://macmini:3000/ | Website | Öffentliche Website | | https://macmini:3002/ | Admin v2 | **Admin-Dashboard (Hauptzugang)** | | https://macmini:8000/ | Backend API | FastAPI Backend | | https://macmini:8086/ | Klausur Service | Prüfungs-/Klausurservice | | https://macmini:8443/ | Jitsi Meet | Videokonferenzen | | wss://macmini:8091/ | Voice Service | Spracheingabe WebSocket | ### AI Compliance SDK (DSGVO-Tools) | URL | Modul | Beschreibung | |-----|-------|--------------| | https://macmini:3002/sdk | SDK Admin | Haupt-SDK mit allen Modulen | | https://macmini:3002/sdk/tom | TOM | Technisch-Organisatorische Maßnahmen | | https://macmini:3002/sdk/dsfa | DSFA | Datenschutz-Folgenabschätzung | | https://macmini:3002/sdk/vvt | VVT | Verzeichnis von Verarbeitungstätigkeiten | | https://macmini:3002/sdk/loeschfristen | Löschfristen | Löschfristen-Verwaltung | | https://macmini:3002/developers | Developer Portal | API-Dokumentation für Kunden | | https://macmini:8093/ | SDK API | Backend-API für SDK | ### Interne Dienste | URL | Service | |-----|---------| | http://macmini:8200/ | Vault UI (Secrets) | | http://macmini:8025/ | Mailpit (E-Mail Dev) | | http://macmini:9001/ | MinIO Console (S3) | | http://macmini:3003/ | Gitea (Git-Server) | | http://macmini:8090/ | Woodpecker CI | | http://macmini:8089/ | Camunda (BPMN) | | http://macmini:8009/ | MkDocs (Projekt-Doku) | ### Studio URLs | URL | Beschreibung | |-----|--------------| | https://macmini/korrektur | Lehrer-Korrekturplattform | | https://macmini:8000/app | Dashboard (alte Version) | --- | http://macmini:8200/ | Vault UI (Secrets) | | http://macmini:8025/ | Mailpit (E-Mail Dev) | | http://macmini:9001/ | MinIO Console (S3) | | http://macmini:3003/ | Gitea (Git-Server) | | http://macmini:8090/ | Woodpecker CI | | http://macmini:8089/ | Camunda (BPMN) | --- ## Services (49 Container) ### Kern-Applikationen | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `studio-v2` | Next.js | 443 | Lehrer-/Schüler-Studio | | `admin-v2` | Next.js | 3002 | Admin-Dashboard | | `website` | Next.js | 3000 | Öffentliche Website | | `backend` | Python/FastAPI | 8000 | API Backend | | `consent-service` | Go/Gin | 8081 | Consent-Management | ### Bildungs-Services | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `klausur-service` | Python/FastAPI | 8086 | Prüfungen, OCR, RAG | | `school-service` | Python | 8082 | Schulverwaltung | | `edu-search-service` | Python | 8088 | Bildungssuche | | `breakpilot-drive` | Node.js | 8087 | Dateiablage (IPFS) | | `geo-service` | Python | 8084 | Geo-Daten (PostGIS) | | `voice-service` | Python | 8091 | Spracheingabe | ### KI & Compliance | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `ai-compliance-sdk` | Python | 8093 | DSGVO-konforme KI-Nutzung | | `embedding-service` | Python | 8083 | Text-Embeddings | | `paddleocr-service` | Python | - | OCR für Dokumente | | `transcription-worker` | Python | - | Audio-Transkription | ### Kommunikation | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `jitsi-web` | Jitsi | 8443 | Videokonferenzen | | `jitsi-xmpp` | Prosody | - | XMPP Server | | `jitsi-jicofo` | Jicofo | - | Konferenz-Fokus | | `jitsi-jvb` | JVB | 8080 | Video Bridge | | `jibri` | Jibri | - | Aufnahme/Streaming | | `synapse` | Matrix | 8008 | Chat-Server | ### Datenbanken & Storage | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `postgres` | PostGIS 16 | 5432 | Hauptdatenbank | | `valkey` | Valkey 8 | 6379 | Session-Cache (Redis-Fork) | | `qdrant` | Qdrant | 6333/6334 | Vektordatenbank | | `minio` | MinIO | 9000/9001 | S3-kompatibler Storage | ### Infrastructure & DevOps | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `nginx` | Nginx | 80/443 | Reverse Proxy + TLS | | `vault` | HashiCorp Vault | 8200 | Secrets Management | | `vault-agent` | Vault | - | Zertifikatserneuerung | | `gitea` | Gitea | 3003 | Git-Server | | `woodpecker-server` | Woodpecker | 8090 | CI/CD Server | | `woodpecker-agent` | Woodpecker | - | CI/CD Agent | | `night-scheduler` | Python/FastAPI | 8096 | Auto-Shutdown/Startup | | `mailpit` | Mailpit | 8025/1025 | E-Mail (Dev) | ### ERP & Billing | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `erpnext-frontend` | ERPNext | 8009 | ERP Frontend | | `erpnext-backend` | ERPNext | - | ERP Backend | | `erpnext-db` | MariaDB | - | ERP Datenbank | | `billing-service` | Python | - | Abrechnungsservice | ### DSMS (Data Sharing) | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `dsms-node` | Node.js | 4001/5001 | IPFS Node | | `dsms-gateway` | Node.js | 8085 | IPFS Gateway | ### Prozesse | Service | Tech | Port | Beschreibung | |---------|------|------|--------------| | `camunda` | Camunda | 8089 | BPMN Engine | --- ## Tech-Stack nach Sprache ### Go - `consent-service`: Gin, GORM, JWT ### Python - `backend`: FastAPI, SQLAlchemy, Pydantic - `klausur-service`: FastAPI, PaddleOCR, RAG - `ai-compliance-sdk`: FastAPI, Langfuse - `embedding-service`: FastAPI, Sentence-Transformers - `voice-service`: FastAPI, Whisper - `geo-service`: FastAPI, PostGIS - `school-service`: FastAPI - `night-scheduler`: FastAPI ### TypeScript/Next.js - `studio-v2`: Next.js 14, React, TailwindCSS - `admin-v2`: Next.js 14, React, TailwindCSS, shadcn/ui - `website`: Next.js 14 ### Node.js - `breakpilot-drive`: Express, IPFS - `dsms-node`: IPFS - `dsms-gateway`: Express --- ## Verzeichnisstruktur ``` breakpilot-pwa/ ├── .claude/ # Claude-Konfiguration │ ├── CLAUDE.md # Diese Datei │ ├── rules/ # Automatische Regeln │ │ ├── testing.md │ │ ├── documentation.md │ │ └── night-scheduler.md │ └── settings.json ├── admin-v2/ # Admin Dashboard (Next.js) ├── studio-v2/ # Lehrer-/Schüler-Studio (Next.js) ├── website/ # Öffentliche Website (Next.js) ├── backend/ # Python Backend (FastAPI) ├── consent-service/ # Go Consent Service ├── klausur-service/ # Klausur/OCR Service ├── ai-compliance-sdk/ # KI-Compliance SDK ├── voice-service/ # Spracheingabe ├── geo-service/ # Geo-Daten ├── school-service/ # Schulverwaltung ├── edu-search-service/ # Bildungssuche ├── breakpilot-drive/ # Dateiablage ├── night-scheduler/ # Auto-Shutdown ├── nginx/ # Reverse Proxy Config ├── vault/ # Vault Config ├── docs-src/ # MKDocs Quellen ├── docs-site/ # MKDocs Build ├── docker-compose.yml # Haupt-Docker-Config └── mkdocs.yml # MKDocs Config ``` --- ## Dokumentation (MKDocs) **Live-URL:** https://macmini:3002/development/docs **Quellen:** `/docs-src/` **Build:** `/docs-site/` **Config:** `mkdocs.yml` ### Dokumentation bearbeiten ```bash # MKDocs lokal starten (Live-Reload) cd /Users/benjaminadmin/Projekte/breakpilot-pwa mkdocs serve -a 0.0.0.0:8008 # Build mkdocs build ``` ### Struktur - `docs-src/index.md` - Startseite - `docs-src/architecture/` - Architektur-Docs - `docs-src/services/` - Service-Dokumentation - `docs-src/api/` - API-Dokumentation - `docs-src/development/` - Entwickler-Guides --- ## Häufige Befehle ### Docker ```bash # Alle Services starten docker compose up -d # Einzelnen Service neu bauen docker compose build --no-cache docker compose up -d # Logs anzeigen docker compose logs -f # Status aller Container docker compose ps ``` ### Tests ```bash # Go Tests (Consent Service) cd consent-service && go test -v ./... # Python Tests cd backend && source venv/bin/activate && pytest -v # Mit Coverage pytest --cov=. --cov-report=html ``` ### Git (via Gitea) ```bash # Remote ist localhost weil Gitea im Container läuft git remote -v # origin http://localhost:3003/pilotadmin/breakpilot-pwa.git ``` --- ## Rollen & Berechtigungen | Rolle | Beschreibung | |-------|--------------| | `user` | Normaler Benutzer (Schüler/Lehrer) | | `admin` | Administrator | | `data_protection_officer` | Datenschutzbeauftragter | | `school_admin` | Schuladministrator | --- ## Compliance & Sicherheit ### DSGVO - Consent-Management via `consent-service` - Datenexport-Funktionen - Löschkonzept implementiert ### AI Act - `ai-compliance-sdk` für konforme KI-Nutzung - Risikobewertung für KI-Funktionen - Audit-Logging ### BSI - BSI-TR-03161 Dokumentation vorhanden - Security-Scanning in CI/CD --- ## Sensitive Dateien **NIEMALS ändern oder committen:** - `.env`, `.env.local`, `.env.backup` - `secrets/` - Vault-Tokens - SSL-Zertifikate --- ## Ansprechpartner - **Git-Server:** http://macmini:3003 (Gitea) - **CI/CD:** http://macmini:8090 (Woodpecker) - **Issue-Tracker:** Gitea Issues