breakpilot-compliance/.claude/CLAUDE.md

BreakPilot Compliance - DSGVO/AI-Act SDK Platform

NON-NEGOTIABLE STRUCTURE RULES (enforced by .claude/settings.json hook, git pre-commit, and CI):

1. File-size budget: soft target 300 lines, hard cap 500 lines for any non-test, non-generated source file. Anything larger → split it. Exceptions are listed in .claude/rules/loc-exceptions.txt and require a written rationale.
2. Clean architecture per service. Routers/handlers stay thin (≤30 lines per handler) and delegate to services; services use repositories; repositories own DB I/O. See AGENTS.python.md / AGENTS.go.md / AGENTS.typescript.md.
3. Do not touch the database schema. No new Alembic migrations, no ALTER TABLE, no model field renames without an explicit migration plan reviewed by the DB owner. SQLAlchemy __tablename__ and column names are frozen.
4. Public endpoints are a contract. Any change to a path, method, status code, request schema, or response schema in backend-compliance/, ai-compliance-sdk/, dsms-gateway/, document-crawler/, or compliance-tts-service/ must be accompanied by a matching update in every consumer (admin-compliance/, developer-portal/, breakpilot-compliance-sdk/, consent-sdk/). Use the OpenAPI snapshot tests in tests/contracts/ as the gate.
5. Tests are not optional. New code without tests fails CI. Refactors must preserve coverage and add a characterization test before splitting an oversized file.
6. Do not bypass the guardrails. Do not edit .claude/settings.json, scripts/check-loc.sh, or the loc-exceptions list to silence violations. If a rule is wrong, raise it in a PR description.

These rules apply to every Claude Code session opened inside this repository, regardless of who launched it. They are loaded automatically via this CLAUDE.md.

First-Time Setup & Claude Code Onboarding

For humans: Read this CLAUDE.md top to bottom before your first commit. Then read AGENTS.<lang>.md for the service you are working on (AGENTS.python.md, AGENTS.go.md, or AGENTS.typescript.md).

For Claude Code sessions — things that cause first-commit failures:

1. Wrong branch. Run git branch --show-current before touching any file. The answer must be coolify. If it is main, run git checkout coolify before proceeding.

2. PreToolUse hook blocks your write. The PreToolUse hooks in .claude/settings.json will reject Write/Edit operations on any file that would push its line count past 500. This is intentional — split the file into smaller modules instead of trying to bypass the hook.

3. Missing [guardrail-change] marker. The guardrail-integrity CI job fails if you modify a guardrail file without the marker in the commit message body. See the table below.

4. Never git add -A or git add .. Stage files individually by path. git add -A risks committing .env, node_modules/, .next/, compiled binaries, and other artifacts that must never enter the repo.

5. LOC check before push. After any session, run bash scripts/check-loc.sh. It must exit 0 before you push. The git pre-commit hook runs this automatically, but run it manually first to catch issues early.

Commit message quick reference

Marker	Required when touching
[guardrail-change]	.claude/settings.json, scripts/check-loc.sh, scripts/githooks/pre-commit, .claude/rules/loc-exceptions.txt, any AGENTS.*.md
[migration-approved]	Anything under migrations/ or alembic/versions/

Add the marker anywhere in the commit message body or footer — the CI job does a plain-text grep for it.

---

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 origin

WICHTIG: Code wird auf dem MacBook bearbeitet. Production-Deployment laeuft automatisch ueber Orca.

Entwicklungsworkflow (CI/CD — Orca)

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

# 3. FERTIG! Push auf origin triggert automatisch:
#    - Gitea Actions: Lint → Tests → Validierung
#    - Orca: Build → Deploy
#    Dauer: ca. 3 Minuten
#    Status pruefen: https://gitea.meghsakha.com/Benjamin_Boenisch/breakpilot-compliance/actions

NICHT MEHR NOETIG: Manuelles ssh macmini "docker compose build" fuer Production. NIEMALS manuell in Orca auf "Redeploy" klicken — Gitea Actions triggert Orca automatisch.

Post-Push Deploy-Monitoring (PFLICHT nach jedem Push)

IMMER wenn Claude auf origin 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):

   # Compliance Health-Endpoints:
   curl -sf https://api-dev.breakpilot.ai/health    # Backend Compliance
   curl -sf https://sdk-dev.breakpilot.ai/health     # AI Compliance SDK
   

3. Sobald ALLE Endpoints healthy sind, dem User im Chat melden: "Deploy abgeschlossen! Du kannst jetzt testen: https://admin-dev.breakpilot.ai"
4. Falls nach 5 Minuten noch nicht healthy → Fehlermeldung mit Hinweis auf Orca-Logs.

Ablauf im Terminal:

> git push origin main ✓
> "Deploy gestartet, ich ueberwache den Status..."
> [Hintergrund-Polling laeuft]
> "Deploy abgeschlossen! Alle Services healthy. Du kannst jetzt testen."

CI/CD Pipeline (Gitea Actions → Orca)

Push auf origin main → go-lint/python-lint/nodejs-lint (nur PRs)
                    → test-go-ai-compliance
                    → test-python-backend-compliance
                    → test-python-document-crawler
                    → test-python-dsms-gateway
                    → validate-canonical-controls
                    → Orca: Build + Deploy (automatisch bei Push)

Dateien:

• .gitea/workflows/ci.yaml — Pipeline-Definition (Tests + Validierung)
• docker-compose.yml — Haupt-Compose
• docker-compose.hetzner.yml — Override: arm64→amd64 fuer Orca Production (x86_64)

Lokale Entwicklung (Mac Mini — optional)

# Nur fuer lokale Tests, NICHT fuer Production:
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-compliance pull --no-rebase origin main"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml build --no-cache <service>"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml up -d <service>"

# Fuer schnelle Iteration ohne Commit (rsync):
rsync -avz --exclude node_modules --exclude .next --exclude .git \
  admin-compliance/ macmini:~/Projekte/breakpilot-compliance/admin-compliance/

WICHTIG: Docker-Pfad auf Mac Mini ist /usr/local/bin/docker (nicht im Standard-SSH-PATH). WICHTIG: cd funktioniert NICHT in SSH-Einzelbefehlen — immer -f <pfad>/docker-compose.yml verwenden!

---

Voraussetzung

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

• Valkey (Session-Cache)
• Vault (Secrets)
• RAG-Service (Vektorsuche fuer Compliance-Dokumente)
• Nginx (Reverse Proxy)

Externe Services (Production):

• PostgreSQL 17 (sslmode=require) — Schemas: compliance, public
• Qdrant @ qdrant-dev.breakpilot.ai (HTTPS, API-Key)
• Object Storage (S3-kompatibel, TLS)

Config via .env (nicht im Repo): COMPLIANCE_DATABASE_URL, QDRANT_URL, QDRANT_API_KEY

---

Haupt-URLs

Production (Orca-deployed)

URL	Service	Beschreibung
https://admin-dev.breakpilot.ai/	Admin Compliance	SDK-Dashboard, alle Compliance-Module
https://developers-dev.breakpilot.ai/	Developer Portal	API-Dokumentation fuer Kunden
https://api-dev.breakpilot.ai/	Backend Compliance	Compliance APIs (DSGVO, DSR, GDPR)
https://sdk-dev.breakpilot.ai/	AI Compliance SDK	KI-konforme Compliance-Analyse

Lokal (Mac Mini — nur Dev/Tests)

URL	Service	Beschreibung
https://macmini:3007/	Admin Compliance	Lokale Entwicklung
https://macmini:3006/	Developer Portal	Lokale Entwicklung
https://macmini:8002/	Backend Compliance	Lokale Entwicklung
https://macmini:8093/	AI Compliance SDK	Lokale Entwicklung

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 (10 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	Go/Gin	8090→8093	bp-compliance-ai-sdk
developer-portal	Next.js 15	3006 (via nginx)	bp-compliance-developer-portal
compliance-tts-service	Python/Piper TTS	8095	bp-compliance-tts
document-crawler	Python/FastAPI	8098	bp-compliance-document-crawler
dsms-node	IPFS Kubo	4001/5001/8085	bp-compliance-dsms-node
dsms-gateway	Node.js	8082	bp-compliance-dsms-gateway
docs	MkDocs/nginx	8011	bp-compliance-docs
core-wait	curl health-check	-	bp-compliance-core-wait

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 (~10 Services, platform: arm64)
├── docker-compose.hetzner.yml # Override: arm64→amd64 fuer Orca Production
└── .gitea/workflows/ci.yaml  # CI/CD Pipeline (Lint → Tests → Validierung)

---

Haeufige Befehle

Deployment (CI/CD — Standardweg)

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

# CI-Status pruefen (im Browser):
# https://gitea.meghsakha.com/Benjamin_Boenisch/breakpilot-compliance/actions

# Health Checks:
curl -sf https://api-dev.breakpilot.ai/health
curl -sf https://sdk-dev.breakpilot.ai/health

Git

git push origin main

# Remote:
# origin: ssh://git@coolify.meghsakha.com:22222/Benjamin_Boenisch/breakpilot-compliance.git

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

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

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

# Lokaler Rebuild (nur wenn noetig):
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-compliance pull --no-rebase origin main"
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml build --no-cache <service> && /usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-compliance/docker-compose.yml up -d <service>"

---

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

Multi-Projekt-Architektur (seit 2026-03-09)

Jeder Tenant kann mehrere Compliance-Projekte anlegen. CompanyProfile ist pro Projekt (nicht tenant-weit).

URL-Schema: /sdk?project={uuid} — alle SDK-Seiten enthalten ?project= Query-Param. /sdk ohne ?project= zeigt die Projektliste (ProjectSelector).

Datenbank:

• compliance_projects — Projekt-Metadaten (Name, Typ, Status, Version)
• sdk_states — UNIQUE auf (tenant_id, project_id) statt nur tenant_id
• Migration: 039_compliance_projects.sql

Backend API (FastAPI):

GET    /api/v1/projects              → Alle Projekte des Tenants
POST   /api/v1/projects              → Neues Projekt erstellen (mit copy_from_project_id)
GET    /api/v1/projects/{project_id} → Einzelnes Projekt laden
PATCH  /api/v1/projects/{project_id} → Projekt aktualisieren
DELETE /api/v1/projects/{project_id} → Projekt archivieren (Soft Delete)

Frontend:

• components/sdk/ProjectSelector/ProjectSelector.tsx — Projektliste + Erstellen-Dialog
• lib/sdk/types.ts — ProjectInfo Interface, SDKState.projectId
• lib/sdk/context.tsx — projectId Prop, createProject(), listProjects(), switchProject()
• lib/sdk/sync.ts — BroadcastChannel + localStorage pro Projekt
• lib/sdk/api-client.ts — projectId in State-API + Projekt-CRUD-Methoden
• app/sdk/layout.tsx — liest ?project= aus searchParams
• app/api/sdk/v1/projects/ — Next.js Proxy zum Backend

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

# Stammdaten, Versionierung & Change-Requests
GET/POST/DELETE /api/compliance/company-profile
GET /api/compliance/company-profile/template-context
GET /api/compliance/change-requests
GET /api/compliance/change-requests/stats
POST /api/compliance/change-requests/{id}/accept
POST /api/compliance/change-requests/{id}/reject
POST /api/compliance/change-requests/{id}/edit
GET /api/compliance/generation/preview/{doc_type}
POST /api/compliance/generation/apply/{doc_type}
GET /api/compliance/{doc}/{id}/versions

Multi-Tenancy

• Shared Dependency: compliance/api/tenant_utils.py (get_tenant_id())
• UUID-Format, kein "default" mehr
• Header X-Tenant-ID > Query tenant_id > ENV-Fallback

---

Wichtige Dateien (Referenz)

Datei	Beschreibung
admin-compliance/app/(sdk)/	Alle 37+ SDK-Routes
admin-compliance/components/sdk/Sidebar/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 (50+ Dateien)
ai-compliance-sdk/	KI-Compliance Analyse
developer-portal/	API-Dokumentation