18 KiB
C – Technical Decisions & Open Issues
Phase 3.2 · v0.3 · 16.10.2026 · technischer Vorschlag, keine Produktionsfreigabe
Management-Zusammenfassung
Die Referenz bleibt beim vorhandenen Stack: FastAPI, React/Vite, PostgreSQL, Docker Compose und Gitea. Neu zusammengeführt werden eine modulare Struktur, explizite Transaktionen, ein einheitlicher HTTP-Vertrag und ein Release-Verfahren mit verpflichtenden Gates und nachvollziehbarer Quell-/Build-/Artefaktzuordnung. Für neue Apps werden unterstützte Versionslinien verwendet; vorhandene Apps erhalten keinen pauschalen Upgradeauftrag.
Die frühere Hervorhebung Kairos als „Hauptvorbild“ war zu weitgehend und wird zurückgenommen. Ich hatte die sichtbare Service-/Registry-Struktur für die Foundation übergewichtet und die spezialisierten, tatsächlich vorhandenen Mechanismen der anderen Produkte zu stark auf Nebenrollen reduziert. Daraus folgt weder Kairos höhere Produktreife noch ein belegter Vorsprung bei den meisten belastbaren Mustern.
Die korrigierte Referenzwahl ist bereichsspezifisch: Mitai für Prompt-/Workflow-Laufzeit und Registrierungsverträge; Shinkan für Nutzer-/Vereinssichten, Berechtigungen und Security-Mechanismen; Kanshō für Maskierung privater KI-Daten; Kairo für einzelne ergänzende Struktur-, Konfigurations- und Actor-Token-Muster. Die Foundation bleibt eine Synthese. Transaktions-, Migrations- und Releaseverträge werden dort gezielt ergänzt, wo keine vorhandene Implementierung vollständig genügt.
Die drei offenen Punkte unten betreffen die erste konkrete Produkteinführung. Die Foundation benötigt dafür keine weitere Grundsatzentscheidung. Der nächste sinnvolle Spezial-Blueprint ist Auth, Session & Scope: sichere Cookies/CSRF, verlässliche Datenraumauflösung, Objektzugriff und geschlossene Ersteinrichtung. Kein weiterer Arbeitsschritt wurde automatisch gestartet.
Gezielte Korrekturen in v0.3
- ADR-11 / Release: R1 „Build once, deploy many“ bleibt bevorzugter technischer Default. R2 – kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds – bleibt zulässig. Beide benötigen Pflicht-Gates vor Prod, menschliche Freigabe und eindeutige Zuordnung der tatsächlich eingesetzten Version. Bei R2 wird der konkrete Prod-Kandidat zusätzlich qualifiziert. Branchstrategie und bestehende Infrastruktur bleiben erhalten.
- Nachweis: A/B sind V (vorgeschlagener technischer Standard) und als Kombination K (noch nicht integriert/getestet). Produkt-Codeverweise sind I (vorhandene Implementierungsreferenz). T setzt bestandene Tests mit Umfang, Stand und Umgebung voraus; für die Foundation wird kein T-Gesamtnachweis oder Produktionsreife behauptet. Die früher benannten Testquellen werden dadurch nicht zu Testergebnissen.
- Verträge / Defaults: A0 unterscheidet verbindliche Schutz-, Datenraum-, Transaktions- und Releaseverträge von anpassbaren technischen Defaults wie Poolgröße, Timeout, Verzeichnisdetail und Framework-Version. Begründete Anpassung im Produktauftrag bzw. in der Konfiguration genügt; keine neuen ADRs oder Freigabeschleifen.
Die bereichsspezifische Referenzauswahl und die bisherigen drei offenen Produkt-/Betriebspunkte bleiben unverändert. Die nachstehende Einordnung wird aus v0.2 übernommen; v0.3 führt keine erneute Produktreifebewertung oder Konsolidierung durch.
Überprüfung der bisherigen Gewichtung
Nutzerangabe: Kairo ist noch nicht im Einsatz und der MVP enthält erhebliche Baustellen bis zur nutzbringenden Verwendung. Das ist relevante Erfahrung des Produkteigentümers und widerspricht einer Darstellung als besonders betriebsbewährtes Gesamtvorbild. Es ist keine hier neu erhobene Nutzungsmetrik; für die anderen Produkte wird daraus ebenfalls kein pauschaler Produktionsnachweis abgeleitet.
Prüfmaßstab: Ein klarer Ordnername ist ein Strukturhinweis. Ein konkreter implementierter Mechanismus ist stärker. Testassertionen, tatsächlich bestandene Tests eines bekannten Standes und erfolgreiche Nutzung sind weitere, getrennte Nachweise. Im Ergänzungsreview wurden Code und ausgewählte Testassertionen gelesen, keine Tests ausgeführt. „Am meisten belastbar“ ist damit als Gesamtranking nicht belegt.
| Produkt / primärer Referenzbereich | Konkret nachgelesener Mechanismus | Was daraus folgt / was offen bleibt |
|---|---|---|
| Mitai · Prompt-/Workflow-System | Graphvalidierung und topologische Ordnung, ausführender Workflow mit Verzweigungen/Joins, Platzhalterauflösung, Metadaten/Resolver und Duplikatsperre. Engine, Executor, Registry, Testquelle | Vorrangiger vorhandener Implementierungskandidat für diese Funktionen und für kleine Registry-Verträge. Nicht nur Widgets. Ein Schemaargument im Prompt-JSON-Validator wird noch nicht als JSON-Schema validiert; Legacypfade und Diagnoseinhalte benötigen Anpassung. |
| Shinkan · Sichten, Rechte, Security | Gemeinsame SQL-Sichtbarkeit für privat/Verein/offiziell, aktive Mitgliedschaft, Kontozustände; Tests für Sessionprofil, Produktionsdiagnose, öffentliche Medien und Nosniff sowie Graphsichtbarkeit. Policy, Account, Securitytests, Sichtbarkeitstests | Primäres konkretes Vorbild für Scope-/Access-Verträge. Die vorherige Verkürzung auf Navigation/Securitychecks war sachlich unzureichend. Vorhandener Layer und geprüfte Einzelregeln belegen noch keine vollständige produktive Security-/Datenschutzabnahme. |
| Kanshō · Maskierung/Privacy-Gateway | Requestbezogenes Maskierungsmanifest, aktive Ersetzungen, Vorabprüfung und Blockade vor dem Modellaufruf, lokale Rückübersetzung. Maskierung, Gate, Testquelle | Primäres Vorbild für persönliche KI-Datenflüsse; nicht lediglich ein Psycopg-/Test-DB-Beispiel. Semantisch vollständige Erkennung jedes privaten Datums und alle Egress-Pfade sind damit nicht bewiesen. |
| Kairo · ergänzende Teilmechanismen | Separate Services, deklarative Registrierungen, Secret-Referenzprüfung und Actor Tokens sind vorhanden. Im untersuchten Action-Pfad greift der Router auf Services und Read Models zu; Data Layer importiert private Servicehelfer und führt selbst SQL aus. Router, Data Layer, Connection-Prüfungen | Nützliche isolierte Kandidaten, aber keine durchgängig nachgewiesene Router → Service → Repository-Implementierung. Kein Vorrang des Gesamtprodukts und kein Betriebsreife-Beleg. |
Die Kritik ändert die Gewichtung und Wiederverwendungsherkunft, nicht automatisch jede technische Zielentscheidung. Der begrenzte Phase-3.2-Fokus auf Foundation rechtfertigt, einen umfangreichen Workflow-Editor nicht in jede neue App einzubauen. Er rechtfertigt nicht, das bereits vorhandene Prompt-/Registrierungssystem bei der Referenzwahl abzuwerten. Für KI-Funktionen werden Mitais Laufzeit und Kanshōs Privacy-Vertrag ausdrücklich vor einer neuen Eigenlösung herangezogen; Zugriffsverträge werden an Shinkans konkreten Sichten und Regeln ausgerichtet.
Technische Empfehlungen und wichtigste Alternativen
Nachweisstatus: Die bevorzugten Zielausgestaltungen sind V, ihre noch nicht ausgeführte Kombination K; die Herkunftsspalte nennt bestehende Referenzen I. Keine Zeile wird hier als durch Tests validierte Foundation-Lösung T ausgewiesen. Die Geltung verbindlicher Verträge gegenüber technischen Defaults folgt A0.
| ID / Bereich | Bevorzugte Lösung und Begründung | Wichtigste Alternative / bewusste Grenze | Konkrete Herkunft |
|---|---|---|---|
| TF-01 · Struktur | Produktlokaler modularer Monolith; Router → Service → Repository/Port; ein Composition Root. Aus vorhandenen Teilmechanismen abgeleiteter Zielentwurf, noch keine validierte Gesamtimplementierung; kein neuer Betrieb. | Großer Router-Monolith wird nicht fortgesetzt; Microservices oder allgemeiner Domänenkern bringen für die Foundation keinen belegten Vorteil. | Gezielte Synthese: Mitai-Cursorvertrag, Kairo-Serviceabgrenzung als Teilbeispiel; dort keine durchgängige Zielschichtung. |
| TF-02 · Backend | FastAPI/Pydantic, explizite DI, synchrone PostgreSQL-Anwendungsfälle, ein Transaktionskontext je atomarem Service. | Durchgehend async nur bei realem I/O-Bedarf. Keine zweite Connection in verschachtelten Validierungen, kein später Response-Commit. | KI-MIT-02/17; Cursor-/Savepoint-Regeln; Anpassungsbedarf im Kairo-Service |
| TF-03 · Frontend | React-SPA, explizite Modulregistry, Data Router, lokaler Formularzustand; kleiner Session-/Scope-Store statt globalem Fachdaten-Context. | Kein Redux/TanStack-Query-Zwang ohne konkreten Bedarf; kein SSR-/RSC-Wechsel. Registry darf Fehler nicht verschlucken. | Vorrangig Mitai-Registryvertrag und Widgets; Shinkan-Navigation; Kairo-Slices ergänzend. |
| TF-04 · API | /api/v1, explizite Pydantic-DTOs, OpenAPI und Problem Details; ein Browser-Transportclient. |
Heutige verschiedenförmige detail-/HTML-Fehler werden nur im Bestandsadapter toleriert; kein vollständiges neues RPC-/GraphQL-System. |
KI-MIT-04; vorhandene Fehlernormalisierung, Problem Details |
| TF-05 · Datenbank | PostgreSQL 16, Psycopg 3 mit begrenztem nativen Pool; SQL-Dateien mit Lock, Prüfsumme und atomarem Ledger. | Psycopg 2 ist Bestandsvariante. Kein ORM-/Alembic-Wechsel zur Lösung eines klar begrenzten Runner-Problems; kein SQLite-SQL-Übersetzer im Standard. | KI-SHK-06, KI-KAI-08, KI-KAN-06; bestehender Pool, Runner, Psycopg 3 |
| TF-06 · Konfiguration | Explizite Prozessumgebung und Pydantic-Validierung; Secrets nur in Adapter/Betriebsbereitstellung; unbekannte Umgebung stoppt. | Kein zusätzlicher Secret-Server. Kein Default-Passwort, kein automatisches development, kein Secretwert in technischer DB-Konfiguration. | KI-KAI-14, KI-KAN-16; Secretreferenz-Prüfung, Env-Fallback als Gegenbeispiel |
| TF-07 · Testing | pytest und echtes isoliertes PostgreSQL; Vitest/RTL und wenige Image-Browsertests; Pflichtfälle statt bloßer Dateipräsenz. | Keine produktiven Mutationen, kein SQLite-Ersatz, keine Testinstallation in laufenden App-Containern und keine still übersprungenen Pflichtsuiten. | KI-SHK-12, KI-KAN-14; Sicherheitschecks, Test-DB-Trennung |
| TF-08 · Deployment | Verbindlich: bestehende Branchfolge, menschliche Freigabe, Release-Gates und Quell-/Build-/Artefaktzuordnung. Default R1: identische qualifizierte Images übernehmen. | ADR-11-Variante R2: kontrollierte reproduzierbare separate Builds mit Pflicht-Gates für den konkreten Prod-Build vor Deployment. Keine neue Infrastruktur; Tests nur nach Prod reichen nicht. | KI-KAI-16, KI-SHK-13; isolierter Kairo-PR-Stack, Gitea: environment ignoriert |
| TF-09 · Extension/Reuse | Erst lokaler Vertragsstandard; kleine Library bei zwei tatsächlichen Abnehmern und benanntem Maintainer. | Keine Cross-Repo-Runtime-Imports, gemeinsame Fachdatenbank, SSO- oder Billing-Plattform auf Vorrat. Zentrale Dienste benötigen echten Betriebsnutzen. | Beschlossener ADR-13 / Reuse First; vorhandenes Register |
Gezielte Anpassungen statt unveränderter Kopie
Die vorhandenen Muster sind Referenzen, kein bereits gemeinsam getestetes Foundation-Paket. Insbesondere wird Kairos psql-Migrationspfad nicht als atomar übernommen: SQL wird dort in einem separaten Prozess committed, der Ledger-Eintrag danach. Die Referenz führt beides auf derselben Connection zusammen. Mitais und Shinkans Pool-/Contextmanager liefern die Richtung, der neue native Psycopg-Pool ersetzt deren konkrete Poolklasse. Die heutige gemischte Cursor-/Connection-Erzeugung wird nicht vererbt.
Bei Registry-Bausteinen wird Überschreiben doppelter IDs durch Aufbaufehler ersetzt; Ladefehler bleiben unterscheidbar statt null. Der gemeinsame API-Client übernimmt Fehlernormalisierung, aber weder das mutable Profilheader-Muster noch ungeprüfte Profilauflösung. Aktuelle App-Regeln über HTML-Sanitizer, Datenschutz oder Importtransaktionen bleiben für tatsächlich übernommene Funktionen relevant.
psycopg_pool ist eine zusätzliche native Treiberkomponente für begrenzte threadsichere Connections, keine neue Infrastruktur. pip-tools ist die einzige zusätzliche Build-Hilfe für Python-Lockfiles mit transitiven Pins/Hashes. Beides löst ein konkretes Foundation-Problem; weitere Frameworks werden nicht vorsorglich ergänzt.
Die Frontend-Versionsaktualisierung gilt ausschließlich für den vorgeschlagenen Neuaufbau. Bestehende React-/Router-Anwendungslogik kann angepasst übernommen werden; eine Kompatibilitätsprüfung der neuen Paketkombination erfolgt beim späteren Aufbau mit Lockfiles und B4. Daraus wird kein getesteter Paketstand behauptet. Die Versions-/Supportquellen und ihre Einordnung als technische Defaults stehen in A1/A0; v0.3 nimmt keine neue Versionsrecherche vor.
Drei offene Punkte
| Punkt | Was bei der ersten konkreten App festzulegen ist | Default / Auswirkung auf die Foundation |
|---|---|---|
| O1 · Datenraum und Schutzbedarf | Konto=Person, Club oder Organisationsraum; welche vertraulichen Mehrraumdaten zusätzlichen RLS-Schutz benötigen. | Expliziter Scope-/Policyvertrag und eingeschränkte Runtime-Rolle stehen fest. Keine universelle Tenanttabelle, kein stiller Erstprofilfallback. Keine externe Freigabe vertraulicher Mehrraumfunktionen ohne diese Produktausprägung. |
| O2 · Wirksame Gitea-Sperren | Tatsächliche Server-/Runnerfähigkeiten, erforderliche Statuschecks, Main-Schutz, getrennte Berechtigungen und verfügbare Artefaktablage bestätigen. | Menschliche Freigabe, Release-Gates und eindeutige Versionszuordnung sind festgelegt; gleiche Images sind Default R1, getrennte qualifizierte Builds zulässige Variante R2. Ohne wirksame Sperren gibt es keine Prod-Promotion; bloßes environment: production zählt nicht. Die tatsächliche Server-/Runnerkonfiguration wurde nicht abgefragt oder verändert. |
| O3 · Recoveryprofil | RPO/RTO, Restorefenster, Medien-/Schlüsselumfang und Schutz der Backups des ersten Produkts. | PostgreSQL-Backup und geprobter Restore vor datenverändernder externer Freigabe; kompatibles altes Image oder kontrollierter Forward-Fix. Keine pauschalen SaaS-Verfügbarkeitszusagen. |
Das sind keine weiteren familienweiten Architekturfreigaben. Die Angaben werden Teil des konkreten Produkt-/Betriebsauftrags; sie verhindern die technische Grundstruktur nicht. ADR-15 und ADR-16 werden in dieser Phase weder bestätigt noch als Voraussetzung für die Foundation behandelt.
Quellen- und Prüfstand
Verwendet wurden die benannten Phase-3.1-Wissenselemente, Abhängigkeiten, Guardrailabschnitte und Kandidaten. Für konkrete Entscheidungen wurden gezielt Codeabschnitte nachgelesen, keine neue Inventur erstellt. Die Guardrail-Originalabschnitte wurden nach den betroffenen Regeln/Erfahrungen ausgewählt.
Die Auswahl folgt den tatsächlichen A01-Einträgen und Codepfaden: Mitais CSV-Registry/Aggregation sind KI-MIT-17/18, der PDF-Export KI-MIT-19. Einzelne E01-Kandidatenzuordnungen enthalten zusätzlich andere Themen; sie werden nicht ungeprüft als Implementierungsnachweis fortgeschrieben. Phase 3.1 bleibt unverändert.
Die ursprüngliche Fassung erfasste 103 gezielte Eingaben; der Ergänzungsreview in v0.2 dokumentierte die Referenzgewichtung. Diese historischen Quellprüfungen werden in v0.3 nicht wiederholt. Für v0.3 wurden ausschließlich die drei v0.2-Dokumente an den beauftragten Punkten geändert und auf Konsistenz geprüft. v0.2 bleibt unverändert. Es wurden weder Produkt-Repositories geändert noch Code, Produkttests, Paketinstallationen, Laufzeitprüfungen, Migrationen, Deployments oder Gitea-Änderungen ausgeführt. Die Beispiele und Zielkombinationen bleiben K; Dokumentationsprüfungen sind keine T-Validierung der Foundation.