Kansho/docs/architecture/technical/platform_extensibility.md

title	version	status	date	product_family	document_role	parent_document
Kanshō – Plattformprinzipien: Registry, Prompt Engine, Konfiguration	0.1	Arbeitsstand	2026-08-19	Jinkendo	Technical Chapter / Extensibility / Registry / Prompt Engine / Configuration	technische_zielarchitektur.md

Kanshō – Plattformprinzipien

Kanonisches Home für die aus Mitai übernommenen Querschnittsmuster: einheitliche Registrierung, Prompt- und Workflow-Engine, Konfigurierbarkeit, Modularisierung.

Quelle: C:\dev\mitai\.claude\docs\jinkendo-foundation\design-principles/ (Dokumente 1–4, 7). Mitai-Pfade sind Beispiele, keine Kanshō-Dateinamen.

Der fachliche Dialog-/MVP-Stand bleibt nicht final. Datenschutz und Guardrails sind bindend: die Engine ruft Modelle nur über das Privacy Gateway auf. Dieses Kapitel legt die Plattform fest, auf der spätere Fachmodule registriert werden – nicht die Module selbst.

1. Leitentscheidung

Status: entschieden (Produktrahmen; Herkunft: Nutzeranforderung, Mitai-Foundation)

Kanshō übernimmt Mitais Erweiterungsarchitektur:

1. Neue Fähigkeiten kommen als registrierte Komponenten hinzu, nicht als Sonderpfade in Routern oder React.
2. KI läuft über eine Prompt-/Workflow-Engine, nicht über verstreute Provider-Calls.
3. Soweit fachlich sinnvoll, liegen Texte, Graphen, Sichtbarkeit und Limits in administrierbarer Konfiguration, nicht im Deploy-Code.
4. Berechnungen haben eine Single Source of Truth (Data Layer); UI und KI konsumieren dieselbe Schicht.
5. Jeder persönliche LLM-Aufruf der Engine geht durch das Privacy Gateway (privacy_gateway.md). Das ist fachliche Invariante, kein optionales Plugin. Konfiguration darf Prompts ändern, nicht den Egress-Pfad umgehen.

Nicht übernommen: Mitai-Domäne, parallele Legacy-Executoren, doppelte Registries, IDOR-Profilheader.

---

2. Registry- und Plugin-Muster

Mitai nutzt dasselbe Muster dreimal (Platzhalter, Dashboard-Widgets, CSV-Module). Kanshō übernimmt das Meta-Muster als einheitliches System für Modularisierung, Skalierung und Erweiterung.

2.1 Gemeinsames Schema

REGISTRY (Kanon: ID + Metadaten + Policies)
    ├── Implementierung (Resolver, Komponente, Executor)
    ├── Validierung am Rand (unbekannte IDs ablehnen)
    └── Konsumenten (GUI-Picker, API, Engine, Tests)

2.2 Verbindliche Prinzipien

Prinzip	Kanshō
Eine autoritative ID-Liste pro Erweiterungstyp	Router und UI duplizieren keine Listen
IDs sind stabile Verträge	Rename = neuer Key + Deprecation
Metadaten getrennt von Implementierung	Admin/Export brauchen den Resolver nicht
Zwei Phasen: Kanon, dann Runtime-Binding	Auto-Registration per Package-Import
Validierung an der Registry-Grenze	unbekannte Keys scheitern früh
Konsumenten-agnostisch	dieselbe Registry für Engine, Admin, Diagnose
Erweiterungs-Checkliste	Katalog, Validierung, Test, Versions-Bump
Optional requires_feature	Entitlements nicht in der Registry auflösen
Eine Runtime, kein Spiegel	Mitai-Anti-Pattern PLACEHOLDER_MAP parallel zur Registry nicht nachbauen

2.3 Erste erwartbare Registries (Rahmen, nicht Fachkatalog)

Registry	Zweck	Status der Inhalte
Prompt-/Workflow-Definitionen	ausführbare KI-Bausteine	Engine entschieden; Kanshō-Prompts offen
Kontext-Platzhalter	{{key}} für Engine-Templates (Data Layer)	Muster entschieden; Key-Set offen
Privacy-Platzhalter	[[SELF]] usw. im External Model Context	getrennt von {{key}}; siehe privacy_gateway.md
Feature-IDs	limitierbare Fähigkeiten	Muster entschieden; Liste offen
UI-Katalog (Widgets/Karten/Nav-Beiträge)	konfigurierbare Oberflächenbausteine	Mechanik wie Mitai-Widgets; keine Health-Widgets
optionale Ingest-Module	später, falls Import nötig	Muster ja, Bedarf offen

Neue erweiterbare IDs nur über den jeweiligen Kanon. Keine Ad-hoc-IDs in Prompt-Texten oder Layout-JSON.

---

3. Prompt- und Workflow-Engine

Mitai: prompt_executor.py, workflow_executor.py, Tabelle ai_prompts, Admin-CRUD, Preview, Import/Export.

3.1 Übernehmen

1. Ein Executor als einziger Einstieg für modellgebundene Ausführung (base / pipeline / workflow). Kein zweiter Pfad wie Mitais Legacy insights.py.
2. Prompts und Workflows in der DB (Name, Slug, Kategorie, aktiv, Template, Stages, Graph, Output-Format/Schema), nicht im Anwendungscode.
3. Drei Typen: base (Baustein), pipeline (Sequenz, Stages per Referenz), workflow (Graph, Verzweigung, Join).
4. Platzhalter als Verträge der Kontext-Registry; Templates enthalten {{keys}}, keine eingebettete Berechnung.
5. Admin konfiguriert, Nutzer führt aus (require_admin vs. require_auth).
6. Preview ohne LLM, Debug mit aufgelösten Platzhaltern (Ausgabe erst nach Gateway-Regeln; keine Klasse-A-Werte im Client-Debug).
7. JSON Import/Export Dev→Prod; System-Defaults mit Reset (is_system_default + default_template).
8. LLM-Call nur als injizierte Callback-Funktion, in Kanshō: Callback = Privacy Gateway, nicht Roh-OpenRouter.

3.2 Schichten in der Engine

Schicht	Rolle
Templates / Graphen	Was konfiguriert ist (Admin)
Kontext-Platzhalter	Semantische Keys, Resolver
Data Layer	Werte für Keys (Layer 1)
Privacy Gateway	Minimierung, Pseudonymisierung, Egress, Demasking
Workflow-Executor	Reihenfolge, Verzweigung, Aggregation

Fachliche Reflexions-Workflows (Tagesreflexion, Journal-Entwurf, …) werden später als Konfiguration in dieser Engine registriert, nicht als fest verdrahteter Python. Solange das Fachkonzept unfertig ist, bleibt die Bibliothek leer oder enthält nur technische Test-Prompts.

3.3 Nicht übernehmen

• Parallele Template-Engines und direkte LLM-Calls neben dem Executor.
• Doppelte Workflow-Speicher (graph_data und workflow_definitions).
• Frontend-Workflow-Editor ohne RequireAdmin (Mitai-Lücke).
• Unversioniertes Overwrite ohne Reset-Pfad.
• Debug-Responses mit Klarnamen oder vollem Internal Context.
• Vermischung von {{key}} (Kontext) und [[ROLE]] (Privacy).

Modellname und Endpoint-URL liegen in Admin-Konfiguration (provider_settings); Secrets bleiben Env. Routing-Policy später über Konfiguration, nicht über neue Executoren.

---

4. Weitgehende Konfigurierbarkeit

Ziel wie Mitai: Einfachheit in der Nutzer-UX, Differenzierung in administrierbarer Konfiguration.

4.1 Administrierbar (DB / Admin-UI)

• Prompt-Texte, Pipelines, Workflow-Graphen, Aktiv/Sortierung, Output-Schema
• Feature-Definitionen und Limits (wenn Entitlements genutzt werden)
• UI-Katalog: welche Karten/Nav-Beiträge sichtbar, Layout-Overrides
• System-Prompts vs. Instanz-Anpassungen (Reset auf Default)
• Provider-URL, Modell und ZDR/No-Train für Generate und Detect (provider_settings, Admin Schnittstellen)
• Additiv 2026-09-08: benannte LLM-Profile (llm_profiles); aktive Zuordnung je Stufe. Secrets bleiben Env.
• später: Privacy-Profile (Strict/Balanced), sobald fachlich konkret

4.2 Code / Env (nicht pro Klick im Admin)

• Registry-Schema und Resolver-Implementierungen
• Auth-Gates, Privacy-Pipeline-Schritte, Fail-Closed
• Breakpoint, Router-Zuschnitt, Migrationsmechanismus
• Provider-Secrets

4.3 Durchsetzung

Keine Sonderlogik „nur dieses eine Feature hardcodiert im Router“, wenn es ein Registry- oder Prompt-Fall ist. Lint/Konvention: neue KI-Aufrufe nur über den Executor.

Nicht administrierbar: Abschalten oder Umgehen des Privacy Gateway, Speichern voller Prompts beim Provider, Training-Freigabe für persönliche Kontexte, Fail-Open auf unsichere Endpoints.

---

5. Data Layer als SSoT

Mitai Layer 0 → 1 → 2a/2b. Kanshō übernimmt die Trennung, nicht die Körper-Metriken.

Schicht	Kanshō-Rahmen
0 Persistenz	PostgreSQL, profilbezogen
1 Ableitung	eine Stelle für berechnete/verdichtete Werte, die mehrere Konsumenten brauchen
2a KI	Platzhalter-Resolver liest Layer 1, formatiert für Templates
2b UI	Chart/Listen-Payloads aus Layer 1, keine zweite Formel in React

Router und React rechnen keine parallelen Scores. Welche Layer-1-Funktionen existieren, folgt dem späteren Fachstand (Summaries, Saturation, …) und wird dann registriert, nicht vorab erfunden.

---

6. Feature- und Entitlement-Muster

Mitai trennt Identität (Auth) von „darf Feature X wie oft?“. Kanshō übernimmt die zentrale check_feature_access-Idee an der API, nicht das Fitness-Abo als Produkt.

• Eine Feature-Registry.
• Enforcement in der API, nicht nur in der UI.
• Kataloge referenzieren Feature-IDs, lösen Tiers nicht selbst auf.
• Ob Tiers, Trials oder nur an/aus gebraucht werden, ist offen (Fach- und Produktstand). Die Erweiterungspunkte werden trotzdem so gebaut, dass Limits später ohne Router-Umbau möglich sind.

6.1 Verlustfreie spätere Ausprägung

Der Code enthält absichtlich kein fertiges Abo. Er enthält die Auflösungshierarchie, damit Tarif, Limit und Billing später Zeilen und Policies sind, keine neue Auth.

Später	Wohin	Nicht wohin
Weitere Tiers / Limits	tiers, tier_limits, Seed/Admin	Router, React, profiles.role
Nutzer einem Tarif zuweisen	profiles.tier_id	neues Account-Modell
Usage nach erfolgreichem Call	increment_feature_usage (bereits vorhanden, noch nicht am Erfolgspfad)	Frontend-Zähler
User-Overrides	user_feature_restrictions	Hardcode in check_feature_access
Billing / Stripe / Familienabo	eigene Billing-Schicht oder zentrales Jinkendo-Abo	Kanshō-Auth, Prompt-Engine
Feinere Rechte (Prompts vs. Diagnose)	Permission-Gate über require_admin, Rolle bleibt grob	Feature-IDs als Pseudo-Rollen
Neue limitierbare Fähigkeit	Zeile in features + Check an der API	neue Spalte max_* am Profil

Bestehende Sessions, Profile und Prompt-Rows bleiben gültig. Ein späteres Abo ist ein Fill-in dieser Tabellen plus Enforcement, kein Schnitt durch Login oder Gateway.

---

7. Konfigurierbare UI-Bausteine

Mitai-Dashboard-Widgets: Backend-Katalog, Frontend-Register, Config-Whitelist, allowed/Entitlement, graceful unknown ID.

Kanshō übernimmt diese Mechanik für spätere Oberflächenbausteine (z. B. Einstiegsimpulse, Diagnosekarten). Es werden keine Mitai-Gewichts-/Schlaf-Widgets kopiert. Solange die IA unfertig ist, kann der Katalog leer oder auf Shell-Platzhalter beschränkt sein.

---

8. Erweiterungs-Checkliste (neues Modul)

Analog Mitai-Übergabe, für Kanshō:

1. Registry-Kanon: ID, Metadaten, Tests auf Eindeutigkeit.
2. Implementierung registriert sich (Package-Import).
3. Validierung am Rand.
4. API-Router des Moduls; keine Business-Logik nur im Frontend.
5. Optional Prompt/Workflow in der Engine, Ausführung nur über Executor + Gateway.
6. Optional Feature-ID und Admin-Sichtbarkeit.
7. MODULE_VERSIONS / App-Version anpassen.
8. Kein zweiter Ausführungspfad.

---

9. Entscheidungsstand

Thema	Stand	Status
Einheitliches Registry-Muster	ja	entschieden
Prompt-/Workflow-Engine mit DB-Konfiguration	ja	entschieden
Ein Executor, Callback = Privacy Gateway	ja	entschieden
Admin konfiguriert, User führt aus	ja	entschieden
Data Layer SSoT	ja	entschieden
Feature-Check an der API (Muster)	ja	entschieden
Konkrete Prompts, Keys, Features, Widgets	–	offen (Fachstand)
Mitai-Membership als Produkt	–	nicht übernehmen
Doppel-Registry / Legacy-Executor	–	verworfen

10. Offene Fragen

Rahmen-Slice (User-Admin, Prompt-DB, Platzhalter-Registry, Feature-Check) ist im Code angelegt. Bleibt offen:

1. Liegen später fachliche System-Prompts zusätzlich als JSON im Git (prompts.seed.json) oder nur in der DB mit Export-Disziplin? Der Lade-Pfad existiert; die Datei ist bewusst leer.
2. Braucht Kanshō früh Limits ungleich unbegrenzt, oder bleibt ai_calls ohne Kontingent bis zur Produktentscheidung?
3. Selbst-Registrierung vs. nur Admin legt Nutzer an.

11. Querverweise

• Mitai: Foundation #1 Prompt Engine, #2 Data Layer, #3 Entitlements, #4 Registry, #7 Widgets
• Technisch: ai_architecture.md, backend_and_api.md, admin_diagnostics.md, privacy_gateway.md, data_architecture.md
• Fachlich: Arbeitsstand, nicht als Prompt-Inhalte vorwegnehmen