breakpilot-compliance/backend-compliance/compliance

Breakpilot Compliance & Audit Framework

Uebersicht

Enterprise-ready GRC (Governance, Risk, Compliance) Framework fuer die Breakpilot EdTech-Plattform.

Kernfunktionen

Feature	Status	Beschreibung
19 EU-Regulations	Aktiv	DSGVO, AI Act, CRA, NIS2, Data Act, etc.
558 Requirements	Aktiv	Automatisch extrahiert aus EUR-Lex + BSI-TR PDFs
44 Controls	Aktiv	Technische und organisatorische Massnahmen
474 Control-Mappings	Aktiv	Keyword-basiertes Auto-Mapping
KI-Interpretation	Aktiv	Claude API fuer Anforderungsanalyse
Executive Dashboard	Aktiv	Ampel-Status, Trends, Top-Risiken

Architektur

backend/compliance/
├── api/
│   ├── routes.py         # 52 FastAPI Endpoints
│   └── schemas.py        # Pydantic Response Models
├── db/
│   ├── models.py         # SQLAlchemy Models
│   └── repository.py     # CRUD Operations
├── data/
│   ├── regulations.py    # 19 Regulations Seed
│   ├── controls.py       # 44 Controls Seed
│   ├── requirements.py   # Requirements Seed
│   └── service_modules.py # 30 Service-Module
├── services/
│   ├── ai_compliance_assistant.py  # Claude Integration
│   ├── llm_provider.py             # LLM Abstraction Layer
│   ├── pdf_extractor.py            # BSI-TR PDF Parser
│   └── regulation_scraper.py       # EUR-Lex Scraper
└── tests/                # Pytest Tests (in /backend/tests/)

Schnellstart

1. Backend starten

cd backend
docker-compose up -d
# ODER
uvicorn main:app --reload --port 8000

2. Datenbank initialisieren

# Regulations, Controls, Requirements seeden
curl -X POST http://localhost:8000/api/v1/compliance/seed \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

# Service-Module seeden
curl -X POST http://localhost:8000/api/v1/compliance/modules/seed \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

3. KI-Interpretation aktivieren

# Vault-gesteuerte API-Keys
export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=breakpilot-dev-token

# Status pruefen
curl http://localhost:8000/api/v1/compliance/ai/status

# Einzelne Anforderung interpretieren
curl -X POST http://localhost:8000/api/v1/compliance/ai/interpret \
  -H "Content-Type: application/json" \
  -d '{"requirement_id": "REQ-ID", "save_to_db": true}'

API-Endpoints

Dashboard & Executive View

Method	Endpoint	Beschreibung
GET	/api/v1/compliance/dashboard	Dashboard-Daten mit Scores
GET	/api/v1/compliance/dashboard/executive	Executive Dashboard (Ampel, Trends)
GET	/api/v1/compliance/dashboard/trend	Score-Trend (12 Monate)

Regulations & Requirements

Method	Endpoint	Beschreibung
GET	/api/v1/compliance/regulations	Alle 19 Regulations
GET	/api/v1/compliance/regulations/{code}	Eine Regulation
GET	/api/v1/compliance/requirements	558 Requirements (paginiert)
GET	/api/v1/compliance/requirements/{id}	Einzelnes Requirement

Controls & Mappings

Method	Endpoint	Beschreibung
GET	/api/v1/compliance/controls	Alle 44 Controls
GET	/api/v1/compliance/controls/{id}	Ein Control
GET	/api/v1/compliance/controls/by-domain/{domain}	Controls nach Domain
GET	/api/v1/compliance/mappings	474 Control-Mappings

KI-Features

Method	Endpoint	Beschreibung
GET	/api/v1/compliance/ai/status	LLM Provider Status
POST	/api/v1/compliance/ai/interpret	Requirement interpretieren
POST	/api/v1/compliance/ai/batch	Batch-Interpretation
POST	/api/v1/compliance/ai/suggest-controls	Control-Vorschlaege

Scraper & Import

Method	Endpoint	Beschreibung
POST	/api/v1/compliance/scraper/fetch	EUR-Lex Live-Fetch
POST	/api/v1/compliance/scraper/extract-pdf	BSI-TR PDF Extraktion
GET	/api/v1/compliance/scraper/status	Scraper-Status

Evidence & Risks

Method	Endpoint	Beschreibung
GET	/api/v1/compliance/evidence	Alle Nachweise
POST	/api/v1/compliance/evidence/collect	CI/CD Evidence Upload
GET	/api/v1/compliance/risks	Risk Register
GET	/api/v1/compliance/risks/matrix	Risk Matrix View

Datenmodell

RegulationDB

class RegulationDB(Base):
    id: str                    # UUID
    code: str                  # "GDPR", "AIACT", etc.
    name: str                  # Kurzname
    full_name: str             # Vollstaendiger Name
    regulation_type: enum      # eu_regulation, bsi_standard, etc.
    source_url: str            # EUR-Lex URL
    effective_date: date       # Inkrafttreten

RequirementDB

class RequirementDB(Base):
    id: str                    # UUID
    regulation_id: str         # FK zu Regulation
    article: str               # "Art. 32"
    paragraph: str             # "(1)(a)"
    title: str                 # Kurztitel
    requirement_text: str      # Original-Text
    breakpilot_interpretation: str  # KI-Interpretation
    priority: int              # 1-5

ControlDB

class ControlDB(Base):
    id: str                    # UUID
    control_id: str            # "PRIV-001"
    domain: enum               # gov, priv, iam, crypto, sdlc, ops, ai
    control_type: enum         # preventive, detective, corrective
    title: str                 # Kontroll-Titel
    pass_criteria: str         # Messbare Kriterien
    code_reference: str        # z.B. "middleware/pii_redactor.py:45"
    status: enum               # pass, partial, fail, planned

Frontend-Integration

Compliance Dashboard

/admin/compliance           # Haupt-Dashboard
/admin/compliance/controls  # Control Catalogue
/admin/compliance/evidence  # Evidence Management
/admin/compliance/risks     # Risk Matrix
/admin/compliance/scraper   # Regulation Scraper
/admin/compliance/audit-workspace  # Audit Workspace

Neue Komponenten (Sprint 1+2)

• ComplianceTrendChart.tsx - Recharts-basierter Trend-Chart
• TrafficLightIndicator.tsx - Ampel-Status Anzeige
• LanguageSwitch.tsx - DE/EN Terminologie-Umschaltung
• GlossaryTooltip.tsx - Erklaerungen fuer Fachbegriffe

i18n-System

import { getTerm, Language } from '@/lib/compliance-i18n'

// Nutzung
const label = getTerm('de', 'control')  // "Massnahme"
const label = getTerm('en', 'control')  // "Control"

Tests

# Alle Compliance-Tests ausfuehren
cd backend
pytest tests/test_compliance_*.py -v

# Einzelne Test-Dateien
pytest tests/test_compliance_api.py -v      # API Endpoints
pytest tests/test_compliance_ai.py -v       # KI-Integration
pytest tests/test_compliance_repository.py -v  # Repository
pytest tests/test_compliance_pdf_extractor.py -v  # PDF Parser

Umgebungsvariablen

# LLM Provider
COMPLIANCE_LLM_PROVIDER=anthropic  # oder "mock" fuer Tests
ANTHROPIC_API_KEY=sk-ant-...       # Falls nicht ueber Vault

# Vault Integration
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=breakpilot-dev-token

# Datenbank
DATABASE_URL=postgresql://user:pass@localhost:5432/breakpilot

Regulations-Uebersicht

Code	Name	Typ	Requirements
GDPR	DSGVO	EU-Verordnung	~50
AIACT	AI Act	EU-Verordnung	~80
CRA	Cyber Resilience Act	EU-Verordnung	~60
NIS2	NIS2-Richtlinie	EU-Richtlinie	~40
DATAACT	Data Act	EU-Verordnung	~35
DGA	Data Governance Act	EU-Verordnung	~30
DSA	Digital Services Act	EU-Verordnung	~25
EUCSA	EU Cybersecurity Act	EU-Verordnung	~20
EAA	European Accessibility Act	EU-Richtlinie	~15
BSI-TR-03161-1	Mobile Anwendungen Teil 1	BSI-Standard	~30
BSI-TR-03161-2	Mobile Anwendungen Teil 2	BSI-Standard	~100
BSI-TR-03161-3	Mobile Anwendungen Teil 3	BSI-Standard	~50
...	7 weitere	...	~50

Control-Domains

Domain	Beschreibung	Anzahl Controls
gov	Governance & Organisation	5
priv	Datenschutz & Privacy	7
iam	Identity & Access Management	5
crypto	Kryptografie	4
sdlc	Secure Development	6
ops	Betrieb & Monitoring	5
ai	KI-spezifisch	5
cra	CRA & Supply Chain	4
aud	Audit & Nachvollziehbarkeit	3

Erweiterungen

Neue Regulation hinzufuegen

1. Eintrag in data/regulations.py
2. Requirements ueber Scraper importieren
3. Control-Mappings generieren

# EUR-Lex Regulation importieren
curl -X POST http://localhost:8000/api/v1/compliance/scraper/fetch \
  -H "Content-Type: application/json" \
  -d '{"regulation_code": "NEW_REG", "url": "https://eur-lex.europa.eu/..."}'

Neues Control hinzufuegen

1. Eintrag in data/controls.py
2. Re-Seed ausfuehren
3. Mappings werden automatisch generiert

Multi-Projekt-Architektur (Migration 039)

Jeder Tenant kann mehrere Compliance-Projekte anlegen. Neue Tabelle compliance_projects, sdk_states erweitert um project_id.

Projekt-API Endpoints

Method	Endpoint	Beschreibung
GET	/api/v1/projects	Alle Projekte des Tenants
POST	/api/v1/projects	Neues Projekt erstellen
GET	/api/v1/projects/{id}	Einzelnes Projekt
PATCH	/api/v1/projects/{id}	Projekt aktualisieren
DELETE	/api/v1/projects/{id}	Projekt archivieren

Siehe compliance/api/project_routes.py und migrations/039_compliance_projects.sql.

Changelog

v2.0 (2026-01-17)

• Executive Dashboard mit Ampel-Status
• Trend-Charts (Recharts)
• DE/EN Terminologie-Umschaltung
• 52 API-Endpoints
• 558 Requirements aus 19 Regulations
• 474 Auto-Mappings
• KI-Interpretation (Claude API)

v1.0 (2026-01-16)

• Basis-Dashboard
• EUR-Lex Scraper
• BSI-TR PDF Parser
• Control Catalogue
• Evidence Management