262 lines
13 KiB
Markdown
262 lines
13 KiB
Markdown
---
|
||
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.
|
||
|
||
**Additiv 2026-08-25:** Der erste vertikale Journal-Slice ist im Code vorhanden. Der fachliche Lieferumfang bleibt `../functional/mvp.md`. Die **technische Umsetzung** (Laufzeit, Module, API, Daten) steht in `mvp_implementation.md`. Der Ist-Stand gegen Spec und Gesamtziel (Fit-Gap) steht in `../functional/mvp_stand_und_abgleich.md`. Technische „Implementierungsstand“-Abschnitte in den Einzelkapiteln sind Ausschnitte; sie ersetzen diese beiden Homes nicht. Der MVP-Schnitt in der Tabelle unten bleibt als *fachliche* Freeze-Frage Arbeitsstand; er ist nicht „nicht gebaut“.
|
||
|
||
---
|
||
|
||
## 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
|
||
mvp_implementation.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 |
|
||
| `provenance_verification.md` | Untrusted Modellausgabe, lokale Registry, `VerifiedArtifact` | Technisch entschieden 2026-08-25; zukünftige Intent-Policies 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 |
|
||
| `mvp_implementation.md` | Technische Umsetzung des Journal-Slices (Ist-Code) | Code 2026-08-25 |
|
||
|
||
---
|
||
|
||
## 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`
|