Benjamin_Boenisch/breakpilot-pwa
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-02-15. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
fa5fe4baceca4d5526eeb7c6afadc283d7f031ea
breakpilot-pwa/.claude/CLAUDE.md
BreakPilot Dev f7487ee240 docs(claude): Add two-machine setup documentation 
- Clarify MacBook (client) vs Mac Mini (server) roles
- Add examples for correct SSH command execution
- Document browser testing workflow

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-09 00:22:38 -08:00

12 KiB
Raw Blame History

BreakPilot PWA - Projekt-Kontext für Claude

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup

Gerät Rolle Aufgaben
MacBook Client Claude Terminal, Browser (Frontend-Tests)
Mac Mini Server Docker, alle Services, Code-Ausführung, Tests, Git

WICHTIG: Die Entwicklung findet vollständig auf dem Mac Mini statt!

  • Alle Befehle (docker, git, tests, builds) per SSH auf dem Mac Mini ausführen
  • Das MacBook dient nur als Terminal und Browser für Frontend-Tests
  • Dateien werden auf dem Mac Mini bearbeitet, nicht lokal auf dem MacBook

SSH-Verbindung

# Verbindung zum Mac Mini im lokalen Netzwerk
ssh macmini

# Projektverzeichnis auf Mac Mini
cd /Users/benjaminadmin/Projekte/breakpilot-pwa

# Oder direkt (BEVORZUGT für einzelne Befehle):
ssh macmini "<befehl>"

Hostname: macmini (im lokalen Netzwerk via Bonjour) User: benjaminadmin Projekt: /Users/benjaminadmin/Projekte/breakpilot-pwa

Beispiele für korrekte Befehlsausführung

# ✅ RICHTIG: Befehle auf Mac Mini ausführen
ssh macmini "docker compose ps"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && git status"
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa/backend && source venv/bin/activate && pytest -v"

# ❌ FALSCH: Lokale Befehle auf MacBook (Docker/Services laufen dort nicht!)
docker compose ps
pytest -v

Browser-Tests (auf MacBook)

Frontend im Browser testen via:

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:

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

# 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

# Alle Services starten
docker compose up -d

# Einzelnen Service neu bauen
docker compose build --no-cache <service-name>
docker compose up -d <service-name>

# Logs anzeigen
docker compose logs -f <service-name>

# Status aller Container
docker compose ps

Tests

# 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)

# 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

Reference in New Issue View Git Blame Copy Permalink