12 KiB
| 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:
- Neue Fähigkeiten kommen als registrierte Komponenten hinzu, nicht als Sonderpfade in Routern oder React.
- KI läuft über eine Prompt-/Workflow-Engine, nicht über verstreute Provider-Calls.
- Soweit fachlich sinnvoll, liegen Texte, Graphen, Sichtbarkeit und Limits in administrierbarer Konfiguration, nicht im Deploy-Code.
- Berechnungen haben eine Single Source of Truth (Data Layer); UI und KI konsumieren dieselbe Schicht.
- 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
- Ein Executor als einziger Einstieg für modellgebundene Ausführung (
base/pipeline/workflow). Kein zweiter Pfad wie Mitais Legacyinsights.py. - Prompts und Workflows in der DB (Name, Slug, Kategorie, aktiv, Template, Stages, Graph, Output-Format/Schema), nicht im Anwendungscode.
- Drei Typen:
base(Baustein),pipeline(Sequenz, Stages per Referenz),workflow(Graph, Verzweigung, Join). - Platzhalter als Verträge der Kontext-Registry; Templates enthalten
{{keys}}, keine eingebettete Berechnung. - Admin konfiguriert, Nutzer führt aus (
require_adminvs.require_auth). - Preview ohne LLM, Debug mit aufgelösten Platzhaltern (Ausgabe erst nach Gateway-Regeln; keine Klasse-A-Werte im Client-Debug).
- JSON Import/Export Dev→Prod; System-Defaults mit Reset (
is_system_default+default_template). - 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_dataundworkflow_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) - 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ō:
- Registry-Kanon: ID, Metadaten, Tests auf Eindeutigkeit.
- Implementierung registriert sich (Package-Import).
- Validierung am Rand.
- API-Router des Moduls; keine Business-Logik nur im Frontend.
- Optional Prompt/Workflow in der Engine, Ausführung nur über Executor + Gateway.
- Optional Feature-ID und Admin-Sichtbarkeit.
MODULE_VERSIONS/ App-Version anpassen.- 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:
- 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. - Braucht Kanshō früh Limits ungleich unbegrenzt, oder bleibt
ai_callsohne Kontingent bis zur Produktentscheidung? - 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