Kairo-Jinkendo/docs/reference/design-principles/alignment/DESIGN_PRINCIPLES_ALIGNMENT.md

Designprinzipien – Abgleich Mitai ↔ Shinkan

Status: Review / Entscheidungsgrundlage
Stand: 2026-07-04
Zweck: Widersprüche, bewusste Abweichungen und Implementierungslücken zwischen den Designprinzipien-Serien identifizieren — Basis für Familien-Entscheidungen und langfristige Konvergenz von Mitai und Shinkan.

Quellen:

App	Index
Mitai (Foundation)	mitai-jinkendo/.claude/docs/jinkendo-foundation/design-principles/README.md — 9 Module
Shinkan	design-principles/DESIGN_PRINCIPLES_INDEX.md — 15 Module

---

1. Kurzfassung

Kategorie	Anzahl	Bedeutung
Familien-Konsens	12 Muster	In beiden Serien gleich oder kompatibel — verbindlich für neue Apps
Bewusste Produkt-Abweichung	8	Fachlich/Architektur begründet — nicht angleichen, aber im Familienmodell verankern
Konzeptuelle Spannung	6	Widersprüche oder gegenläufige Defaults — Familien-Entscheidung nötig
Ist vs. Prinzip (Schuld)	14+	Mindestens eine App verletzt eigene oder Schwester-Prinzipien — Remediation
Nur Shinkan	6 Module	Mandanten-/Domänen-Bausteine ohne Mitai-Pendant
Nur Mitai (reifer)	3 Muster	Data Layer, Widget-Dashboard, Universal Import — Shinkan vereinfacht oder fehlt

Kernbefund: Mitai und Shinkan teilen dieselbe technische Basis (Auth, Migration, Nav-SSoT, Registry-Denken, Probe→Enforce), divergieren aber strukturell bei Entitlement-Subjekt (Profil vs. Verein), Berechnungsarchitektur (generischer Data Layer vs. domänenspezifisches Scoring) und KI-Reife (Unified Executor vs. schmale Laufzeit).

---

2. Familien-Konsens (für neue Produkte übernehmen)

Diese Muster sind in beiden Serien explizit oder implizit tragfähig:

#	Muster	Mitai	Shinkan
F1	Server-Sessions + Depends(require_auth)	Auth #1–3	Auth #1–2
F2	profile_id aus Session, nie aus Client-Header	Auth #3	Auth #3
F3	Auth getrennt von Authorization/Entitlements	Auth #10	Capabilities + Access Layer
F4	Nummerierte SQL-Migrationen + Tracking beim Container-Start	Migration #1–5	Migration #1–3
F5	Fail-fast, kein Auto-Rollback	Migration #5	Migration #2
F6	appNav / zentrale Nav-Config als SSoT	Navigation #1	Navigation #1
F7	Admin als eigener Hub/Realm	Navigation #6–7	Navigation #2
F8	DB-konfigurierbare KI-Prompts (nicht hardcoded Prod)	Prompt #2	AI Runtime #2
F9	Template vs. Kontext/Daten trennen	Prompt #5	AI Runtime #4
F10	Ingest ≠ Interpretation beim Import	Import #2	Wiki Import #1
F11	Preview/Dry-Run vor Massenimport	Import #3+	Wiki Import #2
F12	4-Phasen-Rollout Entitlements (Log → Enforce)	Feature #8	Capability #2

Empfehlung: Als JINKENDO_FOUNDATION_CHECKLIST in künftigen Apps verpflichtend; Details pro Modul in den Einzeldokumenten.

---

3. Modul-Abgleich (9 vergleichbare Paare)

Legende Bewertung:

Symbol	Bedeutung
✅	Prinzipien aligned / kompatibel
⚠️	Teilweise aligned; Lücken in Implementierung oder Doku
🔀	Bewusste Produkt-Divergenz (kein Bug)
❌	Widerspruch oder gegenläufiges Konzept — Entscheidung nötig
🏗️	Ist-Stand verletzt dokumentierte Prinzipien (Architekturschuld)

---

3.1 Prompt Engine (Mitai #1) ↔ AI Prompt Runtime (Shinkan #5)

Aspekt	Mitai	Shinkan	Bewertung
Single Entry Point	execute_prompt / Unified System	ai_prompt_runtime + verteilte Orchestratoren	❌ Konzept
Prompt-Typen	base / pipeline / workflow	nur slug + Mustache	🔀 Shinkan bewusst schlanker
Platzhalter-Registry	zentral, API-Verträge	Kontext-Arten (AiPromptContextKind), kein Registry-Katalog	⚠️
Data Layer-Anbindung	Layer 1 → Resolver	Domänen-Builder ad hoc	⚠️
Debug/Preview	ausgereift	Admin-Vorschau, weniger Runtime-Transparenz	⚠️
Feature-Gating an Execute	teils fehlend (Legacy)	Capability geplant, teils Probe	🏗️ beide

Widersprüche / gegenläufig:

• Mitai: Ein Executor ist Kernprinzip. Shinkan: kein vergleichbarer Executor — Planungs-KI umgeht teils die Laufzeit.
• Beide warnen vor parallelen KI-Pfaden; beide haben sie noch (Mitai insights.py, Shinkan Router-OpenRouter).

Familien-Entscheidung (Vorschlag):

Option	Inhalt
Zielbild	Gemeinsame prompt_executor-Fassade (Package oder Copy mit Namespace); Shinkan-Kontext-Builder als Plugins
Shinkan-Roadmap	Planungs-Orchestrierung in Laufzeit ziehen; keine Workflow-Graphs vor Planungs-Kontext-Reife
Nicht kopieren	Mitai: doppelte Pipeline-Modelle, PLACEHOLDER_MAP-Duplikat, Roh-SQL im Executor

---

3.2 Data Layer (Mitai #2) ↔ Skill Scoring (Shinkan #8)

Aspekt	Mitai	Shinkan	Bewertung
Berechnungs-SSoT	data_layer/ Layer 0→1→2	nur skill_scoring.py	❌ Abdeckung
Router delegieren	explizites Prinzip #13	Skill-Router ja; Planung teils nicht	⚠️
Confidence / data_points	Pflicht-Metadaten	nicht analog	🔀 Domäne anders
Chart/KPI-Anbindung	Layer 2b Adapter	KPI-Dashboard ruft Router-Helfer	⚠️
Import-Grenze	keine Scores beim Insert	Wiki: explizit kein Scoring beim Insert	✅

Widerspruch:

• Mitai postuliert generische Berechnungsschicht für die ganze App. Shinkan hat kein Data Layer — nur ein domänenspezifisches Scoring-Modul. Das ist keine Implementierungslücke allein, sondern unterschiedliche Architektur-Tiefe.

Familien-Entscheidung (Vorschlag):

Option	Inhalt
Familien-Prinzip	„Berechnungen in benannter Schicht, nicht in Router/React“ — Ja
Implementierung	Mitai: data_layer/ bleibt Referenz. Shinkan: Skill Scoring ist Layer-1-Vorbild; langfristig planning_metrics/ o. ä. statt Router-SQL
Nicht verallgemeinern	Mitai-Formeln (TDEE, WHR) — nur Schichtenmodell übernehmen

---

3.3 Feature & Entitlement (Mitai #3) ↔ Capability & Club Features (Shinkan #2)

Aspekt	Mitai	Shinkan	Bewertung
Subjekt	Profil + Tier	Verein (club_id) + Plan	❌ Scope
Auflösungs-API	check_feature_access	check_capability + club_features + /me/entitlements	🔀
Rollout 4 Phasen	ja	ja (Env-Flags)	✅
Registry	DB features + Tiers	Code-Registry → DB Sync	⚠️
Capabilities vs. Features	Features only	Capabilities und Kontingente getrennt	🔀 Shinkan feiner
Widget/Layout-Gating	zentral	Entitlements-API, kein Widget-Layout	⚠️

Größter Familien-Konflikt:

Mitai-Dokument #3 „Nicht übernehmen“ Punkt 10: „Profile as Entitlement-Subject — Multi-App-Familie braucht separates Identity/Subscription-Boundary.“
Shinkan ist die Antwort mit Verein als Subjekt — aber es gibt kein gemeinsames Familienmodell, das Profil-Tier und Org-Limits kombiniert.

Familien-Entscheidung (Vorschlag):

Entitlement-Subjekt (familie):
  ├── account (profile_id)     → Tier, persönliche Limits (Mitai)
  └── tenant (club_id?)        → Org-Plan, Capabilities (Shinkan, optional null)

API: GET /me/entitlements?tenant_id=
Enforcement: eine resolve_entitlement(subject, capability|feature)

App	Remediation
Mitai	Org-Scope reservieren; Tier-Drift (#3 Schuld) bereinigen
Shinkan	CLUB_FEATURE_ENFORCE=1 produktiv; Mitai-Legacy check_feature_access nicht nutzen (bereits Regel)

---

3.4 Registry / Plugin (Mitai #4) ↔ Rights Registry (Shinkan #3)

Aspekt	Mitai	Shinkan	Bewertung
Registry-first	Platzhalter, Widgets, CSV-Module	Capabilities + Features only	⚠️ Abdeckung
Validierung an Grenze	ja	ja (register_* wirft)	✅
Runtime + DB	Dual (Katalog + DB-Overrides)	Code → DB Upsert	✅
Dual Registry FE/BE	Widgets + registerDashboardWidgets	nicht vorhanden	🔀
Metadaten-Tiefe	nach Risiko (Matrix in Doc)	schlankere Dataclasses	✅

Kein Widerspruch — Shinkan Rights Registry ist Teilmenge des Mitai-Meta-Musters.

Familien-Entscheidung: Mitai-Registry-Matrix (Platzhalter / UI-Plugin / Import-Modul / Rechte) als Familien-Taxonomie; Shinkan erweitert um Import-/Prompt-Registry wenn Wiki-Import generisch wird.

---

3.5 Auth & Session (Mitai #5 ↔ Shinkan #4)

Aspekt	Mitai	Shinkan	Bewertung
Session-Modell	opaque token	gleich (shared auth.py)	✅
Depends-Pattern	ja	ja (+ TenantContext)	✅
IDOR Profile-Header	dokumentierte Schwäche	Shinkan: Session-only betont	⚠️ prüfen
RBAC	role admin/user	Portal-Rolle + Vereinsrollen	🔀
Rate Limiting	ja	(Mitai-spezifisch in Router)	⚠️
Feature-Flags in Session	Legacy-Spalten	Account-Lifecycle separat	🏗️ Mitai

Gegenläufig: Shinkan erweitert Auth um Mandanten — darf Mandantenlogik nicht in auth.py legen (Shinkan-Prinzip „Nicht übernehmen“).

Familien-Entscheidung: Gemeinsames Auth-Modul; TenantContext als optionales Add-on-Pattern für mandantenfähige Apps.

---

3.6 Universal Import (Mitai #6) ↔ Wiki Import (Shinkan #11)

Aspekt	Mitai	Shinkan	Bewertung
Ingest ≠ Interpretation	✅	✅	✅
Modul-Registry	zentral	fehlt (wiki-hardcoded)	⚠️
SAVEPOINT pro Zeile	ja	nicht dokumentiert	⚠️
Vorlagen/Mappings	generisch	SMW-Kategorien via Env	🔀
Feature-Limits	an Import gebunden	Admin-only	⚠️

Kein Konflikt — unterschiedliche Reife. Shinkan ist Spezialfall des Mitai-Musters.

Familien-Entscheidung: Neue Import-Quellen über Universal-Import-Gerüst (Mitai); Wiki als import_type=mediawiki registrieren.

---

3.7 Dashboard Widgets (Mitai #7) ↔ Dashboard KPIs (Shinkan #14)

Aspekt	Mitai	Shinkan	Bewertung
UX-Modell	konfigurierbares Widget-Layout	festes KPI-Aggregat	❌ UX-Konzept
Chatty Client vermeiden	via Widget-Daten	via /dashboard/kpis	✅ Ziel
Entitlements	allowed pro Widget	TenantContext auf KPIs	✅
Data Layer	Widgets konsumieren Layer 1	intern Router-Helfer	⚠️

Gegenläufig: Mitai: Nutzer konfiguriert Dashboard. Shinkan: Produkt definiert feste Kacheln — bewusste MVP-Vereinfachung.

Familien-Entscheidung:

App-Typ	Dashboard-Pattern
Personal Tracking (Mitai)	Widget-Katalog + Layout-JSON
Trainer/Verein (Shinkan)	Aggregierte KPI-Endpoints ausreichend; Widget-System optional Phase 2
Neue App	Aggregat-Endpoint mindestens; Widget-System wenn Personalisierung nötig

---

3.8 Navigation / IA (Mitai #8 ↔ Shinkan #12)

Aspekt	Mitai	Shinkan	Bewertung
appNav SSoT	ja	ja	✅
Admin-Hub	Shell + Hub-Gruppen	horizontale AdminPageNav	⚠️
Breakpoint 1024px	explizit	„prüfen“	⚠️
Onboarding-Nav	—	reduziert ohne Verein	🔀 Shinkan
adminNav.js SSoT	empfohlen	hardcoded Array in JSX	🏗️ Shinkan
Safe Area PWA	ja	Design-System, weniger explizit	⚠️

Familien-Entscheidung: appNav.js + adminNav.js als Pflicht; Shinkan AdminPageNav refactoren.

---

3.9 Migration & Deploy (Mitai #9 ↔ Shinkan #13)

Aspekt	Mitai	Shinkan	Bewertung
XXX_*.sql + schema_migrations	✅	✅	✅
Startup vor App	✅	✅	✅
develop/main	✅	✅	✅
Feste Ports	✅	✅	✅
Immutabler Docker-Build	dokumentiert	nicht im Shinkan-Doc	⚠️ Doku
Health-Check / PG wait	ausführlich	kürzer	⚠️ Doku

Aligned — Shinkan-Dokument ist Untermenge; Implementierung vermutlich gleich (shared Infra).

---

4. Nur Shinkan (6 Module) — Einordnung für die Familie

Modul	Familien-Relevanz	Mitai-Bezug
Access Layer & Tenant	Pflicht für mandantenfähige Apps	Mitai #3 fordert Org-Boundary — hier ausformuliert
Media Assets & Archiv	Optional (Content-Apps)	—
Exercise Catalog	Shinkan-Domäne	—
Training Planning	Shinkan-Domäne	—
Content Reports (P-13)	Empfohlen für UGC/Plattform	—
Maturity Models	Optional (Kompetenz-Apps)	—

Kein Widerspruch zu Mitai — ergänzen das Familienmodell um Mandant + Content-Governance.

---

5. Querschnitt: Ist-Stand vs. dokumentierte Prinzipien

Gemeinsame Architekturschuld (beide Apps verletzen teils eigene „Nicht übernehmen“-Listen):

Thema	Mitai	Shinkan
Parallele KI-Pfade	insights.py Legacy	OpenRouter direkt in Routern
Entitlement Enforcement	teils UI-only / Legacy-Spalten	Env Probe-only
Registry-Sync / Duplikat	PLACEHOLDER_MAP + Registry	Capabilities-Sync, kein Prompt-Registry
Frontend ohne Backend-Gate	teils	Capabilities Probe
Dokumentations-Drift	Tier vs. Enforcement-Docs	Endpoint-Audit unvollständig
Monolithische Pages/Client	God Pages, api.js	God Pages, api.js (Roadmap Phase 4)
Fehlende JSON-Schema-KI	TODO	TODO (explizit vermeiden)

---

6. Entscheidungs-Matrix (Priorisiert)

Prio	Entscheidung	Betroffene Apps	Empfohlene Familien-Regel
P0	Entitlement-Subjekt: Profil und optional Tenant	Mitai, Shinkan, neu	Ein API-Shape /me/entitlements; zwei Subjekt-Ebenen
P0	Kein Client-profile_id für AuthZ	alle	Session-only; Tenant via Header + Membership
P1	KI: ein Executor pro App	Mitai (fertig), Shinkan (Ziel)	execute_prompt(slug, context_dto)
P1	Berechnungs-SSoT-Schicht	Shinkan erweitern	Mindestens ein */metrics.py pro Domäne mit KPIs
P1	Enforcement produktiv	beide	Phase 4 Enforce in Prod für kritische Features
P2	Registry-Taxonomie vereinheitlichen	beide	Rechte / Platzhalter / Import / UI-Plugin
P2	Admin-Nav SSoT	Shinkan	adminNav.js wie Mitai
P2	Import: Universal + Spezialmodule	Shinkan	Wiki als registriertes Modul
P3	Dashboard: Aggregat vs. Widgets	produktabhängig	Entscheidungsbaum §3.7
P3	Shared auth.py / db_init	beide	Monorepo-Package oder Sync-Disziplin

---

7. Konvergenz-Roadmap (langfristig)

flowchart LR
  subgraph foundation [Familien-Foundation]
    M9[Migration]
    M5[Auth]
    F3[Entitlements 2-Ebenen]
    R4[Registry Meta]
  end

  subgraph mitai [Mitai]
    DL[Data Layer]
    PE[Prompt Engine]
    DW[Dashboard Widgets]
  end

  subgraph shinkan [Shinkan]
    AL[Access Layer]
    AR[AI Runtime → Executor]
    SS[Skill Scoring → Layer 1]
  end

  M9 --> mitai
  M9 --> shinkan
  M5 --> mitai
  M5 --> shinkan
  F3 --> mitai
  F3 --> shinkan
  R4 --> mitai
  R4 --> shinkan
  AL -.->|Mandanten-Apps| foundation
  PE -.->|Konvergenz| AR
  DL -.->|Schichtenmodell| SS

Phase	Mitai	Shinkan
Kurz	Legacy KI-Pfade entfernen; Enforcement-Doku vereinheitlichen	Access-Layer-Audit abschließen; CAPABILITY_ENFORCE
Mittel	Org-Scope in Entitlements vorbereiten	ai_prompt_runtime → Unified Executor; Router-Helfer statt KPI-Duplikat
Lang	SSO/Identity (Vision)	Data-Layer-ähnliche Module für Planung; optional Widget-Dashboard

---

8. Nächste Schritte

1. Review-Workshop: Tabelle §6 P0–P1 durchgehen und Familien-Regeln verbindlich markieren.
2. FAMILY_ENTITLEMENT_MODEL.md anlegen (P0) → FAMILY_ENTITLEMENT_MODEL.md (Entwurf 2026-07-04)
3. Shinkan-Index und Mitai-Foundation-README auf dieses Dokument verlinken.
4. FAMILY_ENTITLEMENT_MODEL.md — Entwurf angelegt (§6 Produkt-Abweichungen, §8 Regeln neue Apps).
5. Pro P1-Punkt Issue/Remediation-Eintrag in jeweiliger SCHULDEN_UND_REMEDIATION / Mitai-Äquivalent.

---

9. Changelog

Datum	Änderung
2026-07-04	Erstfassung Abgleich Mitai Foundation (9) ↔ Shinkan (15)