92c86ec6ba
Install LOC guardrails (check-loc.sh, architecture.md, pre-commit hook) and split all 44 files exceeding 500 LOC into domain-focused modules: - consent-service (Go): models, handlers, services, database splits - backend-core (Python): security_api, rbac_api, pdf_service, auth splits - admin-core (TypeScript): 5 page.tsx + sidebar extractions - pitch-deck (TypeScript): 6 slides, 3 UI components, engine.ts splits - voice-service (Python): enhanced_task_orchestrator split Result: 0 violations, 36 exempted (pipeline, tests, pure-data files). Go build verified clean. No behavior changes — pure structural splits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# 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
|