Kansho/docs/architecture/technical/backend_and_api.md

title	version	status	date	product_family	document_role	parent_document
Kanshō – Backend und API	0.1	Arbeitsstand	2026-08-19	Jinkendo	Technical Chapter / Backend / API	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

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:

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