breakpilot-compliance/.claude/CLAUDE.md

BreakPilot Compliance - DSGVO/AI-Act SDK Platform

Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

Zwei-Rechner-Setup

Geraet	Rolle	Aufgaben
MacBook	Client	Claude Terminal, Browser (Frontend-Tests)
Mac Mini	Server	Docker, alle Services, Code-Ausfuehrung, Tests, Git

WICHTIG: Die Entwicklung findet vollstaendig auf dem Mac Mini statt!

SSH-Verbindung

ssh macmini
# Projektverzeichnis:
cd /Users/benjaminadmin/Projekte/breakpilot-compliance

# Einzelbefehle (BEVORZUGT):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && <cmd>"

---

Voraussetzung

breakpilot-core MUSS laufen! Dieses Projekt nutzt Core-Services:

• PostgreSQL (Schema: compliance, core)
• Valkey (Session-Cache)
• Vault (Secrets)
• RAG-Service (Vektorsuche fuer Compliance-Dokumente)
• Nginx (Reverse Proxy)

Pruefen: curl -sf http://macmini:8099/health

---

Haupt-URLs (Browser auf MacBook)

Frontends

URL	Service	Beschreibung
https://macmini:3007/	Admin Compliance	SDK-Dashboard, alle Compliance-Module
https://macmini:3006/	Developer Portal	API-Dokumentation fuer Kunden

Backend-APIs

URL	Service	Beschreibung
https://macmini:8002/	Backend Compliance	Compliance APIs (DSGVO, DSR, GDPR)
https://macmini:8093/	AI Compliance SDK	KI-konforme Compliance-Analyse

Admin Compliance Module (https://macmini:3007/)

Pfad	Modul	Beschreibung
/dashboard	Dashboard	Uebersicht + Catalog-Manager
/sdk/tom	TOM	Technisch-Organisatorische Massnahmen
/sdk/dsfa	DSFA	Datenschutz-Folgenabschaetzung
/sdk/vvt	VVT	Verzeichnis von Verarbeitungstaetigkeiten
/sdk/loeschfristen	Loeschfristen	Loeschfristen-Verwaltung
/sdk/ai-act	AI Act	KI-Verordnung Compliance
/sdk/consent	Consent	Einwilligungsmanagement
/sdk/dsr	DSR	Betroffenenrechte
/sdk/vendor-compliance	Vendor	Auftragsverarbeitung
/sdk/risk-assessment	Risiko	Risikobewertung
/sdk/incident-response	Vorfaelle	Datenschutz-Vorfaelle
/sdk/training	Schulung	Mitarbeiter-Schulungen
/sdk/audit	Audit	Audit-Management
/sdk/policy-generator	Policies	Richtlinien-Generator
/sdk/data-mapping	Data Map	Datenfluss-Mapping
/developers	Developer Portal	SDK API-Docs

---

Services (~8 Container)

Service	Tech	Port	Container
admin-compliance	Next.js 15	3007 (via nginx)	bp-compliance-admin
backend-compliance	Python/FastAPI	8002	bp-compliance-backend
ai-compliance-sdk	Python/FastAPI	8093	bp-compliance-ai-sdk
developer-portal	Next.js	3006 (via nginx)	bp-compliance-developer-portal
dsms-node	Node.js	4001/5001	bp-compliance-dsms-node
dsms-gateway	Node.js	8085	bp-compliance-dsms-gateway
pca-platform	Python	-	bp-compliance-pca
consent-sdk	Node.js	-	bp-compliance-consent-sdk

Docker-Netzwerk

Nutzt das externe Core-Netzwerk:

networks:
  breakpilot-network:
    external: true
    name: breakpilot-network

Container-Naming: bp-compliance-*

DB search_path: compliance,core,public

---

Verzeichnisstruktur

breakpilot-compliance/
├── .claude/
│   ├── CLAUDE.md             # Diese Datei
│   └── rules/                # Automatische Regeln
├── admin-compliance/         # Next.js Compliance Dashboard
│   ├── app/(sdk)/            # 37 SDK-Route-Dirs
│   ├── app/(admin)/          # Dashboard + Catalog-Manager
│   ├── components/sdk/       # SDKSidebar, CommandBar, ComplianceAdvisor
│   ├── components/catalog-manager/  # Shared Catalog UI
│   └── lib/sdk/              # SDK Context, Types, API-Client
├── backend-compliance/       # Python/FastAPI Backend
│   ├── compliance/           # Haupt-Package (40 Dateien)
│   │   ├── api/              # API Router
│   │   ├── db/               # DB Models
│   │   ├── services/         # Business Logic
│   │   └── data/             # Stammdaten
│   ├── consent_admin_api.py
│   ├── dsr_api.py
│   └── gdpr_api.py
├── ai-compliance-sdk/        # KI-Compliance Analyse Service
├── developer-portal/         # API-Dokumentation (Next.js)
├── breakpilot-compliance-sdk/ # SDK Package
├── consent-sdk/              # Consent SDK Package
├── pca-platform/             # Privacy Compliance Automation
├── dsms-node/                # IPFS Node
├── dsms-gateway/             # IPFS Gateway
├── scripts/                  # Helper Scripts
└── docker-compose.yml        # Compliance Compose (~8 Services)

---

Haeufige Befehle

Docker

# Compliance-Services starten (Core muss laufen!)
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && /usr/local/bin/docker compose up -d"

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

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

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

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

Git

# Zu BEIDEN Remotes pushen (PFLICHT!):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && git push all main"

# Remotes:
# origin: lokale Gitea (macmini:3003)
# gitea:  gitea.meghsakha.com
# all:    beide gleichzeitig

---

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. DSGVO-Compliance

• Dieses Projekt implementiert DSGVO-Tools — es muss selbst DSGVO-konform sein
• Audit-Logging fuer alle Compliance-Aktionen
• Consent-Management via Core consent-service

3. AI Act Compliance

• KI-Risikobewertung fuer alle KI-Features
• Human Oversight sicherstellen
• Transparenzpflicht bei KI-Nutzung

4. Testing & Dokumentation

• Tests sind Pflicht bei jeder Aenderung
• Compliance-Checkliste bei neuen Features durchgehen

5. Sensitive Dateien

NIEMALS aendern oder committen:

• .env, .env.local, Vault-Tokens, SSL-Zertifikate
• *.pdf, *.docx, kompilierte Binaries, grosse Medien

---

Tech-Stack

Sprache	Services
Python/FastAPI	backend-compliance, ai-compliance-sdk, pca-platform
TypeScript/Next.js	admin-compliance, developer-portal
Node.js	dsms-node, dsms-gateway, consent-sdk

---

SDK-Module im Detail

Katalog-System (Shared mit Lehrer)

• components/catalog-manager/ — CatalogManagerContent, CatalogTable, CatalogModuleTabs, CatalogEntryForm
• lib/sdk/catalog-manager/ — catalog-registry.ts, types.ts
• 17 DSGVO/AI-Act Kataloge (dsfa, vvt-baseline, vendor-compliance, etc.)

Backend-Compliance APIs

POST/GET /api/v1/compliance/risks
POST/GET /api/v1/compliance/controls
POST/GET /api/v1/compliance/requirements
POST/GET /api/v1/compliance/evidence
POST/GET /api/v1/dsr/requests
POST/GET /api/v1/gdpr/exports
POST/GET /api/v1/consent/admin

---

Wichtige Dateien (Referenz)

Datei	Beschreibung
admin-compliance/app/(sdk)/	Alle 37 SDK-Routes
admin-compliance/components/sdk/SDKSidebar.tsx	SDK Navigation
admin-compliance/components/sdk/CommandBar.tsx	Command Palette
admin-compliance/lib/sdk/context.tsx	SDK State (Provider)
backend-compliance/compliance/	Haupt-Package (40 Dateien)
ai-compliance-sdk/	KI-Compliance Analyse
developer-portal/	API-Dokumentation