mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/README.md

Designprinzipien – Index (Jinkendo Foundation)

Teil von: Jinkendo Foundation

Status: Arbeitspapier / Übergabe
Stand: 2026-07-04
Zweck: Zentraler Einstieg für die aus Mitai extrahierte Serie tragfähiger Designprinzipien — für neue Apps der Jinkendo-Produktfamilie oder vergleichbare Self-Hosted-PWAs.

Nicht enthalten: Mitai-Gesamtarchitektur, Domänenlogik (Gesundheit/Ernährung), Kairo-/Framework-Empfehlungen.

Ablage: .claude/docs/jinkendo-foundation/design-principles/ · Regeln: DOCUMENTATION.md

---

Wofür diese Serie?

Mitai Jinkendo implementiert wiederkehrende Querschnittsmuster (Prompt-Ausführung, Data Layer, Entitlements, Registries, Auth, Import, Dashboard, Navigation, Deploy). Die neun Dokumente destillieren daraus:

• Was übertragbar ist (Prinzip + Begründung + Tragfähigkeit)
• Was bewusst nicht kopiert werden soll („Nicht übernehmen“)
• Wo im Code nachgeschaut werden kann (Pfade, Agent-Guides)

Jedes Dokument ist eigenständig lesbar; dieser Index ordnet Abhängigkeiten und Lese-Reihenfolge.

---

Dokumente (9/9)

#	Modul	Datei	Kernidee (1 Satz)
1	Prompt Engine	PROMPT_ENGINE_DESIGN_PRINCIPLES.md	Ein Executor, Pipeline/Workflow-Typen, Platzhalter über Registry — keine Raw-Template-Ausführung.
2	Data Layer	DATA_LAYER_DESIGN_PRINCIPLES.md	Layer 0→1→2: Single Source of Truth für Berechnungen; Charts und KI nutzen dieselbe Schicht.
3	Feature & Entitlement	FEATURE_ENTITLEMENT_DESIGN_PRINCIPLES.md	Zentrale check_feature_access, DB-Registry, 4-Phasen-Rollout — Enforcement an der API.
4	Registry / Plugin (Meta)	REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md	Drei Registry-Muster (Platzhalter, Widgets, CSV): SSoT, Validierung an der Grenze, Runtime-Registrierung.
5	Auth & Session	AUTH_SESSION_DESIGN_PRINCIPLES.md	Server-Sessions, require_auth als Depends — bekannte Schwäche: Profile-Header ohne Session-Bindung.
6	Universal Import	UNIVERSAL_IMPORT_DESIGN_PRINCIPLES.md	Modul-Registry + Executor + Vorlagen; Ingest ≠ Interpretation; SAVEPOINT pro Zeile.
7	Dashboard Widgets	DASHBOARD_WIDGETS_DESIGN_PRINCIPLES.md	Backend-Katalog, Profil-Layout, Config-Whitelist, Entitlements — Dual Registry mit Frontend.
8	Navigation / IA	NAVIGATION_IA_DESIGN_PRINCIPLES.md	appNav als SSoT, Shells für tiefe Bereiche, Admin-Hub, ein Breakpoint 1024px.
9	Migration & Deploy	MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md	XXX_*.sql beim Container-Start; develop/main → Dev/Prod; fail-fast, kein Auto-Rollback.

---

Empfohlene Lesereihenfolge

Schnellüberblick (30 Min)

1. REGISTRY_PLUGIN_DESIGN_PRINCIPLES.md — Meta-Muster für viele Module
2. DATA_LAYER_DESIGN_PRINCIPLES.md — Daten vs. Darstellung
3. MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md — Betrieb & Schema-Evolution

Vollständige Implementierung (neues Produkt)

Foundation:  (9) Migration & Deploy  →  (5) Auth  →  (3) Feature & Entitlement
Daten:       (2) Data Layer  →  (6) Universal Import
Erweiterung: (4) Registry Meta  →  (1) Prompt Engine  →  (7) Dashboard Widgets
Oberfläche:  (8) Navigation / IA

Nur ein Modul nachbauen

Ziel	Lese zuerst	Dann
KI-Analysen	#1 Prompt Engine	#2 Data Layer, #4 Registry
Charts & KPIs	#2 Data Layer	#7 Dashboard Widgets
Freemium / Limits	#3 Feature & Entitlement	#7 Widgets (Gating)
CSV-Import	#6 Universal Import	#2 Data Layer, #4 Registry
Admin-PWA	#8 Navigation / IA	#3, #5

---

Querschnittsthemen (über alle Docs)

Thema	Primär	Ergänzend
Single Source of Truth	#2 Data Layer	#4 Registry, #7 Widget-Katalog, #6 Modul-Registry
Validierung an der Grenze	#4 Registry	#7 Layout-Pydantic, #6 Template-Validator
Feature-Gating	#3 Entitlement	#7 Widget allowed, #6 Import-Limits
Dual Registry (Backend + Frontend)	#4 Registry	#7 registerDashboardWidgets, Platzhalter-UI
Idempotenz / Recovery	#9 Migration	#6 SAVEPOINT, Migration IF NOT EXISTS
Bekannte Lücken dokumentieren	alle „Nicht übernehmen“	z. B. IDOR Profile-Header (#5), fehlender Cross-Check Widget-IDs (#7)

---

Verwandte normative Docs (Mitai-spezifisch)

Diese Agent-Guides sind Implementierungsdetail; die Designprinzipien-Serie ist extrahiertes Muster:

Thema	Agent-Guide / Spec
Platzhalter	PLACEHOLDER_REGISTRY_FRAMEWORK.md
Data Layer erweitern	DATA_LAYER_EXTENSION_GUIDE.md
CSV Import	UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md
Dashboard Widgets	DASHBOARD_WIDGETS_AGENT_GUIDE.md
GUI / Admin / Nav	GUI_IA_ADMIN_NAV_2026-04-05.md
Migrationen (operativ)	MIGRATIONS.md
Membership	MEMBERSHIP_SYSTEM.md, FEATURE_ENFORCEMENT.md
Architektur-Regeln	ARCHITECTURE.md

---

Übergabe-Checkliste (neues Produkt in der Familie)

Nutze diese Liste beim Start eines Schwester-Projekts — Prinzipien ja, Mitai-Pfade nein:

[ ] Deploy: nummerierte SQL-Migrationen + Tracking-Tabelle + Startup vor App
[ ] Auth: Session server-side; Depends(require_auth); Admin-Route-Guard
[ ] Entitlements: eine check_feature_access-Funktion; keine Tier-Logik in UI-Widgets
[ ] Data Layer: Berechnungen nicht in Router/React duplizieren
[ ] Registry: neue erweiterbare IDs nur über zentralen Katalog + Validierung
[ ] Import (falls CSV): Modul-Registry + Vorlagen + Import-Grenze (keine Scores beim Insert)
[ ] Dashboard (falls konfigurierbar): Backend-Katalog + Layout-JSON + allowed-Flag
[ ] Navigation: eine appNav-SSoT; Shells für >6 Top-Level-Bereiche
[ ] Prompt/KI (falls): ein Executor; Platzhalter-Registry; kein Raw-Template an LLM
[ ] Dokumentieren: pro Modul „Nicht übernehmen“ aus Mitai-Lücken mitnehmen

---

Pflege

Aktion	Wo
Neues Querschnittsmodul extrahiert	Neues *_DESIGN_PRINCIPLES.md + Zeile in Tabelle oben
Mitai-Implementierung ändert Muster	Betroffenes Einzeldokument + ggf. Querschnittstabelle hier
Nur Mitai-Bugfix ohne Muster-Änderung	Agent-Guides / Code; Designprinzipien optional

---

Changelog Index

Datum	Änderung
2026-07-04	Index angelegt; Serie 1–9 abgeschlossen
2026-07-04	Nach jinkendo-foundation/design-principles/ verschoben