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