13 KiB
| title | version | status | date | product_family | document_role | parent_document |
|---|---|---|---|---|---|---|
| Kanshō – Technische Zielarchitektur | 0.1 | Arbeitsstand | 2026-08-19 | Jinkendo | Technische Zielarchitektur / Master Structure | ../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-Idohne Session-Bindung. Sieheauth_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
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:
- Welche Fachanforderungen brauchen die Struktur – Invariante (Privacy) vs. Arbeitsstand (Dialog/MVP)?
- Welche späteren Fähigkeiten (Memory, Self Model, Threading, Provenance, Re-Grounding) wären betroffen?
- Welche Integrationen hängen davon ab?
- Ist die Vereinfachung reversibel?
- 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/oderbackend/
10. Querverweise
- Fachliche Governance:
../functional/fachliche_zielarchitektur.md - Context Bundles:
documentation_index.md - Interviewfortschritt:
../functional/interview_plan.md