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:
Lars committed 2026-08-21 15:48:43 +02:00
1 parent 3a367b7bcc
commit d62673e48b
89 files changed
+13463 -241

No files matched your search

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