Update .gitignore to exclude Python-related files and directories. Enhance AGENTS.md and README.md with clarifications on documentation structure and product identity. Add technical architecture references and local setup instructions. Revise privacy guardrails and product identity documents for consistency. Remove obsolete memory and context documentation. Expand reflection spaces documentation to define context boundaries and lifecycle. Ensure all changes align with the ongoing development of the Kanshō project.
This commit is contained in:
1 parent
3a367b7bcc
commit
d62673e48b
89 files changed
+13463
-241
No files matched your search
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Kanshō – Admin- und Diagnoseansicht"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Admin / Diagnostics"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Admin- und Diagnoseansicht
|
||||
|
||||
Kanonisches Home für die technische Admin-/Developer View. Fachlich entschieden: `../functional/fachliche_zielarchitektur.md` §2.7, `../functional/reflection_spaces.md`. UI, Berechtigungen im Detail und Rollenfeinheit sind offen.
|
||||
|
||||
## 1. Zweck
|
||||
|
||||
Die normale Oberfläche abstrahiert interne KI-Strukturen.
|
||||
|
||||
Für Entwicklung, Test, Qualitätssicherung und Administration existiert eine **getrennte Realm** (Mitai-Muster: `/admin/*`, `AdminShell`, `RequireAdmin`).
|
||||
|
||||
Reguläre Nutzer erhalten diese Ansicht nicht. Zugriff: Rolle `admin` (v0.1), API und UI gegated (`auth_identity_and_roles.md`).
|
||||
|
||||
## 2. Vorgesehene Diagnoseobjekte
|
||||
|
||||
Herkunft: Fachdoku, hier nur als zu inspizierende technische Objekte:
|
||||
|
||||
- Threads und Thread-Kandidaten
|
||||
- Reflection-Space-Zuordnungen
|
||||
- Konsolidierungsentscheidungen
|
||||
- Memory-Provenance, Confidence, Unsicherheit
|
||||
- Hypothesen vs. bestätigte Aussagen
|
||||
- Context-Builder-Ergebnisse und verwendete Quellen
|
||||
- Strukturänderungen
|
||||
- Privacy: Datenklasse, maskierte Entitätstypen, Provider, ZDR, Policy-Allow/Deny, Response-Validation – **ohne** vollständige Prompts und ohne Mapping als Default
|
||||
|
||||
Echte Mapping-Tabelle nur soweit eine besonders berechtigte Rolle es braucht (`guardrails.md` §17).
|
||||
|
||||
## 3. Was die Diagnose nicht ist
|
||||
|
||||
- kein zweites Nutzerprodukt
|
||||
- keine Aufgabenverwaltung
|
||||
- kein Bypass des Privacy Gateway „zum Debuggen in der Cloud“
|
||||
- keine Anzeige fremder Nutzerdialoge ohne explizites, später zu definierendes Betriebsmodell (Support). Default: Admin sieht Systemzustand und eigene Tests, nicht fremde Lived Experience.
|
||||
|
||||
## 4. Mitai-Übernahme
|
||||
|
||||
Übernehmen: getrennte Nav-Config (`adminNav.js`-Muster), Shell, `RequireAdmin`, Backend `require_admin`, Admin für Prompts/Workflows/Preview/Import-Export analog Mitai (`platform_extensibility.md`).
|
||||
|
||||
Nicht übernehmen: Mitai-Admin für Körpertarife, Coupons, Training Types als Kanshō-Kern. Feature-Admin nur als Muster, wenn Entitlements genutzt werden.
|
||||
|
||||
## 5. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Diagnoseansicht erforderlich | ja | entschieden (fachlich) |
|
||||
| Getrennte Admin-Realm + API-Guard | ja | entschieden |
|
||||
| Rolle v0.1 | `admin` | entschieden |
|
||||
| Feineres Rollenmodell | Hauptadmin vs. Entwickler | offen |
|
||||
| Konkrete Screens und Felder | – | offen |
|
||||
|
||||
## 6. Offene Fragen
|
||||
|
||||
1. Darf ein Admin auf einer Shared Instance jemals fremde Dialoge sehen (Break-glass)?
|
||||
2. Welche Diagnose-Events werden persistiert vs. nur live berechnet?
|
||||
3. Wie werden Thread-Kandidaten dargestellt, ohne ein falsches „fertiges“ State Model zu suggerieren?
|
||||
|
||||
## 7. Querverweise
|
||||
|
||||
- `auth_identity_and_roles.md`, `privacy_gateway.md`, `frontend_pwa_shell.md`, `platform_extensibility.md`
|
||||
- Fachlich: `../functional/reflection_spaces.md` Admin-/Developer View
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "Kanshō – AI-Architektur"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / AI Architecture"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – AI-Architektur
|
||||
|
||||
Kanonisches Home für Inferenzpfad und spätere Agenten. Prompt-Engine und Registries: `platform_extensibility.md`. Egress und Datenklassen: `privacy_gateway.md`.
|
||||
|
||||
## 1. Rolle der KI
|
||||
|
||||
Kanshō ist bewusst stärker KI-kollaborativ als bisherige Jinkendo-Komponenten. Die KI ist Dialogpartner, nicht nur Feature.
|
||||
|
||||
Sie darf Zusammenhänge als **Hypothese** anbieten, keine künstliche Gewissheit und keinen erfundenen Wesenskern. Journalstil folgt dem Writing Profile; Inhalt und Stil sind getrennt zu erzeugen (fachlich bevorzugte Richtung).
|
||||
|
||||
## 2. Laufzeit
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Externe Inferenz für leistungsfähige Dialoge | vorgesehen | entschieden |
|
||||
| Lokale große Modelle als alleinige Basis | derzeit nein | entschieden |
|
||||
| Privacy Gateway vor persönlichem Egress | zwingend | entschieden |
|
||||
| OpenRouter | möglicher Router | kein Zwang |
|
||||
| Lokale kleine Modelle / Fallback | möglich | offen |
|
||||
|
||||
Kein Router, kein Frontend und kein Prompt-String umgeht `privacy_gateway.md`.
|
||||
|
||||
## 3. Engine und Registries
|
||||
|
||||
Verbindlich gemäß `platform_extensibility.md`:
|
||||
|
||||
- ein Executor (`base` / `pipeline` / `workflow`)
|
||||
- Prompts in der DB, Admin-CRUD, Preview, Import/Export
|
||||
- Kontext-Platzhalter `{{key}}` ≠ Privacy-Platzhalter `[[SELF]]`
|
||||
- LLM nur als Gateway-Callback
|
||||
|
||||
Fachliche Reflexions- oder Journal-Prompts sind **Konfiguration**, die später registriert wird – nicht Code und nicht der heutige Fachstand als fest verdrahtete Texte.
|
||||
|
||||
## 4. Agentenrollen
|
||||
|
||||
Interview F3 listet Reflection Agent, Memory Agent, Context Builder, Journal Writer, Critic/Verifier, Routing, Evaluation.
|
||||
|
||||
**Status: offen.** Es wird in v0.1 kein Agentengraph festgeschrieben.
|
||||
|
||||
Technische Mindestanforderung unabhängig von der späteren Zerlegung:
|
||||
|
||||
- Context Builder (wann immer er existiert) erzeugt Internal Context.
|
||||
- Gateway erzeugt External Model Context.
|
||||
- Antworten werden validiert und demaskiert, bevor sie lokal weiterverwendet werden.
|
||||
- Der aktuelle Fachstand zur Strukturierungsautonomie ändert weder Egress-Klasse noch Nutzerhoheit über Identität.
|
||||
|
||||
## 5. Context-Fenster
|
||||
|
||||
Der heutige Fachstand geht davon aus, dass ein LLM-Kontextfenster nicht ausreicht (`memory_and_context.md`). Orchestrierung von Ausschnitten und Re-Grounding bleibt an diesen Stand gekoppelt, ist aber **kein** vorgezogenes Speicherschema. Algorithmen und Token-Budgets: offen.
|
||||
|
||||
Resurfacing und Saturation (aktueller Fachstand) steuern Relevanz, nicht die Egress-Menge. Guardrails bleiben vorrangig.
|
||||
|
||||
## 6. Safety
|
||||
|
||||
Krisen- und Hochrisiko-Grenzen sind fachlich Phase H3 und **offen**. Technisch v0.1: keine psychiatrische Diagnose, keine stillschweigenden Persönlichkeitsprofile. Konkrete Blocklisten und Eskalations-UX später.
|
||||
|
||||
## 7. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Extern + Gateway | ja | entschieden |
|
||||
| Ein Executor / Gateway-Callback | ja | entschieden |
|
||||
| Konkrete Prompt-Bibliothek | später als Config | offen |
|
||||
| Multi-Agent-Zerlegung | – | offen |
|
||||
| Modellwahl und Routing-Policy-Datei | – | offen |
|
||||
| Prompt-Admin (CRUD/Preview/Export) | Mitai-Engine-Muster | entschieden |
|
||||
| Evaluation / Qualitätsmetriken | – | offen |
|
||||
|
||||
## 8. Offene Fragen
|
||||
|
||||
Siehe Interview F3. Zusätzlich: Wie wird das Writing Profile in die Journal-Pipeline injiziert, ohne Klasse-A-Identität zu leaken?
|
||||
|
||||
## 9. Querverweise
|
||||
|
||||
- Fachlich: `../functional/guardrails.md`, `../functional/reflection_intelligence.md`, `../functional/writing_profile_and_journaling.md`
|
||||
- Technisch: `platform_extensibility.md`, `privacy_gateway.md`, `admin_diagnostics.md`
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
title: "Kanshō – Auth, Identität und Rollen"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Auth / Identity / Roles"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Auth, Identität und Rollen
|
||||
|
||||
Kanonisches Home für Login, Session, Rollen und API-Gates. Fachliche Admin-/Developer-View: `../functional/fachliche_zielarchitektur.md` §2.7. Privacy-Identität: `../functional/guardrails.md`.
|
||||
|
||||
Mitai-Referenz: `C:\dev\mitai\.claude\docs\jinkendo-foundation\design-principles\AUTH_SESSION_DESIGN_PRINCIPLES.md`, `backend/auth.py`, `frontend/src/context/AuthContext.jsx`.
|
||||
|
||||
## 1. Fachliche Verantwortung
|
||||
|
||||
Das Auth-Modul übernimmt:
|
||||
|
||||
1. Identität (Profil + Passwort).
|
||||
2. Session (opaques Token in der Datenbank, Ablauf, Logout).
|
||||
3. API-Gates (`require_auth`, `require_admin`).
|
||||
4. Passwort-Lifecycle (Hash, Verify, Reset, Registrierung, E-Mail-Verifizierung).
|
||||
5. Grobe Rollen: `user` | `admin`.
|
||||
|
||||
Es übernimmt **nicht**:
|
||||
|
||||
- Feature-Tiers / Entitlements (eigene Schicht, `platform_extensibility.md` §6).
|
||||
- Org-/Vereinsmandanten.
|
||||
- OAuth/SSO/JWT (Familien-Vision, nicht Rahmen).
|
||||
- Privacy-Pseudonymisierung (→ `privacy_gateway.md`).
|
||||
- fachliche Autorisierung auf Reflexionsinhalten jenseits von `profile_id`.
|
||||
|
||||
Spätere feinere Rollen oder ein Abo ersetzen diese Schicht nicht. Sie hängen **additiv** daran: Session bleibt die Identität, `require_admin` bleibt der grobe Gate, Entitlements bleiben `check_feature_access`. Keine Feature-Limits in `role` und keine Rolle in `tier_id` mischen.
|
||||
|
||||
## 2. Account-Modell
|
||||
|
||||
**Status: entschieden**
|
||||
|
||||
Ein Login (E-Mail) entspricht einem Profil. Kanshō ist keine Multi-Profil-App auf einem Login und keine Vereinsapp.
|
||||
|
||||
Mehrere Nutzer pro Instanz: ja. Jede Session ist an genau ein `profile_id` gebunden. Alle personenbezogenen Tabellen tragen diese Bindung.
|
||||
|
||||
Klarnamen, E-Mail und Mapping-Tabellen sind Klasse A (Local Only). Sie verlassen die Trusted Zone nicht als Teil eines External Model Context.
|
||||
|
||||
## 3. Session-Flow (übernommen)
|
||||
|
||||
Herkunft: Mitai-Implementierung, als Muster.
|
||||
|
||||
1. Login mit E-Mail + Passwort, Rate Limit am Login-Endpoint.
|
||||
2. Passwortprüfung via bcrypt.
|
||||
3. Session-Token (`secrets.token_urlsafe`), Speicherung in `sessions` mit `expires_at`.
|
||||
4. Frontend speichert Token lokal und sendet ihn bei API-Calls (Header-Muster Mitai: `X-Auth-Token`).
|
||||
5. `require_auth` lädt Session + Profil oder antwortet 401.
|
||||
6. Logout invalidiert die Session serverseitig.
|
||||
|
||||
Session-Dauer: Mitai-Default 30 Tage, profilbezogen konfigurierbar. Für Kanshō **bevorzugte Richtung**, konkreter Default später festzulegen.
|
||||
|
||||
Registrierung und E-Mail-Verifizierung: Mitai-Muster übernehmen, SMTP-Konfiguration über Server-`.env`.
|
||||
|
||||
## 4. Rollen
|
||||
|
||||
| Rolle | Nutzer-PWA | Admin-/Developer View | Status |
|
||||
|---|---|---|---|
|
||||
| `user` | eigene Reflexionsdaten | nein | entschieden |
|
||||
| `admin` | eigenes Nutzerkonto plus Verwaltungs- und Diagnosezugriff | ja | entschieden |
|
||||
|
||||
Konkretes feineres Rollenmodell (Hauptadmin vs. Entwickler) ist fachlich offen (`produktvision_und_produktidentitaet.md` Entscheidungsstand). Technisch v0.1: zwei Rollen wie Mitai. Weitere Rollen nur nach fachlicher Entscheidung.
|
||||
|
||||
UI-Guard analog `RequireAdmin.jsx`. Backend-Guard analog `require_admin`. Die UI ist kein Ersatz für den API-Guard.
|
||||
|
||||
## 5. Bewusst nicht übernehmen (Mitai-Lücke)
|
||||
|
||||
Mitai dokumentiert eine bekannte Schwäche: ein Profile-Header (`X-Profile-Id`) ohne harte Bindung an die Session ermöglicht IDOR.
|
||||
|
||||
**Status: verworfen für Kanshō**
|
||||
|
||||
Regeln:
|
||||
|
||||
- Die aktive Identität kommt ausschließlich aus der Session.
|
||||
- Kein Client-Header darf ein anderes `profile_id` wählen.
|
||||
- Jede Query auf personenbezogene Daten filtert mit dem Session-Profil.
|
||||
- Tests müssen fremden Ressourcenzugriff ablehnen.
|
||||
|
||||
Historische Multi-Profil-Endpunkte von Mitai (`/profiles` als Umschalter) werden nicht nachgebaut.
|
||||
|
||||
## 6. Token-Speicherung im Client
|
||||
|
||||
Mitai nutzt `localStorage`. Das ist für eine First-Party-PWA akzeptabel, aber XSS-sensitiv.
|
||||
|
||||
**Status: bevorzugte Richtung** – gleiches Muster wie Mitai für den Rahmen, mit der Maßgabe, später HttpOnly-Cookie vs. localStorage zu bewerten (`security.md`).
|
||||
|
||||
Keine Secrets, API-Keys oder Identity-Mappings im Frontend-Bundle.
|
||||
|
||||
## 7. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Server-Sessions | opaque Token in DB | entschieden |
|
||||
| Rollen | `user` \| `admin` | entschieden |
|
||||
| 1 Login = 1 Profil | ja | entschieden |
|
||||
| IDOR-Header-Profilwahl | nicht übernehmen | verworfen |
|
||||
| JWT/SSO | nicht Rahmen | verworfen für v0.1 |
|
||||
| Session-Länge | ~30 Tage | bevorzugte Richtung |
|
||||
| Feineres Rollenmodell | später | offen |
|
||||
| Token-Ablage Client | localStorage wie Mitai | bevorzugte Richtung |
|
||||
|
||||
## 8. Offene Fragen
|
||||
|
||||
1. First-Run-Setup (erster Admin) exakt wie Mitai `SetupScreen`?
|
||||
2. Selbst-Registrierung offen oder einladungsgesteuert?
|
||||
3. Gemeinsame Jinkendo-Identität später: Migrationspfad von Sessions zu SSO offenhalten, ohne ihn jetzt zu bauen.
|
||||
|
||||
## 9. Querverweise
|
||||
|
||||
- Fachlich: `../functional/guardrails.md` §4–5, `../functional/fachliche_zielarchitektur.md` §2.7
|
||||
- Technisch: `admin_diagnostics.md`, `security.md`, `privacy_gateway.md`
|
||||
- Mitai: `AUTH.md`, `AUTH_SESSION_DESIGN_PRINCIPLES.md`
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: "Kanshō – Backend und API"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Backend / API"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Backend und API
|
||||
|
||||
Kanonisches Home für FastAPI-Struktur, Router-Schnitt und API-Vertrag. Mitai-Referenz: `.claude/rules/ARCHITECTURE.md` §1, `backend/main.py`, `backend/routers/`.
|
||||
|
||||
## 1. Prinzipien
|
||||
|
||||
Herkunft: Mitai-Architekturregeln, als Rahmen übernommen.
|
||||
|
||||
### 1.1 Ein Modul = ein Router
|
||||
|
||||
Jedes fachliche Modul besitzt genau eine Router-Datei unter `backend/routers/`. Endpoints liegen nicht in `main.py` außer Health/Status.
|
||||
|
||||
Neue Module = neue Datei, Registrierung via `app.include_router(..., prefix="/api")`.
|
||||
|
||||
Rahmen-Module (erste erwartbare Dateien, keine vollständige Liste):
|
||||
|
||||
- `auth`
|
||||
- `profiles`
|
||||
- später: Dialog, Memory, Journal-Handoff, Gateway-Audit-Metadaten, Admin-Diagnose
|
||||
|
||||
Domänenrouter für Mitai-Tracking werden nicht angelegt.
|
||||
|
||||
### 1.2 API-First
|
||||
|
||||
Jede vom UI benötigte Funktion ist zuerst ein Endpoint. Das Frontend spricht ausschließlich diese API (Mitai: `utils/api.js`). Keine fachliche Berechnung, kein Context-Building und kein Privacy-Demasking im Browser.
|
||||
|
||||
### 1.3 Fehlerformat
|
||||
|
||||
```text
|
||||
HTTPException → {"detail": "menschenlesbare Meldung"}
|
||||
```
|
||||
|
||||
Keine parallelen Formate (`error`, `success: false`). Herkunft: Mitai.
|
||||
|
||||
### 1.4 Auth an der Grenze
|
||||
|
||||
Geschützte Routen nutzen `Depends(require_auth)` bzw. `require_admin`. Ressourcenfilter immer über Session-`profile_id`. Siehe `auth_identity_and_roles.md`.
|
||||
|
||||
## 2. Schichten im Backend
|
||||
|
||||
Bevorzugte innere Trennung, analog Mitai plus Kanshō-spezifische Gateway-Schicht:
|
||||
|
||||
```text
|
||||
routers/ HTTP, Validierung, Auth-Depends
|
||||
services/ fachliche Orchestrierung (später)
|
||||
privacy_gateway/ Minimierung, Pseudonymisierung, Egress, Validation
|
||||
data/ PostgreSQL-Zugriff
|
||||
```
|
||||
|
||||
**Status: bevorzugte Richtung** für Ordnernamen. Kein Zwang, Mitai-Dateibaum 1:1 zu klonen, wenn die Trennlinie Router / Gateway / Persistenz klar bleibt.
|
||||
|
||||
Privacy Gateway darf nicht umgangen werden, indem ein Router den Provider direkt aufruft. KI-Ausführung nur über die Prompt-Engine (`platform_extensibility.md`), Callback = Gateway.
|
||||
|
||||
## 3. Versionierung
|
||||
|
||||
Mitai führt `backend/version.py` mit `APP_VERSION` und `MODULE_VERSIONS`.
|
||||
|
||||
**Status: bevorzugte Richtung** – gleiches Muster für Kanshō, sobald Code existiert. Semantic Versioning.
|
||||
|
||||
## 4. Health und Betrieb
|
||||
|
||||
Ein ungeschützter oder schwach geschützter Status-Endpoint für Deploy-Healthchecks analog Mitai `/api/auth/status` bzw. Health nach Container-Start.
|
||||
|
||||
Konkreter Pfad: offen, Muster übernommen.
|
||||
|
||||
## 5. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| FastAPI + ein Router je Modul | ja | entschieden |
|
||||
| API-First, keine Business-Logik im Frontend | ja | entschieden |
|
||||
| Fehlerkörper `{detail}` | ja | entschieden |
|
||||
| Direktaufruf externer LLMs aus Routern | verboten | entschieden |
|
||||
| OpenAPI als dokumentierter Vertrag | später | offen |
|
||||
| Interne service-Schicht vs. fette Router | service-Schicht | bevorzugte Richtung |
|
||||
|
||||
## 6. Offene Fragen
|
||||
|
||||
1. Internes API für mindnet/Kairo: synchron REST vs. Events? → `integrations_technical.md`
|
||||
2. Idempotenz-Keys für Offline-Sync-Queue? → `memory_storage_and_offline.md`
|
||||
3. Rate Limits außer Auth: welche Dialog-Endpoints?
|
||||
|
||||
## 7. Querverweise
|
||||
|
||||
- Technisch: `auth_identity_and_roles.md`, `privacy_gateway.md`, `runtime_and_deploy.md`
|
||||
- Mitai: `ARCHITECTURE.md` §1, `INTERNAL_API_REFERENCE.md`
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: "Kanshō – Datenarchitektur"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Data Architecture"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Datenarchitektur
|
||||
|
||||
Kanonisches Home für Persistenzgrenzen **ohne** vorgezogenes SQL-Schema. Ableitungen, die UI und KI gemeinsam brauchen, folgen dem Data-Layer-Muster in `platform_extensibility.md` (Layer 0/1/2), sobald der Fachstand konkrete Funktionen hergibt.
|
||||
|
||||
## 1. Speicherverantwortung
|
||||
|
||||
Herkunft: `../functional/memory_and_context.md` §11, bevorzugte Richtung, technisch zu validieren.
|
||||
|
||||
| System | Besitz | Nicht besitzen |
|
||||
|---|---|---|
|
||||
| Kanshō / PostgreSQL | laufender Dialog, Session, Thread-Arbeitsstand, Working Context, lokale Kontinuitätsstrukturen | langfristiges Wissensnetz als Primärgraph |
|
||||
| mindnet | langfristiges Wissen, Retrieval, Edges, Reflection Memories, Knowledge Deltas | exakte Dialogreihenfolge, Offline-Branching |
|
||||
| Obsidian | menschenlesbares Archiv, Journal Entries | interne Thread-Zustände |
|
||||
|
||||
**Status: bevorzugte Richtung** für die Verteilung; Validierung bleibt offen.
|
||||
|
||||
Kanshō erzeugt kein proprietäres geschlossenes Langzeitarchiv, das Obsidian ersetzen würde.
|
||||
|
||||
## 2. Aktueller Fach-Arbeitsstand (nicht final)
|
||||
|
||||
Die folgenden Punkte stehen heute in der Fachdoku. Sie sollen bei einer späteren Persistenz **nicht stillschweigend verloren gehen**. Sie sind **kein** Auftrag, jetzt Tabellen, Enums oder State Machines daraus zu bauen. Ändert die Fachkonzeption sie, gilt der neue Fachstand.
|
||||
|
||||
1. **Originaldialog ist Primärquelle.** Summaries, Thread Memories und Space-Zustände sind abgeleitet. Re-Grounding rekonstruiert aus Ursprungsquellen (`context_fidelity_and_regrounding.md`).
|
||||
2. **Session Lifecycle ≠ Thread Lifecycle.** Das Ende einer Nutzungssitzung schließt Threads nicht automatisch (`reflection_outputs.md`). Tabellen und Statusfelder müssen beide Zyklen unabhängig abbilden können.
|
||||
3. **Lived Experience / Point-in-Time Self.** Frühere Innenperspektiven werden nicht durch heutige Summaries überschrieben (`self_model_and_lived_experience.md`). Versionierung und Zeitbindung sind erforderlich, sobald Self-Model-Daten persistiert werden.
|
||||
4. **Hypothese ≠ bestätigte Erkenntnis.** Self-Model-Änderungen nicht stillschweigend schreiben.
|
||||
5. **Action Candidates** sind Handoffs nach Kairo, keine Kanshō-Aufgabenliste.
|
||||
6. **Resurfacing ≠ Speicherung.** Langfristig gespeichert heißt nicht aktuell relevant (`resurfacing_and_saturation.md`).
|
||||
|
||||
## 3. Fachliche Entitäten (noch kein Schema)
|
||||
|
||||
Die folgende Liste spiegelt den **heutigen** Fachstand. Sie ist ein Merkzettel, keine Tabellendefinition und keine Zusage, dass all diese Objekte so bleiben. Welche Objektarten und Beziehungen ein späteres Schema **erfüllen** muss, steht als Vertrag in `memory_storage_and_offline.md` §3a.
|
||||
|
||||
| Entität | Fachliches Home | Technische Erwartung v0.1 |
|
||||
|---|---|---|
|
||||
| Profile / Session | dieses Kapitel + `auth_identity_and_roles.md` | Kanshō-DB, Rahmen |
|
||||
| Conversation / Message | `dialogue_model.md` | Kanshō-DB, Originalrepräsentation |
|
||||
| Thread (kein fertiges State Model) | `dialogue_model.md`, `resurfacing_and_saturation.md` | Kanshō-DB; Zustände nicht als geschlossene Enum vortäuschen |
|
||||
| Reflection Space | `reflection_spaces.md` | Kanshō-DB, sichtbare vs. interne Struktur trennen |
|
||||
| Working / Thread Memory | `memory_and_context.md` | Kanshō-DB, quellengebunden |
|
||||
| Episodic / Journal / Memory / Knowledge Delta | `reflection_outputs.md` | Handoff-Ziele mindnet/Obsidian |
|
||||
| Action Candidate | `reflection_outputs.md` | Handoff Kairo |
|
||||
| Self Model Version | `self_model_and_lived_experience.md` | lokal, versioniert, Bestätigungspflicht |
|
||||
| Writing Profile | `writing_profile_and_journaling.md` | lokal langfristig |
|
||||
| Provenance / Confidence | `context_fidelity_and_regrounding.md` | an abgeleiteten Strukturen, nicht nur an Originalen |
|
||||
| Privacy Mapping | `guardrails.md` | Klasse A, nur lokal |
|
||||
|
||||
Kein Thread-State-Machine-Kapitel in v0.1. Die fachlich genannten Zustände (`Open`, `Anchored / Resurface`, `Dormant`, `Resolved`) sind **nicht abschließend**.
|
||||
|
||||
## 4. Was nicht in der Kanshō-DB landen soll
|
||||
|
||||
- Vollständiges mindnet-Graphmodell als Kopie.
|
||||
- Kairo-Projekte, Tasks, Rituale als führendes System.
|
||||
- Mitai-Vital- und Trainingsrohdaten als zweites Tracking.
|
||||
- Identity-Mapping in Backup-Logs oder Prompt-Archiven.
|
||||
|
||||
## 5. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Kanshō besitzt den Dialogspeicher | ja | bevorzugte Richtung |
|
||||
| mindnet besitzt langfristiges Gedächtnis | ja | bevorzugte Richtung |
|
||||
| Obsidian menschenlesbares Archiv | ja | bevorzugte Richtung |
|
||||
| Session ≠ Thread / Originaldialog / Handoffs | aktueller Fach-Arbeitsstand | nicht einfrieren |
|
||||
| SQL-Schema / IDs / Edges | nein | offen |
|
||||
| Thread-Zustandsmenge | nicht schließen | offen |
|
||||
| Gemeinsame IDs mit mindnet/Obsidian | nötig, Form unbekannt | offen |
|
||||
|
||||
## 6. Offene Fragen
|
||||
|
||||
Entsprechen den Interview-Leitfragen Phase F1/F4 und werden hier nicht vorab beantwortet: kanonische IDs, Backlinks, welche Strukturen nur in Obsidian existieren, Schema für Reflection Memory und Knowledge Delta.
|
||||
|
||||
## 7. Querverweise
|
||||
|
||||
- `memory_storage_and_offline.md`, `integrations_technical.md`, `privacy_gateway.md`, `platform_extensibility.md`
|
||||
- Fachlich: `memory_and_context.md`, `reflection_outputs.md`, `self_model_and_lived_experience.md`
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: "Kanshō – Technischer Dokumentationsindex und Context Bundles"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Documentation Index / Technical Context Loading Guide"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Technischer Dokumentationsindex
|
||||
|
||||
Für technische Arbeit nur die benötigten Dateien laden. Fachliche Homes nicht durch technische Kurzfassungen ersetzen. Dialog-/MVP-Stand nicht als final behandeln. **Datenschutz und Guardrails** (`../functional/guardrails.md`) sind verbindliche Invariante. Mitai-Produktrahmen weitgehend übernehmen, Gateway nicht umgehen.
|
||||
|
||||
## 1. Root-Dokumente
|
||||
|
||||
Technisch:
|
||||
|
||||
- `technische_zielarchitektur.md` – Governance, Stack, Kapitelkarte, Entscheidungsstand.
|
||||
- `documentation_index.md` – dieser Index.
|
||||
|
||||
Fachlich zusätzlich immer bei Querschnittsentscheidungen:
|
||||
|
||||
- `../functional/fachliche_zielarchitektur.md`
|
||||
- `../functional/produktvision_und_produktidentitaet.md`
|
||||
|
||||
## 2. Technische Kapitel
|
||||
|
||||
| Datei | Kanonisches Thema |
|
||||
|---|---|
|
||||
| `product_frame_and_stack.md` | 3-Tier, Stack, Mitai-Übernahme |
|
||||
| `auth_identity_and_roles.md` | Sessions, Rollen, Admin-Gate |
|
||||
| `frontend_pwa_shell.md` | PWA, Responsive Shell, Navigation |
|
||||
| `backend_and_api.md` | Router, API-First |
|
||||
| `runtime_and_deploy.md` | Migrationen, Compose, Gitea |
|
||||
| `platform_extensibility.md` | Registry, Prompt-Engine, Konfiguration |
|
||||
| `data_architecture.md` | Persistenzgrenzen, Entitäten |
|
||||
| `memory_storage_and_offline.md` | Dialogspeicher, Sync, Offline |
|
||||
| `privacy_gateway.md` | Trust Zones, Egress, Demasking |
|
||||
| `ai_architecture.md` | Inferenzpfad, Agenten |
|
||||
| `integrations_technical.md` | Technische Handoffs |
|
||||
| `admin_diagnostics.md` | Diagnoseansicht |
|
||||
| `voice_and_media.md` | Sprache und Transkription |
|
||||
| `security.md` | Security-Baseline |
|
||||
|
||||
## 3. Empfohlene Context Bundles
|
||||
|
||||
### Produktrahmen / erste Shell
|
||||
|
||||
1. `technische_zielarchitektur.md`
|
||||
2. `product_frame_and_stack.md`
|
||||
3. `auth_identity_and_roles.md`
|
||||
4. `frontend_pwa_shell.md`
|
||||
5. `backend_and_api.md`
|
||||
6. `runtime_and_deploy.md`
|
||||
7. `platform_extensibility.md`
|
||||
8. fachlich: `../functional/produktvision_und_produktidentitaet.md` §19 und §21
|
||||
|
||||
### Produktrahmen / Erweiterung
|
||||
|
||||
1. `technische_zielarchitektur.md`
|
||||
2. `platform_extensibility.md`
|
||||
3. `privacy_gateway.md`
|
||||
4. `ai_architecture.md`
|
||||
5. `backend_and_api.md`
|
||||
6. `admin_diagnostics.md`
|
||||
|
||||
### Privacy / externe KI
|
||||
|
||||
1. `technische_zielarchitektur.md`
|
||||
2. `privacy_gateway.md`
|
||||
3. `platform_extensibility.md`
|
||||
4. `ai_architecture.md`
|
||||
5. `security.md`
|
||||
6. fachlich: `../functional/guardrails.md`
|
||||
7. bei Bedarf: `../functional/self_model_and_lived_experience.md`, `../functional/memory_and_context.md`
|
||||
|
||||
### Dialogspeicher / Memory / Offline
|
||||
|
||||
1. `data_architecture.md`
|
||||
2. `memory_storage_and_offline.md`
|
||||
3. fachlich: `../functional/memory_and_context.md`
|
||||
4. `../functional/context_fidelity_and_regrounding.md`
|
||||
5. `../functional/reflection_outputs.md`
|
||||
6. `../functional/resurfacing_and_saturation.md`
|
||||
|
||||
### Integrationen
|
||||
|
||||
1. `integrations_technical.md`
|
||||
2. fachlich: `../functional/integrations.md`
|
||||
3. `../functional/reflection_outputs.md`
|
||||
4. das betroffene Fachkapitel (Kairo, mindnet, Mitai, Shinkan)
|
||||
|
||||
### Admin / Diagnose
|
||||
|
||||
1. `admin_diagnostics.md`
|
||||
2. `auth_identity_and_roles.md`
|
||||
3. fachlich: `../functional/fachliche_zielarchitektur.md` §2.7
|
||||
4. `../functional/reflection_spaces.md` (Admin-/Developer View)
|
||||
|
||||
### Voice / PWA-Offline
|
||||
|
||||
1. `frontend_pwa_shell.md`
|
||||
2. `voice_and_media.md`
|
||||
3. `memory_storage_and_offline.md`
|
||||
4. `privacy_gateway.md` (eigener Egress-Typ)
|
||||
5. fachlich: `../functional/produktvision_und_produktidentitaet.md` §19.4–19.5
|
||||
|
||||
## 4. Ladeprinzip
|
||||
|
||||
> Root-Dokumente plus 2–4 betroffene Kapitel. Nicht den ganzen technischen und fachlichen Ordner gleichzeitig laden.
|
||||
|
||||
Vor Vereinfachungen die Invariantenliste in `technische_zielarchitektur.md` §3.6 prüfen.
|
||||
|
||||
## 5. Code-Gerüst
|
||||
|
||||
Lokaler Produktrahmen in `frontend/` und `backend/`. Auth, Nutzerverwaltung, Prompt-DB, Platzhalter, Feature-Check, Privacy-Gateway-Stub. **Dialog-Layer 0:** Conversations/Messages/`usage_sessions`, Thread-/Space-Identität, Derived-Hülle mit Provenance. Keine Dialog-IA, keine Domain-Prompts, kein Stripe. SQLite nur lokal.
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: "Kanshō – Frontend-PWA-Shell und Navigation"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / PWA Shell / Navigation / Responsive"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Frontend-PWA-Shell und Navigation
|
||||
|
||||
Kanonisches Home für PWA-Hülle, Breakpoint und Navigations**mechanik**. Die Mitai-Shell wird weitgehend übernommen. Welche Kanshō-Orte später in dieser Shell stehen, folgt dem **dann aktuellen** Fachstand – der heutige Dialog-/Entry-Stand ist nicht final und wird hier nicht als technische Startroute eingefroren.
|
||||
|
||||
Mitai-Referenz: `NAVIGATION_IA_DESIGN_PRINCIPLES.md`, `frontend/src/config/appNav.js`, `frontend/src/app.css`, Shells unter `frontend/src/layouts/`.
|
||||
|
||||
## 1. Was die Shell übernimmt
|
||||
|
||||
1. Progressive Web App, installierbar, Service Worker über Vite PWA-Plugin.
|
||||
2. Mobile First, vollwertiges Desktop-Layout.
|
||||
3. Ein Breakpoint: **1024px** (Mitai). Darunter Bottom-Nav, darüber Desktop-Sidebar.
|
||||
4. Safe Area / Content-Padding für iOS-Homescreen.
|
||||
5. Eine Navigations-SSoT analog `appNav.js` (Reihenfolge, Labels, Icons, Admin-Sichtbarkeit).
|
||||
6. Bereichs-Shells, wenn ein Top-Level-Bereich eigene Sub-Navigation braucht.
|
||||
7. Getrennte Admin-Realm mit `RequireAdmin`.
|
||||
|
||||
Die Shell übernimmt die Mitai-Mechanik. Mitai-Labels (Übersicht, Erfassen, Verlauf, Ziele, Analyse) sind **Domänenplatzhalter**. Sie dürfen in einer ersten Rahmen-Kopie stehen, werden aber nicht mit Mitai-Fachseiten gefüllt. Die spätere Kanshō-IA ersetzt oder benennt sie, sobald das Fachkonzept dafür reif ist.
|
||||
|
||||
## 2. Fachliche Startlogik – nicht technisch einfrieren
|
||||
|
||||
Der aktuelle Fachstand bevorzugt Contextual Continuation statt eines Funktions-Dashboards (`dialogue_model.md`, `produktvision_und_produktidentitaet.md`). Das ist **Arbeitsstand**, kein finaler UX-Schnitt.
|
||||
|
||||
Technische Folge für den Rahmen:
|
||||
|
||||
- Mitai-Home (`/`) und Nav-Mechanik dürfen zunächst wie in Mitai existieren (leere oder minimale Platzhalter).
|
||||
- Es wird **keine** verbindliche Kanshō-Startroute und **keine** endgültige Nav-Item-Liste in v0.1 festgeschrieben.
|
||||
- Interne Fachobjekte (Threads, Spaces, Hypothesen) werden nicht als Nutzer-Verwaltungsnav vorgebaut, nur weil der heutige Fachtext sie nennt.
|
||||
|
||||
## 3. Responsive Muster
|
||||
|
||||
| Viewport | Muster | Status |
|
||||
|---|---|---|
|
||||
| < 1024px | Bottom-Nav, volle Breite, Einhand-Nähe der Primäraktion | entschieden als Rahmen |
|
||||
| ≥ 1024px | Sidebar + Inhaltsfläche; Desktop darf Mehrspalten später nutzen | entschieden als Rahmen |
|
||||
| Lange Dialoge | scrollbarer Verlauf, Eingabe unten; Desktop darf Kontextspalte später ergänzen | bevorzugte Richtung |
|
||||
|
||||
Kein zweites paralleles Layout-System. Zusätzliche Breakpoints nur mit dokumentiertem Grund.
|
||||
|
||||
## 4. PWA
|
||||
|
||||
- `vite-plugin-pwa` wie Mitai.
|
||||
- Manifest, Icons und Offline-Cache gehören zur Shell.
|
||||
- Welche Daten offline schreibbar sind, steht in `memory_storage_and_offline.md` und ist in der Ausprägung **offen**.
|
||||
- Die Shell muss offline zumindest die installierte UI laden können (App Shell Cache). Fachliche Dialog-Offline-Fähigkeit ist davon getrennt.
|
||||
|
||||
## 5. Komponentenrahmen
|
||||
|
||||
Übernehmen als Muster, nicht als Domäne:
|
||||
|
||||
- `AuthContext`
|
||||
- Layout-Shells
|
||||
- Avatar, einfache Markdown-Darstellung wo nötig
|
||||
- keine Mitai-Widgets, Charts oder Capture-Hubs als Kern
|
||||
|
||||
Business-Logik bleibt im Backend (`backend_and_api.md`).
|
||||
|
||||
## 6. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| PWA + Vite PWA Plugin | ja | entschieden |
|
||||
| Breakpoint 1024px | Bottom-Nav / Sidebar | entschieden |
|
||||
| Nav-SSoT + Shells + Admin-Realm | Mitai-Mechanik | entschieden |
|
||||
| Mitai-Nav-Labels als Platzhalter | zulässig im Rahmen | bevorzugte Richtung |
|
||||
| Kanshō-Startroute / endgültige IA | folgt späterem Fachstand | offen |
|
||||
| Desktop-Mehrspalten | späterer Fach-/UX-Stand | offen |
|
||||
|
||||
## 7. Offene Fragen
|
||||
|
||||
1. Welche Platzhalter-Routen bleiben in der ersten Rahmen-Kopie sichtbar, welche werden ausgeblendet, bis Fachseiten existieren?
|
||||
2. Wo liegt Journal-Lesen relativ zum laufenden Dialog (eigene Route vs. Overlay)?
|
||||
3. Wie wird Spracheingabe in der mobilen Chrome platziert, ohne die Dialogfläche zu verdrängen? → `voice_and_media.md`
|
||||
|
||||
## 8. Querverweise
|
||||
|
||||
- Fachlich (aktueller Arbeitsstand, nicht final): `../functional/dialogue_model.md`, `../functional/produktvision_und_produktidentitaet.md` §19
|
||||
- Technisch: `product_frame_and_stack.md`, `auth_identity_and_roles.md`, `admin_diagnostics.md`
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: "Kanshō – Technische Integrationen"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Integrations"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Technische Integrationen
|
||||
|
||||
Kanonisches Home für technische Handoffs. Fachliche Produktgrenzen: `../functional/integrations.md`. Verträge (APIs, Events, Auth zwischen Apps) sind **offen** (Interview F1/F2).
|
||||
|
||||
## 1. Prinzip
|
||||
|
||||
Integrationen folgen der Produktverantwortung, nicht der Bequemlichkeit gemeinsamer Tabellen.
|
||||
|
||||
Kein stilles Mitlesen fremder Datenbanken als Ersatz für einen Vertrag. Berechtigung und Zweckbindung gelten auch familienintern.
|
||||
|
||||
## 2. Handoff-Matrix
|
||||
|
||||
| Gegenüber | Kanshō darf | Kanshō darf nicht | Status Vertrag |
|
||||
|---|---|---|---|
|
||||
| **Kairo** | Ziele/Entwicklungskontext lesen; Action Candidates vorschlagen und zur Übernahme anbieten | Aufgaben, Projekte, Rituale führen | offen |
|
||||
| **mindnet** | Wissen abrufen; Memories und Knowledge Deltas vorschlagen/schreiben gemäß späterem Schema | Working Memory laufender Dialoge ersetzen | offen |
|
||||
| **Obsidian** | Journal und strukturierte Reflexionen ablegen, referenzieren | einziges geschlossenes Archiv sein | offen (Ablage/Sync) |
|
||||
| **Mitai** | bei Kontext und Berechtigung körperlichen Kontext lesen | Vital-/Ernährungs-Tracking nachbauen | offen |
|
||||
| **Shinkan** | Trainingskontext für Reflexion lesen | Trainingsplanung nachbauen | offen |
|
||||
|
||||
Action Candidate fachlich: `../functional/reflection_outputs.md`. Operationalisierung bleibt Kairo.
|
||||
|
||||
## 3. Technische Leitplanken bis zum Vertrag
|
||||
|
||||
- Lesen, Schreiben und „nur vorschlagen / Nutzer bestätigt“ sind drei verschiedene Rechte. Default: vorschlagen.
|
||||
- IDs und Backlinks müssen später kanonisch sein; Format offen.
|
||||
- Egress zu einer Schwester-App ist nicht dasselbe wie LLM-Egress, braucht aber ebenfalls Minimierung identifizierender Daten gegenüber nicht vertrauenswürdigen Netzen.
|
||||
- Shinkan-Vereinsmodell wird nicht nach Kanshō gespiegelt, auch wenn Shinkan-Kontext gelesen wird: Mapping auf den Kanshō-Nutzer, nicht auf einen Verein.
|
||||
|
||||
## 4. Event vs. API
|
||||
|
||||
**Status: offen.** Fachlich sind externe Reflexionstrigger erlaubt (andere Komponenten dürfen Anlässe anbieten; Kairo plant, Kanshō reflektiert). Technische Trigger-Architektur ist bewusst noch nicht abgeleitet (`usage_situations.md`).
|
||||
|
||||
## 5. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Keine Funktionsduplikation | ja | entschieden (fachlich) |
|
||||
| Action Candidates → Kairo | ja | entschieden (fachlich) |
|
||||
| Journal → Obsidian | primär | entschieden (fachlich) |
|
||||
| Konkrete APIs/Events/Auth-Zertifikate | – | offen |
|
||||
| Shared Database | als Integrationsmuster | verworfen als Default |
|
||||
|
||||
## 6. Offene Fragen
|
||||
|
||||
Interview F1/F2 vollständig: welche Daten kanonisch wo liegen, welche Edges mindnet braucht, Obsidian-Pfadkonvention, Bestätigungsdialoge vor Schreib-Handoffs.
|
||||
|
||||
## 7. Querverweise
|
||||
|
||||
- `data_architecture.md`, `privacy_gateway.md`
|
||||
- Fachlich: `../functional/integrations.md`, `../functional/reflection_outputs.md`
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: "Kanshō – Memory-Speicher, Sync und Offline"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Memory Storage / Sync / Offline"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Memory-Speicher, Sync und Offline
|
||||
|
||||
Kanonisches Home für Gedächtnisschichten und Offline, sobald der Fachstand sie trägt. Die Schichtenbeschreibungen unten spiegeln den **heutigen** Fach-Arbeitsstand (`memory_and_context.md`) und sind nicht als finales Speichermodell zu implementieren. Offline-Ausprägung bleibt offen.
|
||||
|
||||
## 1. Schichten
|
||||
|
||||
| Schicht | Lebensdauer (fachlich) | Technische Konsequenz |
|
||||
|---|---|---|
|
||||
| Working Context | Minuten bis Stunden | lokal, hohe Schreibfrequenz, an die aktive Session/Conversation gebunden |
|
||||
| Thread Memory | Tage bis Monate+ | persistiert, quellengebunden, darf nicht die Originalnachrichten ersetzen |
|
||||
| Episodic / langfristig | Jahre | Handoff nach mindnet/Obsidian; Kanshō behält Provenance-Referenzen |
|
||||
|
||||
Ein LLM-Kontextfenster ist kein Speicher. Context Builder wählt Ausschnitte; das Gateway minimiert sie erneut vor Egress.
|
||||
|
||||
## 2. Primärquelle und Re-Grounding
|
||||
|
||||
**Status: fachliche Invariante** (Re-Grounding / Originalquelle). Kein SQL-Schema, keine Drift-Formel in v0.1.
|
||||
|
||||
- Vollständige Dialoge bzw. eine verlässliche Originalrepräsentation bleiben erhalten.
|
||||
- Summaries dürfen laufend fortgeschrieben werden, auch mitten im Dialog, nicht nur am Session-Ende.
|
||||
- Drift-Erkennung und Re-Grounding arbeiten **lokal** auf Originalquellen. Für externe Inferenz wird danach ein neuer minimierter External Model Context erzeugt. Privacy Guardrails werden dabei nicht umgangen.
|
||||
|
||||
Keine unbegrenzte Kette Summary → Summary ohne Rückgriff auf die Quelle.
|
||||
|
||||
Konkrete Drift-Metrik, Granularität und Update-Algorithmen: **offen**.
|
||||
|
||||
## 3a. Strukturelle Vorsorge (Verträge, kein SQL)
|
||||
|
||||
**Status: entschieden als Vorsorge.** Felder, Enums und Tabellennamen bleiben offen. Festgezogen wird, **welche Objektarten und Beziehungen** das Langzeitdialog- und Erinnerungssystem tragen müssen. Herkunft: `memory_and_context.md`, `dialogue_model.md`, `resurfacing_and_saturation.md`, `context_fidelity_and_regrounding.md`, `self_model_and_lived_experience.md`, `reflection_outputs.md`, `reflection_spaces.md`.
|
||||
|
||||
Ein späteres Schema **füllt** diese Verträge. Es darf sie nicht kollabieren (z. B. Thread in der Session aufgehen lassen, Summary als Primärquelle, Handoff als Kanshō-Todo).
|
||||
|
||||
### Objektarten
|
||||
|
||||
| Art | Fachliche Rolle | Darf nicht |
|
||||
|---|---|---|
|
||||
| **Conversation** | Geordnete Originalrepräsentation (Layer 0). Stabile Message-IDs, Reihenfolge, Zeit. | Durch Summary ersetzt oder nur im LLM-Fenster existieren |
|
||||
| **Session** | Eine Nutzungssitzung / Interaktionszyklus inkl. Checkpoint am Ende | Thread mitabschließen |
|
||||
| **Thread** | Reflexionsfaden über Sitzungen hinweg; Zustand und Wiedervorlage am Faden, nicht an der Session | Geschlossene State-Machine vortäuschen; jeder Nebenfaden muss sichtbar sein |
|
||||
| **Thread-Kandidat** | Intern markierter möglicher Faden | Automatisch eigener Chat oder bestätigtes Wissen |
|
||||
| **Working Context** | Kurzlebiger Arbeitsstand der aktiven Conversation | Langzeitgedächtnis; Egress ohne Gateway |
|
||||
| **Thread Memory** | Quellengebundene Verdichtung eines Fadens (Layer 1, versioniert) | Original ersetzen; still als Erkenntnis schreiben |
|
||||
| **Reflection Space** | Lebendiger Kontext über Conversations/Threads | Bloßer Ordner; interne Feinstruktur 1:1 in der UX |
|
||||
| **Reflection Intent** | Absicht *dieser* Interaktion, orthogonal zum Space | Mit Space identisch sein |
|
||||
| **Derived record** | Summary, Hypothese, Emotionseinordnung, Pattern, Kandidat | Ohne Provenance, ohne Zeit, ohne „abgeleitet“-Kennzeichnung |
|
||||
| **Handoff** | Journal / Reflection Memory / Knowledge Delta / Action Candidate | Kanshō-Aufgabenliste; mindnet-Graphkopie |
|
||||
| **External ref** | Nullable Verweis mindnet / Obsidian | Besitz des Langzeitgraphen oder des Archivs |
|
||||
| **Re-grounding event** | Wann, warum, aus welchen Quellen neu abgeleitet wurde | Nur Debug-Log ohne Quellenbindung |
|
||||
| **Identity mapping** | Klasse A, lokal | In Summaries, Prompt-Archiv, mindnet-Handoff |
|
||||
|
||||
Point-in-Time Self / Lived Experience ist **keine eigene frühe Tabelle**, sondern die Konsequenz: Original + zeitgebundene Ableitungen, die frühere Versionen nicht überschreiben.
|
||||
|
||||
### Beziehungen, die das Modell skalieren
|
||||
|
||||
- `profile_id` an jeder personenbezogenen Struktur.
|
||||
- Session 1:n Conversations (oder 1:1, später festlegbar) – **ohne** 1:1 mit Thread.
|
||||
- Conversation n:m Threads (ein Gespräch, mehrere Fäden; ein Faden über mehrere Gespräche).
|
||||
- Thread n:1 oder n:m Spaces (Zuordnung darf vorläufig/unsicher sein).
|
||||
- Jede Ableitung: `source_ids[]` auf Messages/Conversations, `as_of`, `confidence`/`uncertainty`, `kind`.
|
||||
- Sichtbarkeit getrennt von Existenz: intern vs. nutzersichtbar (Space-Regel: KI strukturiert, Nutzer verwaltet nicht die Feinstruktur).
|
||||
- Handoffs referenzieren Kanshō-Quellen; sie sind nicht der Dialogspeicher.
|
||||
- Message-IDs idempotent (späteres Offline, Sync-Hypothese).
|
||||
|
||||
### Schichtenzuordnung
|
||||
|
||||
| Layer | Hier |
|
||||
|---|---|
|
||||
| 0 | Conversation/Messages, Session, Thread-Identität und Anker (Wiedervorlage), Space-Identität, Mapping |
|
||||
| 1 | Working-Context-Snapshot, aktuelle Thread-Memory-Version, Space-„aktueller Stand“, später Relevanz/Saturation als registrierte Leser |
|
||||
| 2a | Context Builder wählt Layer-1- und Quell-Ausschnitte; Gateway minimiert erneut |
|
||||
| 2b | Fortsetzungsvorschlag, Space-Ansicht, Aufklappen zur Quelle – keine zweite Verdichtungsformel |
|
||||
|
||||
Kontinuitätsarbeit ist ein **laufender Schreibpfad** auf Layer 0/1, auslösbar mitten im Dialog und am Session-Checkpoint. Sie ist unabhängig vom sichtbaren Abschluss und unabhängig davon, ob ein Handoff entsteht.
|
||||
|
||||
### Bewusst nicht schließen
|
||||
|
||||
- Thread-Zustandsliste (`Open` / `Anchored` / `Dormant` / `Resolved` sind Hinweise, kein Enum-Vertrag).
|
||||
- Drift-Formel, Saturation-Score, Entry-IA (Contextual Continuation).
|
||||
- Self-Model-Felder, Episodic-Schema in Kanshō (Handoff-Ziel mindnet/Obsidian).
|
||||
- SQL, Sync-Engine, Offline-Store.
|
||||
|
||||
### Erweiterbarkeit
|
||||
|
||||
Neue fachliche Arten (z. B. weiteres Derived-`kind`, weiterer Handoff-Typ, feinere Space-Sicht) kommen als **registrierter Typ** plus Provenance, nicht als Sonderpfad in der Conversation-Tabelle und nicht als Prompt-Text im Code. Retrieval in den Langzeitgraphen bleibt Adapter + External ref, kein zweites mindnet in Kanshō.
|
||||
|
||||
Session-Ende ist ein Checkpoint, kein Zwang zu Journal/Memory/Delta/Action. Technisch heißt das: Persistenzpfade für Original und interne Kontinuität existieren unabhängig von Handoff-Tabellen oder sichtbaren Abschluss-Screens.
|
||||
|
||||
## 4. Offline
|
||||
|
||||
**Anforderung: entschieden. Ausprägung: offen.**
|
||||
|
||||
Leitplanken, die jede spätere Lösung erfüllen muss:
|
||||
|
||||
- Dialoge müssen lokal zwischenspeicherbar sein (fachliche Anforderung).
|
||||
- Konfliktbehandlung und Sync sind zu definieren, bevor Multi-Gerät produktiv personenbezogene Dialoge führt.
|
||||
- KI-Funktionen dürfen online bleiben; Fail Closed gilt für unsichere Provider, nicht als Ausrede, lokale Eingaben zu verwerfen.
|
||||
- App-Shell-Cache (PWA) ist nicht dasselbe wie Dialog-Offline.
|
||||
- Verschlüsselung at rest auf dem Gerät: offen, siehe `security.md`.
|
||||
|
||||
Lokale kleine Modelle: fachlich offen, nicht als Voraussetzung des Rahmens.
|
||||
|
||||
## 5. Sync-Hypothese
|
||||
|
||||
**Status: Hypothese**
|
||||
|
||||
Ein Gerät schreibt in eine lokale Queue, das Backend ist Source of Truth nach erfolgreichem Sync. Idempotente Message-IDs verhindern Duplikate. Konflikte an Originalnachrichten sind selten (ein Nutzer, ein aktiver Dialog); Konflikte an Summaries werden durch Neuberechnung aus der Quelle gelöst, nicht durch Merge von Verdichtungen.
|
||||
|
||||
Diese Hypothese ist zu verwerfen oder zu bestätigen, sobald Geräte- und Offline-Szenarien in Phase G4 entschieden sind.
|
||||
|
||||
## 6. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Mehrere Memory-Schichten | heutiger Fachstand | nicht als Schema einfrieren |
|
||||
| Original vor Summary / Re-Grounding | fachliche Invariante | bindend, sobald Memory gebaut wird |
|
||||
| Objektarten und Lebenszyklus-Trennung | Verträge in §3a | entschieden als Vorsorge, kein SQL |
|
||||
| mindnet nicht Working Memory | wahrscheinlich | bevorzugte Richtung |
|
||||
| Offline-Fähigkeit | erforderlich | entschieden (fachlich), Ausprägung offen |
|
||||
| Sync/Konflikte/lokale DB | – | offen |
|
||||
| Drift-Berechnung | fachlich nötig | bevorzugte Richtung, Technik offen |
|
||||
|
||||
## 6.1 Implementierungsstand (Rahmen-Schnitt)
|
||||
|
||||
**Status: Code vorhanden, Heuristiken nicht.**
|
||||
|
||||
Layer-0-Tabellen `usage_sessions` (nicht Auth-`sessions`), `conversations`, `messages`, Thread-/Space-Identität, `derived_records` (append-only, Kind-Registry), Handoff-/Ref-/Re-Grounding-/Mapping-Hüllen. Continuity-Checkpoint ohne LLM. Admin trennt Original und Derived. Die Dialogseite speichert nur Originaltext.
|
||||
|
||||
Nicht enthalten: Entry-IA, Fadenerkennung, Thread-Enum, Summaries über das Gateway.
|
||||
|
||||
## 7. Offene Fragen
|
||||
|
||||
1. IndexedDB vs. SQLite-WASM vs. nur Service-Worker-Queue?
|
||||
2. Wird Audio nach Transkription gelöscht oder als Medium behalten? → `voice_and_media.md`
|
||||
3. Wie greift Re-Grounding bei teilweise gesyncten Sessions?
|
||||
|
||||
## 8. Querverweise
|
||||
|
||||
- `data_architecture.md`, `frontend_pwa_shell.md`, `privacy_gateway.md`
|
||||
- Fachlich: `memory_and_context.md`, `resurfacing_and_saturation.md`
|
||||
@@ -0,0 +1,234 @@
|
||||
---
|
||||
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 darf vorerst Env-Default sein; 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)
|
||||
- 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
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: "Kanshō – Privacy Gateway und AI-Egress"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Privacy Gateway / Egress"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Privacy Gateway und AI-Egress
|
||||
|
||||
Technische Abbildung der fachlichen Guardrails. Kanonisches Fachhome: `../functional/guardrails.md` (inkl. Root Cause §2, Datenklassen §5, Gateway §6, Entscheidungsstand §22). Dieses Kapitel dupliziert die Herleitung nicht.
|
||||
|
||||
**Rang:** Datenschutz und Guardrails sind im Fachkonzept **grundlegend und entschieden**. Sie stehen nicht auf derselben Ebene wie unfertige Dialog- oder MVP-Schnitte. Offene Punkte betreffen Verfahren und rechtliche Ausprägung (Entity Detection, Encryption at rest, DSFA), nicht die Invariante selbst.
|
||||
|
||||
## 1. Invariante
|
||||
|
||||
> Identität bleibt lokal. Externe Intelligenz erhält nur den für die Aufgabe notwendigen, minimierten und soweit sinnvoll pseudonymisierten Kontext.
|
||||
|
||||
Herkunft: `guardrails.md` §2.4; querschnittlich in der fachlichen Zielarchitektur. Providerunabhängig: OpenRouter ist Kandidat, kein Ersatz für das lokale Gateway. OpenRouter-eigene Guardrail-Features ergänzen höchstens, sie ersetzen die Kanshō-Schicht nicht.
|
||||
|
||||
Pseudonymisierung ist keine Anonymisierung. Kanshō behauptet keine vollständige Anonymität nach außen.
|
||||
|
||||
Persönlicher Kontext wird **nie** direkt aus UI, Dialog-Router, Prompt-Engine oder Admin-Preview an OpenRouter, Provider oder Tools gesendet. Die Engine darf den Provider nur über den Gateway-Callback erreichen (`platform_extensibility.md`).
|
||||
|
||||
### 1.1 Guardrail-Vorrang
|
||||
|
||||
Fachlich §19: Guardrails haben Vorrang vor Modellqualität, Kosten, Latenz, Komfort und automatischem Provider-Fallback. Eine Anfrage wird abgelehnt oder degradiert, wenn die Policy nicht erfüllbar ist. Administrierbare Prompts, Workflows oder Feature-Flags dürfen das Gateway nicht abschalten.
|
||||
|
||||
## 2. Trust Zones
|
||||
|
||||
| Zone | Inhalt | Egress |
|
||||
|---|---|---|
|
||||
| Local Trusted Zone | Identity Mapping, Klarnamen, Secrets, volle Primärquellen, Obsidian-Pfade | kein Roh-Egress |
|
||||
| External AI Zone | External Model Context (Klasse B) | nur nach Policy-Check, ZDR |
|
||||
| Tool-/Plugin-Zone | Suche, Plugins, Speech | eigene Policy, nicht implizit mit LLM-Freigabe |
|
||||
|
||||
## 3. Datenklassen
|
||||
|
||||
- **A Local Only:** Mapping, Secrets, vollständige Identität, interne IDs soweit identifizierend. Verlassen die Trusted Zone nicht.
|
||||
- **B Pseudonymized AI Context:** Normalfall persönlicher Dialoge. Stabile, nicht sprechende Platzhalter (`[[SELF]]`, `[[PERSON:PARTNER]]`). Minimierung zusätzlich zur Maskierung.
|
||||
- **C Low-Identity:** generische, nicht-personalisierte Inhalte; schwächere Transformation zulässig, eigene Policy bleibt nötig.
|
||||
|
||||
Quasi-Identifikatoren (Beruf+Ort+Familie) sind fachlich erkannt; die Bewertungsmethode ist offen, der Gateway-Auftrag „nicht nur Klarnamen“ gilt trotzdem.
|
||||
|
||||
## 4. Pflichtpipeline
|
||||
|
||||
Jeder persönliche Modellaufruf durchläuft lokal:
|
||||
|
||||
1. Context Minimization
|
||||
2. Entity Detection
|
||||
3. Pseudonymization
|
||||
4. Policy Check
|
||||
5. Provider/Endpoint Eligibility (ZDR, kein Training, kein Prompt-Logging)
|
||||
6. Egress Validation
|
||||
7. Response Validation
|
||||
8. Local Rehydration / Demasking
|
||||
9. Audit Metadata (ohne volle Prompts)
|
||||
10. Fail Closed
|
||||
|
||||
Fail Closed: kein stillschweigender Fallback auf einen weniger geschützten Provider.
|
||||
|
||||
LLM-Egress und Tool-/Web-/Transkriptions-Egress sind getrennte Policies. Ein für ZDR-LLM freigegebener Kontext darf nicht automatisch an Web Search oder Speech-Cloud.
|
||||
|
||||
## 5. Internal vs. External Context
|
||||
|
||||
Der Context Builder darf intern mit Klaridentität arbeiten. Vor dem Socket nach außen existiert eine zweite Repräsentation ohne Mapping-Tabelle.
|
||||
|
||||
Demasking ausschließlich in der Trusted Zone, nach Validierung (Platzhalter erhalten, keine erratenen Klarnamen, keine Policy-Verstöße).
|
||||
|
||||
## 6. Audit
|
||||
|
||||
Speichern: Request-ID, Zeit, Policy, Provider-/Modellkennung, ZDR-/Region-Status, Typ maskierter Entitäten, Prüf- und Fallback-Status.
|
||||
|
||||
Nicht speichern: volle Prompts, volle Antworten, echte Namen, Mapping.
|
||||
|
||||
Admin-Sichtbarkeit der Mapping-Tabelle nur für besonders berechtigte Rollen (`admin_diagnostics.md`).
|
||||
|
||||
## 7. Beziehung zu anderen Kapiteln
|
||||
|
||||
- Resurfacing darf keinen breiteren Egress rechtfertigen als der aktuelle Task braucht.
|
||||
- Re-Grounding läuft lokal und erzeugt danach erneut einen minimierten External Context.
|
||||
- Voice/Transkription: eigener Egress-Typ (`voice_and_media.md`).
|
||||
- Lived Experience / Re-Grounding: volle Primärquellen bleiben lokal; externes Modell bekommt erneut nur Klasse B.
|
||||
- Prompt-Engine: Preview ohne LLM ist erlaubt; Debug-Ausgaben an den Admin ohne Klasse-A-Klartext und ohne Mapping.
|
||||
|
||||
## 8. Was Phase H noch offen lässt
|
||||
|
||||
Interview H1 (Encryption at rest, vollständiges Löschen, Portabilität, DSFA bei späterem Mehrbenutzerbetrieb) ergänzt diese Invariante, ersetzt sie nicht. Privacy Profiles (Strict / Balanced / Low-Identity) sind fachlich perspektivisch; Default muss die Invariante erfüllen.
|
||||
|
||||
## 9. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Privacy Gateway vor persönlichem Egress | zwingend, nicht abschaltbar | entschieden |
|
||||
| Guardrails vor Qualität/Kosten/Latenz | ja | entschieden (fachlich) |
|
||||
| Providerunabhängige Guardrails | ja | entschieden (fachlich) |
|
||||
| ZDR / kein Training / kein Prompt-Log | persönliche Kontexte | entschieden bzw. bevorzugte verbindliche Policy |
|
||||
| Fail Closed | ja | bevorzugte Richtung |
|
||||
| Keine Anonymitätsbehauptung | Pseudonymisierung | entschieden (fachlich) |
|
||||
| OpenRouter | Kandidat, nicht Gateway-Ersatz | entschieden |
|
||||
| EU-Routing | bevorzugt | offen in Ausprägung |
|
||||
| Encryption at rest, Delete, DSFA | Phase H | offen |
|
||||
| Implementierung Entity Detection | deterministisch vs. KI-gestützt | offen |
|
||||
|
||||
## 10. Offene Fragen
|
||||
|
||||
Übernommen aus `guardrails.md` §21, hier nicht vorentschieden: Entitätstypen, Quasi-Identifikatoren, Pseudonym-Stabilität, Mehrnutzer-Trennung der Mappings, Verschlüsselung der Mapping-Tabelle, rechtliche DSFA bei Mehrbenutzer-Produktbetrieb.
|
||||
|
||||
## 11. Querverweise
|
||||
|
||||
- Fachlich: `../functional/guardrails.md`
|
||||
- Technisch: `ai_architecture.md`, `security.md`, `voice_and_media.md`, `platform_extensibility.md`
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: "Kanshō – Produktrahmen und Stack"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Product Frame / Stack"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Produktrahmen und Stack
|
||||
|
||||
Kanonisches Home für die übertragbare Laufzeit- und UI-Hülle. Fachliche Identität bleibt in `../functional/produktvision_und_produktidentitaet.md`.
|
||||
|
||||
## 1. Herkunft
|
||||
|
||||
Explizite Nutzeranforderung: Der **Produktrahmen** (PWA, Responsive, Desktop/Mobile-Shell, Authentifizierung, Userrollen, Multiuser auf Instanz-Ebene, API- und Deploy-Muster) soll **weitgehend** von Mitai übernommen werden, nicht neu entwickelt werden.
|
||||
|
||||
Der aktuelle fachliche Konzeptionsstand zu Dialog, Memory und MVP ist **nicht final**. **Datenschutz und Guardrails sind bindend.** Mitai enthält kein Kanshō-Privacy-Gateway; dieser Pfad wird ergänzt, nicht von Mitai übernommen.
|
||||
|
||||
Referenz: Mitai Jinkendo, nicht Kairo und nicht Shinkan.
|
||||
|
||||
Mitai-Foundation beschreibt übertragbare Muster unabhängig von Körper-Tracking: `C:\dev\mitai\.claude\docs\jinkendo-foundation/`.
|
||||
|
||||
## 2. Systemüberblick
|
||||
|
||||
Kanshō folgt dem Mitai-3-Tier-Modell.
|
||||
|
||||
```text
|
||||
Nutzergerät (PWA)
|
||||
↓ HTTPS
|
||||
Frontend (React + Vite, Nginx in Prod)
|
||||
↓ /api
|
||||
Backend (FastAPI)
|
||||
↓
|
||||
PostgreSQL
|
||||
↓ nur über Privacy Gateway
|
||||
Externe KI / Tools
|
||||
```
|
||||
|
||||
Alle persönlichen Daten und das Identity Mapping liegen in der Local Trusted Zone. Siehe `privacy_gateway.md`.
|
||||
|
||||
## 3. Stack
|
||||
|
||||
| Schicht | Technologie | Status |
|
||||
|---|---|---|
|
||||
| UI | React 18 ohne TypeScript-Pflicht | entschieden |
|
||||
| Build | Vite, `vite-plugin-pwa` | entschieden |
|
||||
| Routing | React Router 6 | entschieden |
|
||||
| Icons | Lucide React | entschieden |
|
||||
| API | FastAPI, Python 3.12 | entschieden |
|
||||
| DB | PostgreSQL 16 | entschieden |
|
||||
| Auth-Hash | bcrypt | entschieden |
|
||||
| Container | Docker Compose | entschieden |
|
||||
| Reverse Proxy | Nginx vor dem Frontend-Bundle (Prod-Muster Mitai) | bevorzugte Richtung |
|
||||
| Hosting | selbst gehostet, Gitea-CI wie die Familie | entschieden |
|
||||
|
||||
State Management: Context (Auth, Profil), kein Redux. Herkunft: Mitai-Frontend-Muster.
|
||||
|
||||
## 4. Was als Rahmen übernommen wird
|
||||
|
||||
Weitgehend das Mitai-Muster, inklusive konkreter Datei- und UX-Mechanik:
|
||||
|
||||
- PWA-Installierbarkeit, Vite PWA-Plugin, Manifest.
|
||||
- Breakpoint 1024px, Bottom-Nav, Desktop-Sidebar, Safe Area.
|
||||
- Nav-SSoT, Bereichs-Shells, `RequireAdmin`, Admin-Realm.
|
||||
- AuthContext, Login/Register/Verify/Setup analog Mitai.
|
||||
- Server-Sessions, Rollen `user` / `admin`, Rate Limits, bcrypt.
|
||||
- Ein Modul = ein Backend-Router, API-First, Fehlerformat `{detail}`.
|
||||
- Nummerierte SQL-Migrationen, Compose Dev/Prod, Gitea-Branches.
|
||||
- Multiuser auf Instanz-Ebene, Isolation über Session-`profile_id`.
|
||||
- Registry-Muster, Prompt-/Workflow-Engine, Data Layer, Feature-Check an der API: `platform_extensibility.md`.
|
||||
|
||||
Platzhalter-Seiten der Mitai-Nav dürfen als **leere Shell-Routen** mitwandern, bis der Fachstand Kanshō-Inhalte vorgibt. Sie werden nicht mit Tracking-Fachlogik gefüllt.
|
||||
|
||||
## 5. Was nicht übernommen wird
|
||||
|
||||
Nur Domäne, Mandantenmodell und bekannte Sicherheitslücken – nicht der Rahmen.
|
||||
|
||||
| Nicht übernehmen | Begründung |
|
||||
|---|---|
|
||||
| Körper-Tracking, Messwerte, Capture-Fachlogik, CSV-Import, Membership als Kern | Mitai-Domäne |
|
||||
| Shinkan: Verein → viele Nutzer | anderes Produktmodell |
|
||||
| `X-Profile-Id` ohne Session-Bindung | IDOR; siehe `auth_identity_and_roles.md` |
|
||||
| TypeScript-Pflicht, JWT/SSO als Ist | nicht Mitai-Rahmen |
|
||||
| Direkter LLM-Provider-Call aus der Engine | Kanshō ergänzt Privacy Gateway (`privacy_gateway.md`) |
|
||||
|
||||
Kanshō-spezifische Startlogik, Dialog-IA und Memory-Modelle kommen aus der **späteren** Fachkonzeption. Sie sind kein Grund, Login, Shell, Deploy oder Router anders zu bauen.
|
||||
|
||||
## 6. Multiuser ohne Mandanten
|
||||
|
||||
**Status: entschieden**
|
||||
|
||||
Kanshō ist nutzerbezogen. Ein Account entspricht einem Profil. Es gibt keine Vereine, Clubs oder Organisations-Workspaces.
|
||||
|
||||
Mehrere Nutzer auf einer Instanz sind zulässig (wie Mitai). Isolation erfolgt über `profile_id` der Session, nicht über eine Tenant-Tabelle.
|
||||
|
||||
Admin sieht Diagnose- und Verwaltungsfunktionen, nicht die private Reflexion anderer Nutzer als Alltagspfad. Details: `admin_diagnostics.md`.
|
||||
|
||||
## 7. KI im Rahmen
|
||||
|
||||
Externe Modelle sind für leistungsfähige Dialoge vorgesehen. Sie sind **kein** Teil des UI-Frameworks. Jeder persönliche Aufruf läuft über das Privacy Gateway. OpenRouter ist Kandidat, kein Zwang.
|
||||
|
||||
Mitai-Prompt-Engine-Muster (ein Executor, Registry, Admin-Konfiguration) wird übernommen; der LLM-Callback ist in Kanshō das Privacy Gateway, nicht Roh-OpenRouter. Siehe `platform_extensibility.md`.
|
||||
|
||||
## 8. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| 3-Tier PWA | React + FastAPI + PostgreSQL | entschieden |
|
||||
| Referenz | Mitai-Rahmen weitgehend | entschieden |
|
||||
| Fachliche IA / Startroute | nicht durch den Rahmen vorwegnehmen | offen (Fach-Arbeitsstand) |
|
||||
| Mandantenmodell | keines | entschieden |
|
||||
| Konkrete Ports/Domains | nicht aus Mitai kopieren | offen |
|
||||
| Gemeinsame UI-Bibliothek der Familie | eigene Kopie des Musters, kein Shared-Package vorausgesetzt | bevorzugte Richtung |
|
||||
|
||||
## 9. Offene Fragen
|
||||
|
||||
1. Soll der Rahmen später in ein gemeinsames Jinkendo-Paket extrahiert werden oder als kopiertes Muster in Kanshō leben?
|
||||
2. Welche Domain und welche Host-Ports gelten für Dev/Prod?
|
||||
3. Wird Nginx als eigener Container beibehalten oder das Vite-Preview nur für lokale Entwicklung genutzt?
|
||||
|
||||
## 10. Querverweise
|
||||
|
||||
- Fachlich: `../functional/produktvision_und_produktidentitaet.md` §19, §21.11
|
||||
- Technisch: alle übrigen Kapitel dieses Ordners
|
||||
- Mitai: `.claude/docs/technical/ARCHITECTURE.md`, `FRONTEND.md`, Foundation-Index
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
title: "Kanshō – Runtime, Migrationen und Deploy"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Runtime / Deploy / Migrations"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Runtime, Migrationen und Deploy
|
||||
|
||||
Kanonisches Home für Container-Start, Schema-Evolution und Gitea-Pipelines. Mitai-Referenz: `MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md`, `docker-compose.yml`, `docker-compose.dev-env.yml`, `.gitea/workflows/`.
|
||||
|
||||
## 1. Umgebungen
|
||||
|
||||
Muster der Familie: zwei Umgebungen, zwei Branches.
|
||||
|
||||
| Umgebung | Git-Branch | Rolle |
|
||||
|---|---|---|
|
||||
| Development | `develop` | Auto-Deploy nach Push |
|
||||
| Production | `main` | Auto-Deploy nach Merge |
|
||||
|
||||
**Status: entschieden** als Betriebsmuster. Konkrete Domains, Host-Pfade und **Produktions-Ports** sind **offen** und werden nicht aus Mitai (`3002`/`8002`, `3099`/`8099`, `bodytrack/`) kopiert.
|
||||
|
||||
Lokale Entwicklung (ohne Docker) verwendet eigene Ports, nicht die Vite-/FastAPI-Defaults und nicht die Ports anderer lokaler Repos:
|
||||
|
||||
| Dienst | Port | Bindung |
|
||||
|---|---|---|
|
||||
| Frontend (Vite) | 5188 | `strictPort`, kein Ausweichen |
|
||||
| Backend (Uvicorn) | 8018 | explizit |
|
||||
|
||||
Nicht verwenden: 5173, 5174, 4000, 4001, 8000.
|
||||
|
||||
Hypothese für spätere Benennung: `kansho.jinkendo.de` / `dev.kansho.jinkendo.de`, analog zur Foundation-Tabelle. Nicht festgelegt.
|
||||
|
||||
## 2. Container
|
||||
|
||||
Docker Compose mit mindestens:
|
||||
|
||||
- Frontend (Nginx + gebündelte PWA in Prod; Vite-Dev optional lokal)
|
||||
- Backend (FastAPI)
|
||||
- PostgreSQL 16
|
||||
|
||||
Secrets und SMTP nur in Server-`.env`, nicht im Repository. Vorlage: `.env.example`.
|
||||
|
||||
Watchtower oder gleichwertiges Image-Update: Mitai-Betrieb, für Kanshō **später prüfen**.
|
||||
|
||||
## 3. Schema-Migrationen
|
||||
|
||||
**Status: entschieden** (Muster)
|
||||
|
||||
1. Nummerierte SQL-Dateien `backend/migrations/XXX_*.sql`.
|
||||
2. Tracking-Tabelle `schema_migrations`.
|
||||
3. Startup: Postgres ready → Migrationen → App-Prozess.
|
||||
4. Idempotenz wo möglich (`IF NOT EXISTS`).
|
||||
5. Kein automatisches Schema-Downgrade.
|
||||
|
||||
Greenfield-Basis analog Mitai `schema.sql` ist zulässig. Änderungen danach nur über nummerierte Migrationen.
|
||||
|
||||
Fail-fast beim Start, wenn Migrationen scheitern. Kein stilles Weiterlaufen mit Drift.
|
||||
|
||||
## 4. Gitea CI/CD
|
||||
|
||||
Mitai-Pipeline als Vorlage:
|
||||
|
||||
```text
|
||||
push develop → deploy-dev.yml → compose build/up → Healthcheck
|
||||
push/PR nach Tests → test.yml (pytest, Frontend-Build)
|
||||
merge in main → deploy-prod.yml
|
||||
```
|
||||
|
||||
**Status: bevorzugte Richtung.** Workflow-Dateien erst anlegen, wenn Code und Runner-Pfade existieren.
|
||||
|
||||
Kanshō-Repo liegt bereits auf Gitea (`Lars/Kansho`). HTTPS-Push ist eingerichtet.
|
||||
|
||||
## 5. Was Deploy nicht übernimmt
|
||||
|
||||
- Blue-Green oder Multi-Region
|
||||
- Automatisches Rollback der Datenbank
|
||||
- Mitai-Verzeichnisnamen auf dem Pi
|
||||
- Fachliche Datenberechnungen
|
||||
|
||||
## 6. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Compose + Postgres + nummerierte SQL-Migrationen | ja | entschieden |
|
||||
| develop → Dev, main → Prod | ja | entschieden |
|
||||
| Ports/Domains/Hostpfade | Prod offen; lokal Frontend 5188 / Backend 8018 | lokal festgelegt, Prod offen |
|
||||
| Gitea Workflows | Mitai-Muster | bevorzugte Richtung |
|
||||
| Auto-Rollback | nein | verworfen |
|
||||
|
||||
## 7. Offene Fragen
|
||||
|
||||
1. Läuft Kanshō auf demselben Raspberry-Pi-Host wie Mitai, mit eigenen Compose-Projekten?
|
||||
2. Gemeinsames oder separates Postgres?
|
||||
3. Backup-Rhythmus und Restore-Übung vor erstem persönlichen Dialogdatenbestand.
|
||||
|
||||
## 8. Querverweise
|
||||
|
||||
- Technisch: `product_frame_and_stack.md`, `security.md`
|
||||
- Fachlich: Offline und Sync bleiben `memory_storage_and_offline.md`; Deploy löst Offline nicht.
|
||||
- Mitai: `MIGRATIONS.md`, `.gitea/workflows/`
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Kanshō – Security"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Security"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Security
|
||||
|
||||
Kanonisches Home für Zugriffssicherheit des Mitai-Rahmens (Auth, TLS, Secrets, IDOR). Der Schutz personenbezogener Daten beim AI-Egress liegt in `privacy_gateway.md`. Encryption at rest, selektives Vergessen und DSFA: Interview H1, Ausprägung **offen**.
|
||||
|
||||
## 1. Rahmen, übernommen aus Mitai
|
||||
|
||||
- bcrypt für Passwort-Hashes, keine Klartext-PINs.
|
||||
- Rate Limiting an Login/Register (Mitai: Login 5/min, Register restriktiver) – konkrete Zahlen für Kanshō **bevorzugte Richtung**, bei Bedarf anpassen.
|
||||
- CORS explizit, nicht `*` in Prod.
|
||||
- HTTPS vor der App (Synology/Reverse Proxy der Familie).
|
||||
- Secrets nur Server-`.env` (SMTP, Provider-Keys, DB). Nie im Frontend, nie ins Git.
|
||||
- Session-Invalidierung beim Logout.
|
||||
- Kein IDOR über Client-gewähltes Profil (`auth_identity_and_roles.md`).
|
||||
|
||||
## 2. Kanshō-spezifisch
|
||||
|
||||
- Provider-Keys für LLM nur hinter dem Gateway, mit Policy-Check vor Verwendung.
|
||||
- Audit-Logs ohne Prompt-Volltext.
|
||||
- Admin-API nicht über Security-by-Obscurity; immer `require_admin`.
|
||||
- Fremde `profile_id` in Pfaden/Bodies ignorieren oder 403.
|
||||
|
||||
## 3. Transport und Ruhe
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| TLS nach außen | ja, Betriebsstandard der Familie | entschieden als Anforderung |
|
||||
| Verschlüsselung at rest (DB, Backups, Gerät) | – | offen |
|
||||
| Client-Token in localStorage | XSS-Risiko bekannt | bevorzugte Richtung, später bewerten |
|
||||
| Vollständiges Löschen / selektives Vergessen | fachlich offen | offen |
|
||||
| Export/Portabilität | fachlich gewünscht (menschenlesbar) | offen in Technik |
|
||||
|
||||
## 4. Dependency- und Deploy-Hygiene
|
||||
|
||||
- Keine Provider-Keys in Compose-Dateien im Repo.
|
||||
- Fail Closed bei fehlender Privacy-Policy des Endpoints, nicht Fail Open wegen Verfügbarkeit.
|
||||
- Healthchecks ohne Leak von Nutzerdaten.
|
||||
|
||||
## 5. Safety vs. Security
|
||||
|
||||
Krisengrenzen und medizinische Hochrisikothemen sind **nicht** dieses Kapitel (`ai_architecture.md`, fachlich H3). Hier: Zugriff, Secrets, Isolation, Logging.
|
||||
|
||||
## 6. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Guardrails / Privacy-Invariante | bindend, unabhängig von H1-Ausprägung | entschieden |
|
||||
| IDOR-Profilheader | verworfen | entschieden |
|
||||
| Encryption at rest, Delete, Cookie-Sessions | – | offen |
|
||||
| Shared-Postgres mit anderen Apps | Default nein | bevorzugte Richtung |
|
||||
|
||||
## 7. Offene Fragen
|
||||
|
||||
1. Getrennte Datenbank pro App vs. gemeinsamer Server mit getrennten Schemas?
|
||||
2. Backup-Verschlüsselung und Schlüsselhaltung.
|
||||
3. DSFA und Retention, sobald Mehrbenutzer über den privaten Betrieb hinausgeht.
|
||||
|
||||
## 8. Querverweise
|
||||
|
||||
- `auth_identity_and_roles.md`, `privacy_gateway.md`, `runtime_and_deploy.md`
|
||||
- Fachlich: `../functional/guardrails.md` §18–19
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
title: "Kanshō – Technische Zielarchitektur"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technische Zielarchitektur / Master Structure"
|
||||
parent_document: "../functional/fachliche_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Technische Zielarchitektur
|
||||
|
||||
## 1. Zweck dieses Dokuments
|
||||
|
||||
Dieses Dokument definiert die **technische Zielarchitektur** von Kanshō: Umsetzung, Speicher, Schnittstellen und Betriebsform.
|
||||
|
||||
Es ist das führende Referenzdokument des Ordners `docs/architecture/technical/`. Die übrigen technischen Kapitel werden hier eingeordnet.
|
||||
|
||||
Die **fachliche Zielarchitektur bleibt führend**. Dialog-, Memory-, Space-, Output- und MVP-Schnitte sind **Arbeitsstand** und nicht final. **Datenschutz, Privacy Gateway und Guardrails** sind davon ausgenommen: Sie sind bereits eine verbindliche Architektur-Invariante (`../functional/guardrails.md`) und dürfen technisch nicht relativiert werden.
|
||||
|
||||
Technische Kapitel beschreiben, *wie* umgesetzt wird. Sie ersetzen, kürzen oder überschreiben keine Fachtexte.
|
||||
|
||||
Dieses Dokument ist bewusst **keine Implementierungsanleitung** und enthält keine SQL-Schemas, OpenAPI-Verträge oder Prompt-Texte.
|
||||
|
||||
---
|
||||
|
||||
## 2. Verhältnis zur fachlichen Konzeption
|
||||
|
||||
Herkunft: gemeinsam getroffene Entscheidung in der Fachdoku (`fachliche_zielarchitektur.md` §2.6, `dialogue_model.md` §8.5).
|
||||
|
||||
| Ebene | Zuständig für | Nicht zuständig für |
|
||||
|---|---|---|
|
||||
| Fachliche Architektur | Nutzererlebnis, Verantwortlichkeiten, fachliche Objekte, Nutzerkontrollen | Speicherform, Algorithmen, Deploy |
|
||||
| Technische Architektur | Stack, Runtime, API, Persistenzgrenzen, Egress, Betrieb | Produktidentität, neue Fachobjekte |
|
||||
|
||||
Technische Vorentscheidungen sind nur dann zulässig, wenn sie:
|
||||
|
||||
- eine fachliche Produktgrenze unmittelbar beeinflussen,
|
||||
- später nur mit sehr hohem Aufwand revidierbar wären,
|
||||
- oder zwingende Auswirkungen auf Datenschutz, Offline-Fähigkeit, Sicherheit oder Integrationen haben.
|
||||
|
||||
Der Interviewplan (`interview_plan.md`) vertieft weiter Dialog, Datenverträge, Voice, Offline-Ausprägung, Encryption/Löschen (Phase H1) und MVP. Die **Guardrail-Invariante** (Identität lokal, Privacy Gateway, getrennte Egress-Policies) ist fachlich bereits entschieden und hier technisch bindend. Unfertige Fachobjekte (Threads, Spaces, Prompts) bleiben Arbeitsstand.
|
||||
|
||||
### 2.1 Fachstand: was Arbeitsstand ist, was bindet
|
||||
|
||||
**Status: entschieden** (Herkunft: Nutzeranforderung 2026-08-19 plus `guardrails.md`)
|
||||
|
||||
Nicht als finales Produktschema behandeln:
|
||||
|
||||
- Dialog-IA, Startroute, Memory-/Thread-Modelle, Reflection Outputs, MVP-Schnitt.
|
||||
|
||||
Verbindlich für jede technische Umsetzung, auch für den Mitai-Rahmen:
|
||||
|
||||
- Identität bleibt lokal.
|
||||
- Persönlicher Kontext geht nie direkt an externe Modelle oder Tools.
|
||||
- Lokales Privacy Gateway vor jedem persönlichen AI-Egress.
|
||||
- Datenklassen A/B/C, Minimierung und Pseudonymisierung, lokales Mapping.
|
||||
- Guardrails haben Vorrang vor Modellqualität, Kosten, Latenz und Komfort (`guardrails.md` §19).
|
||||
- Ausprägungen wie Entity-Detection-Verfahren, Encryption at rest, DSFA bleiben offen – sie schwächen die Invariante nicht.
|
||||
|
||||
### 2.2 Produktrahmen versus MVP
|
||||
|
||||
Der aus Mitai übernommene Produktrahmen (PWA, Auth, Rollen, Layout-Shell, Deploy) ist ein **Umsetzungs-Slice „Produktrahmen“**. Er darf **weitgehend** der Mitai-Implementierung folgen.
|
||||
|
||||
Ein späterer MVP bleibt eine fachliche Entscheidung (Interview Phase I). Die dort genannte kleine Reflexionsschleife ist **aktueller Arbeitsstand**, kein technisch eingefrorener Lieferumfang. Die leere oder fast leere Mitai-Shell ist Infrastruktur, nicht der MVP.
|
||||
|
||||
---
|
||||
|
||||
## 3. Dokumentationsprinzipien
|
||||
|
||||
Die technischen Kapitel folgen denselben Regeln wie die Fachdoku.
|
||||
|
||||
### 3.1 Keine stillschweigende Verdichtung
|
||||
|
||||
Änderungen erfolgen durch Ergänzung, explizite Ersetzung, Kennzeichnung als überholt, Decision Record oder Gitea-Versionierung.
|
||||
|
||||
### 3.2 Entscheidungen und Ideen trennen
|
||||
|
||||
Jedes Kapitel unterscheidet:
|
||||
|
||||
- **Entschieden**
|
||||
- **Bevorzugte Richtung**
|
||||
- **Hypothese**
|
||||
- **Offen**
|
||||
- **Verworfen**
|
||||
- **Später prüfen**
|
||||
|
||||
### 3.3 Herkunft von Aussagen erhalten
|
||||
|
||||
Wo sinnvoll kenntlich machen, ob ein Punkt stammt aus:
|
||||
|
||||
- expliziter Nutzeranforderung,
|
||||
- gemeinsam getroffener Entscheidung,
|
||||
- Mitai-Referenzimplementierung,
|
||||
- technischem Zwang,
|
||||
- späterer Validierung.
|
||||
|
||||
### 3.4 Keine unnötige Duplizierung
|
||||
|
||||
Ein Thema hat ein kanonisches Home. Fachliches bleibt in `docs/architecture/functional/`. Technisches verlinkt dorthin.
|
||||
|
||||
### 3.5 Stabile Dateinamen
|
||||
|
||||
Dateinamen enthalten keine Versionsnummern. Frontmatter mindestens: Titel, Version, Status, Datum, `document_role`.
|
||||
|
||||
### 3.6 Schutz vor Übervereinfachung
|
||||
|
||||
Interne technische Modelle dürfen differenziert sein, wenn der **jeweils aktuelle** Fachstand es erfordert. Vereinfachung nur nach Capability-Check (`fachliche_zielarchitektur.md` §2.8).
|
||||
|
||||
Die folgenden Punkte sind fachliche **Querschnittsinvarianten** (`fachliche_zielarchitektur.md` §2.9). Privacy/Guardrails gelten für den Produktrahmen **sofort**. Die übrigen vier begrenzen spätere Domänen-Persistenz und KI-Nutzung; sie werden nicht als SQL-Schema vorgezogen und nicht abgeschwächt, sobald die jeweilige Fähigkeit gebaut wird.
|
||||
|
||||
| Invariante | Fachliches Home | Technisches Home |
|
||||
|---|---|---|
|
||||
| Context Fidelity / Re-Grounding | `../functional/context_fidelity_and_regrounding.md` | `memory_storage_and_offline.md`, `data_architecture.md`, `privacy_gateway.md` |
|
||||
| Thread Resurfacing / Reflection Saturation | `../functional/resurfacing_and_saturation.md` | `data_architecture.md`, `ai_architecture.md` |
|
||||
| Session Lifecycle ≠ Thread Lifecycle | `../functional/reflection_outputs.md` | `data_architecture.md` |
|
||||
| Point-in-Time Self / Lived Experience | `../functional/self_model_and_lived_experience.md` | `data_architecture.md`, `privacy_gateway.md` |
|
||||
| Privacy Gateway / External-AI-Guardrails | `../functional/guardrails.md` | `privacy_gateway.md`, `ai_architecture.md`, `voice_and_media.md` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Referenz und bewusste Nicht-Übernahmen
|
||||
|
||||
**Referenzimplementierung:** Mitai Jinkendo (`C:\dev\mitai`, Gitea `Lars/mitai-jinkendo`).
|
||||
|
||||
**Foundation-Muster:** `C:\dev\mitai\.claude\docs\jinkendo-foundation/`.
|
||||
|
||||
**Produktrahmen: weitgehend von Mitai übernehmen** (Shell, Auth, Router, Compose, Migrationen, Admin-Realm, Nav-Mechanik, Breakpoint, **Registry-Muster, Prompt-/Workflow-Engine, Data-Layer-Trennung, Feature-Check an der API**). Abweichungen nur dort, wo sie zwingend sind.
|
||||
|
||||
**Nicht als Rahmen übernehmen bzw. zwingend ergänzen:**
|
||||
|
||||
- Shinkan-Vereins- und Mandantenmodell. Kanshō bleibt nutzerbezogen: ein Login = ein Profil.
|
||||
- Kairo als UI-/Verhaltensvorlage.
|
||||
- Mitai-**Domäne** (Körper-Tracking, Messwerte, CSV-Import, Membership-Tiers als Produktkern).
|
||||
- Mitai-Auth-Lücke: Profilwahl über `X-Profile-Id` ohne Session-Bindung. Siehe `auth_identity_and_roles.md`.
|
||||
- TypeScript als Pflicht-Stack.
|
||||
- JWT/SSO als aktuelle Auth.
|
||||
- **Direktaufrufe an LLM-Provider** wie in Mitai (`prompt_executor` → OpenRouter). Kanshō ergänzt zwingend das Privacy Gateway; das ist die zentrale Abweichung vom Mitai-KI-Pfad.
|
||||
|
||||
Mitai-Hauptnav-**Beschriftungen** (Erfassen, Ziele, …) sind Domäne. Die Nav-**Mechanik** (SSoT, Bottom-Nav, Sidebar, Shells) gehört zum Rahmen und wird übernommen. Welche Kanshō-Einträge später in dieser Mechanik stehen, folgt dem **dann aktuellen** Fachstand.
|
||||
|
||||
---
|
||||
|
||||
## 5. Technische Grundentscheidungen (Stack)
|
||||
|
||||
Herkunft: Nutzeranforderung (nahezu identischer Produktrahmen) plus Mitai-Referenz. Fachliche Vorbedingungen: PWA, Mobile First, responsive Desktop (`produktvision_und_produktidentitaet.md` §19).
|
||||
|
||||
| Thema | Entscheidung | Status |
|
||||
|---|---|---|
|
||||
| Lieferform | Progressive Web App (Mitai-Rahmen) | entschieden |
|
||||
| Frontend | React 18, Vite, React Router 6, Lucide | entschieden |
|
||||
| TypeScript | kein Pflicht-Stack | entschieden |
|
||||
| Backend | FastAPI, Python 3.12 | entschieden |
|
||||
| Datenbank | PostgreSQL 16 | entschieden |
|
||||
| API-Stil | REST, API-First, Business-Logik nur Backend | entschieden |
|
||||
| Auth | serverseitige Sessions, bcrypt, Rollen `user` \| `admin` | entschieden |
|
||||
| Mandanten | keine Org-/Vereinsmandanten | entschieden |
|
||||
| Container | Docker Compose, Dev- und Prod-Umgebung | entschieden |
|
||||
| CI/CD | Gitea, Branch `develop` → Dev, `main` → Prod | entschieden |
|
||||
| KI-Laufzeit | externe Inferenz grundsätzlich vorgesehen | entschieden (fachlich) |
|
||||
| Prompt-/Workflow-Engine | ein Executor, DB-Konfiguration, Typen base/pipeline/workflow | entschieden (Mitai-Rahmen) |
|
||||
| Komponenten-Registry | einheitliches ID-Kanon-Muster | entschieden (Mitai-Rahmen) |
|
||||
| Privacy Gateway | zwingende lokale Schicht vor persönlichem AI-Egress | entschieden (fachliche Invariante) |
|
||||
| OpenRouter | Kandidat, kein Architekturzwang, kein Gateway-Ersatz | entschieden (fachlich) |
|
||||
| Ports / Domains | Muster wie Mitai, konkrete Werte nicht 1:1 kopieren | offen |
|
||||
| Offline-Ausprägung | Anforderung entschieden, Mechanismus offen | offen |
|
||||
| Transkription | Anforderung entschieden, Mechanismus offen | offen |
|
||||
|
||||
Details: `product_frame_and_stack.md`, `platform_extensibility.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Kanonische Kapitelstruktur
|
||||
|
||||
```text
|
||||
technische_zielarchitektur.md
|
||||
documentation_index.md
|
||||
product_frame_and_stack.md
|
||||
auth_identity_and_roles.md
|
||||
frontend_pwa_shell.md
|
||||
backend_and_api.md
|
||||
runtime_and_deploy.md
|
||||
platform_extensibility.md
|
||||
data_architecture.md
|
||||
memory_storage_and_offline.md
|
||||
privacy_gateway.md
|
||||
ai_architecture.md
|
||||
integrations_technical.md
|
||||
admin_diagnostics.md
|
||||
voice_and_media.md
|
||||
security.md
|
||||
```
|
||||
|
||||
| Datei | Kanonisches Thema | Reife v0.1 |
|
||||
|---|---|---|
|
||||
| `product_frame_and_stack.md` | 3-Tier, Stack, Nicht-Übernahmen | Rahmen entschieden |
|
||||
| `auth_identity_and_roles.md` | Session, Rollen, Admin-Gate | Rahmen entschieden |
|
||||
| `frontend_pwa_shell.md` | PWA-Shell, Breakpoint, Nav-SSoT | Mitai-Rahmen; Kanshō-IA folgt späterem Fachstand |
|
||||
| `backend_and_api.md` | Router, API-First, Fehlerformat | Rahmen entschieden |
|
||||
| `runtime_and_deploy.md` | Migrationen, Compose, Gitea | Muster entschieden, Ports offen |
|
||||
| `platform_extensibility.md` | Registry, Prompt-/Workflow-Engine, Konfiguration, Data Layer | Mitai-Prinzipien entschieden; Fachinhalte offen |
|
||||
| `data_architecture.md` | Persistenzgrenzen, Entitäten ohne Schema | Arbeitsstand, nicht final |
|
||||
| `memory_storage_and_offline.md` | Dialogspeicher, Sync, Offline | Arbeitsstand, Sync offen |
|
||||
| `privacy_gateway.md` | Trust Zones, Egress, Demasking | Invariante entschieden; Verfahren offen |
|
||||
| `ai_architecture.md` | Inferenzpfad, Agenten (später) | Gateway bindend; Agenten offen |
|
||||
| `integrations_technical.md` | Handoffs zur Produktfamilie | Arbeitsstand, Verträge offen |
|
||||
| `admin_diagnostics.md` | Diagnoseansicht | Mitai-Admin-Realm; Kanshō-Inhalte später |
|
||||
| `voice_and_media.md` | Sprache / Transkription | Bedarf im Fachstand, Ausprägung offen |
|
||||
| `security.md` | Rate Limit, Secrets, Encryption | Teil entschieden, Rest offen |
|
||||
|
||||
---
|
||||
|
||||
## 7. Capability-Check vor Vereinfachung
|
||||
|
||||
Vor einer technischen Modellvereinfachung ist zu prüfen:
|
||||
|
||||
1. Welche Fachanforderungen brauchen die Struktur – Invariante (Privacy) vs. Arbeitsstand (Dialog/MVP)?
|
||||
2. Welche späteren Fähigkeiten (Memory, Self Model, Threading, Provenance, Re-Grounding) wären betroffen?
|
||||
3. Welche Integrationen hängen davon ab?
|
||||
4. Ist die Vereinfachung reversibel?
|
||||
5. Kann wahrgenommene Komplexität stattdessen in der UX abstrahiert werden?
|
||||
|
||||
---
|
||||
|
||||
## 8. Aktueller Entscheidungsstand (übergreifend)
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Fachlich vs. technisch getrennt | getrennte Ordner; Fachdoku führend; Guardrails bindend, Dialog/MVP nicht final | entschieden |
|
||||
| Produktrahmen | Mitai weitgehend (PWA, Auth, Shell, Deploy, Registry, Prompt-Engine) | entschieden |
|
||||
| Fachstand Dialog/MVP | Arbeitsstand, nicht final | entschieden |
|
||||
| Datenschutz / Guardrails | Invariante, bindend | entschieden |
|
||||
| Kanshō-Start-IA / Dialogmodell | folgt späterem Fachstand, nicht jetzt technisch einfrieren | offen |
|
||||
| Dialogspeicher vs. mindnet | aktueller Fach-Arbeitsstand | bevorzugte Richtung |
|
||||
| Originaldialog / Session ≠ Thread / Action Candidates | aktueller Fach-Arbeitsstand | nicht als Schema einfrieren |
|
||||
| AI-Agentenrollen | Reflection/Memory/Journal-Agenten | offen |
|
||||
| Thread-State-Machine | fachliche Zustände keine technische Vollständigkeit | offen |
|
||||
| MVP-Schnitt | nach fachlicher Konzeption, nicht dieser Rahmen | offen |
|
||||
|
||||
---
|
||||
|
||||
## 9. Noch nicht in v0.1
|
||||
|
||||
- SQL-Schemas und Migrationsdateien
|
||||
- OpenAPI
|
||||
- Prompt-Texte und Modellwahl
|
||||
- konkrete Ports, Domains, Serverpfade
|
||||
- MVP-Feature-Schnitt
|
||||
- Anwendungscode unter `frontend/` oder `backend/`
|
||||
|
||||
---
|
||||
|
||||
## 10. Querverweise
|
||||
|
||||
- Fachliche Governance: `../functional/fachliche_zielarchitektur.md`
|
||||
- Context Bundles: `documentation_index.md`
|
||||
- Interviewfortschritt: `../functional/interview_plan.md`
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: "Kanshō – Sprache und Medien"
|
||||
version: "0.1"
|
||||
status: "Arbeitsstand"
|
||||
date: "2026-08-19"
|
||||
product_family: "Jinkendo"
|
||||
document_role: "Technical Chapter / Voice / Transcription / Media"
|
||||
parent_document: "technische_zielarchitektur.md"
|
||||
---
|
||||
# Kanshō – Sprache und Medien
|
||||
|
||||
Kanonisches Home für Spracheingabe und Transkription. Fachlich erforderlich, Ausprägung offen (`produktvision_und_produktidentitaet.md` §19.5). Interview G3 ist nicht abgeschlossen.
|
||||
|
||||
## 1. Anforderung
|
||||
|
||||
Auf dem Smartphone darf Reflexion nicht zwingend Tippen erfordern. Transkription ist eine zentrale technische Funktion.
|
||||
|
||||
Sie ist kein Freibrief für Cloud-Speech ohne Policy.
|
||||
|
||||
## 2. Egress-Klasse
|
||||
|
||||
Transkriptionsdienste sind eine **eigene Trust- und Policy-Zone** (`guardrails.md` §13). Ein ZDR-LLM-Endpoint legalisiert nicht denselben Audiostream oder denselben Klartext an einen Speech-Provider.
|
||||
|
||||
Klasse-A-Identität und unnötige Quasi-Identifikatoren gelten auch für Metadaten von Audio (Dateiname, GPS, Geräte-ID).
|
||||
|
||||
## 3. Offene Ausprägung
|
||||
|
||||
Nicht entschieden, daher kein Implementierungszwang in v0.1:
|
||||
|
||||
- Live vs. nachträgliche Transkription
|
||||
- lokal vs. serverseitig vs. externer Speech-Dienst
|
||||
- Bearbeitung vor Übernahme in den Dialog
|
||||
- Sprecher-/Pausenlogik
|
||||
- lange Aufnahmen
|
||||
- Audio löschen nach Transkript vs. als Medium behalten
|
||||
- Push-to-talk vs. Daueraufnahme
|
||||
- Offline-Transkription
|
||||
|
||||
## 4. Leitplanken für jede spätere Wahl
|
||||
|
||||
- Das Transkript wird zur Originalrepräsentation des Dialogs oder zu einer klar gekennzeichneten Ableitung; die Regel muss dokumentiert werden, bevor Re-Grounding darauf aufsetzt.
|
||||
- Nutzerkorrektur vor Persistenz als bevorzugte Richtung (fachlich offen, technisch vorbereiten).
|
||||
- Fail Closed: kein unsicherer Cloud-Speech-Fallback.
|
||||
- Journal- und Writing-Profile laufen auf Text nach Korrektur, nicht auf Roh-ASR-Fehlern als „persönlicher Stil“.
|
||||
|
||||
## 5. Entscheidungsstand
|
||||
|
||||
| Thema | Stand | Status |
|
||||
|---|---|---|
|
||||
| Transkription erforderlich | ja | entschieden (fachlich) |
|
||||
| Eigener Egress-Typ | ja | entschieden (fachlich) |
|
||||
| Verfahren, Vendor, Speicherdauer Audio | – | offen |
|
||||
|
||||
## 6. Offene Fragen
|
||||
|
||||
Siehe Interview G3. Zusätzlich: Wie verhält sich Voice zum Working Context, während ein Thread-Wechsel erkannt wird?
|
||||
|
||||
## 7. Querverweise
|
||||
|
||||
- `privacy_gateway.md`, `frontend_pwa_shell.md`, `memory_storage_and_offline.md`
|
||||
- Fachlich: `../functional/produktvision_und_produktidentitaet.md` §19.5
|
||||
Reference in new issue
Block a user