# Architecture Rule — BreakPilot Core

## File Size Budget

Hard default: **500 LOC max** per file.
Soft targets:
- Handler/Router/Service: 300-400 LOC
- Models/Schemas/Types: 200-300 LOC
- Utilities: 100-200 LOC

Ausnahmen nur in `.claude/rules/loc-exceptions.txt` mit Begruendung.

## Split-Trigger

Sofort splitten wenn:
- Datei ueberschreitet 500 LOC
- Datei wuerde nach Aenderung 500 LOC ueberschreiten
- Datei mischt Transport + Business Logic + Persistence
- Datei enthaelt mehrere unabhaengig testbare Verantwortlichkeiten

## Go (consent-service, billing-service)

- Handler duenn halten (≤40 LOC pro Handler-Funktion)
- Business Logic in Services/Use-Cases
- Transport/Request-Decoding getrennt von Domain-Logik
- Dateien im gleichen Package teilen Typen automatisch — kein Re-Export noetig
- Models nach Domain splitten (user, consent, school, document, etc.)

## Python (backend-core, night-scheduler)

- Routes duenn halten — Business Logic in Services
- Persistenz in Repositories/Data-Access-Module
- Pydantic Schemas nach Domain splitten
- Zirkulaere Imports vermeiden

## TypeScript / Next.js (admin-core, pitch-deck)

- page.tsx duenn halten — Server Actions, Queries, Components auslagern
- _components/ + _hooks/ Konvention fuer Route-lokale Extracts
- .ts Dateien mit JSX muessen .tsx heissen (Turbopack!)
- Monolithische types.ts frueh splitten
- types.ts + types/ Shadowing vermeiden

## Entscheidungsreihenfolge

1. Bestehendes kleines kohaeesives Modul wiederverwenden
2. Neues Modul in der Naehe erstellen
3. Ueberfuellte Datei splitten, neues Verhalten in richtiges Split-Modul
4. Nur als letzter Ausweg: Grosse bestehende Datei erweitern

## FINGER WEG (laufende RAG Pipeline)

Diese Verzeichnisse duerfen NICHT refaktoriert werden:
- `control-pipeline/` — RAG/Control-Extraction Pipeline
- `rag-service/` — Semantische Suche
- `embedding-service/` — Text-Embeddings
- `voice-service/bqas/` — RAG Quality Assessment

## Workflow (bei jeder Aenderung)

1. Datei lesen + LOC pruefen
2. Wenn nahe am Budget → erst splitten
3. Minimale kohaerente Aenderung
4. Verifikation (Tests + Lint)
5. Zusammenfassung: Was geaendert, was verifiziert, Restrisiko

## LOC-Check ausfuehren

```bash
bash scripts/check-loc.sh --changed   # nur geaenderte Dateien
bash scripts/check-loc.sh --all       # alle Dateien (zeigt alle Violations)
```

## Commit-Marker

- `[split-required]` — Aenderung beginnt mit Datei-Split
- `[guardrail-change]` — Aenderungen an .claude/**, scripts/check-loc.sh
- `[interface-change]` — Public API Contracts geaendert
- `[migration-approved]` — Schema-/Migrations-Aenderungen