---
title: "Kanshō – Plattformprinzipien: Registry, Prompt Engine, Konfiguration"
version: "0.1"
status: "Arbeitsstand"
date: "2026-08-19"
product_family: "Jinkendo"
document_role: "Technical Chapter / Extensibility / Registry / Prompt Engine / Configuration"
parent_document: "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

```text
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)
- 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