Architektur

Aufrufkette

Persönliche Website / Web Component
             │ JSON oder SSE über HTTPS
             ▼
FastAPI: Validierung → Persona-Aufbau → Chat-Dienst → Provider-Adapter
             │                                            │
             │                                            ├── gehostete API (aktuelle Voreinstellung)
             │                                            ├── lokales llama.cpp (Entwicklung)
             │                                            └── selbst gehosteter Modellserver über HTTPS + API-Key (bereit)
             └── schreibgeschützte, vom Autor freigegebene Persona-Dateien

Der Provider-Adapter ist die einzige Stelle dieser Architektur, die für einen späteren Modellwechsel vorgesehen ist. Alle drei Backends liegen hinter derselben Schnittstelle; ein Wechsel berührt den Frontend-Vertrag nie.

Betriebstopologie

Das statische Frontend läuft unter meiner eigenen Domain, FastAPI als einzelne Instanz auf einer kostenlosen Container-Plattform. Das Image wird aus dem Repository-Wurzelverzeichnis gebaut, damit der Container sowohl den Backend-Code als auch das darüber liegende, schreibgeschützte Persona-Verzeichnis erhält.

Zentrale Architekturentscheidungen

Das Backend ist zustandslos. Der Gesprächsverlauf reist mit dem Browser. Der Preis ist eine etwas größere Anfrage, der Gewinn ein Dienst, der sich jederzeit neu starten, skalieren oder verschieben lässt — und keine Frage danach, wessen Chatverlauf auf dem Server liegt.

Private Quellmaterialien sind von der auslieferbaren Persona physisch getrennt. Zwei Verzeichnisse; nur das zweite gelangt ins Image.

Die Entwicklung darf ohne API-Key starten, die Produktionsprüfung nicht. Lokale Arbeit soll nicht an Zugangsdaten scheitern, aber die Produktion verweigert den Start, sobald etwas fehlt.

Das Frontend nutzt Shadow DOM. Die Komponente lässt sich überall einbetten, ohne Stile in die Gastseite zu tragen, und das CSS der Gastseite erreicht sie nicht.

Die CORS-Konfiguration in der Produktion ist keine einstellbare Liste, sondern zwei im Code fixierte Ursprünge. Einer zu viel, einer zu wenig oder ein Platzhalter — der Dienst startet nicht.

Die Deployment-Beschreibung deklariert kostenlosen Tarif, eine einzelne Instanz und abgeschaltetes automatisches Deployment ausdrücklich und legt weder Datenbank noch Datenträger an. Die Kostengrenze steht in der Versionsverwaltung, nicht im Gedächtnis.

Der Container wird aus einer Lockfile gebaut, läuft ohne Root-Rechte und startet den Prozess mit exec, damit das SIGTERM der Plattform tatsächlich ankommt und nicht von einer Shell verschluckt wird.

Der selbst gehostete Modellserver läuft nicht auf der kostenlosen Plattform. Er arbeitet getrennt, der Modellport ist nur im Container-Netz sichtbar, und ein Reverse Proxy gibt über HTTPS ausschließlich einen Health Check und einen per Bearer-Key geschützten Inferenz-Endpunkt frei. Solange dieser Server nicht verifiziert ist, bleibt die Produktion auf die gehostete API gerichtet — es soll gar nicht erst die Gelegenheit geben, den Live-Verkehr versehentlich umzuschalten.