Architektur
Systemarchitektur Übersicht
Fastify v5, Directus SDK, LiteLLM Orchestrierung und Fail-Fast Systemarchitektur
Systemarchitektur
Der LoreKeeper Service ist modular aufgebaut und trennt strikt zwischen API-Routing, Datenbankpersistenz und KI-Orchestrierung.
graph TD
Client[Client / Redakteur / Agent] -->|HTTP / JSON| Fastify[Fastify v5 Backend Service]
subgraph "LoreKeeper Service Container"
Fastify --> Env[Zod Config .env]
Fastify --> DirectusPlugin[Directus SDK Plugin]
Fastify --> LoreService[AgenticLoreService]
end
DirectusPlugin -->|Healthcheck Ping / REST| Directus[Remote Directus Headless CMS]
Directus --> Hook[liberino-schema-hook]
Directus --> NeonDB[(Neon.tech PostgreSQL)]
LoreService -->|OpenAI SDK Client| LiteLLM[LiteLLM Proxy :4000]
LiteLLM -->|router-model| GeminiFlash[Google Gemini 2.5 Flash]
LiteLLM -->|writer-model| GeminiPro[Google Gemini 2.5 Pro]Technologie-Stack im Detail
| Schicht | Technologie | Begründung & Rolle |
|---|---|---|
| API-Framework | Fastify v5 (TypeScript) | Schneller als Express, native Plugin-Architektur, standardisierte Schema-Validierung und integriertes Pino-Logging. |
| Konfiguration | Zod + dotenv | Strikt typisierte .env-Validierung; bricht sofort ab (Fail-Fast), wenn Variablen fehlen. |
| Headless CMS | Directus 12 | Liefert relationale Datenbankverwaltung, Admin-UI, Rollenmanagement und Webhook-Trigger. |
| CMS Extension | liberino-schema-hook | Deklaratives Schema-Management: synchronisiert Collections, Relationen und UI-Felder beim Directus-Start. |
| KI-Proxy | LiteLLM | Normalisiert LLM-Zugriffe auf OpenAI-kompatible Schnittstellen und leitet logische Modelle an Google Gemini weiter. |
| KI-Modelle | Gemini 2.5 Flash & Pro | Flash für schnelle Intent- & Abfrageplanung (Router), Pro für narrative Prosa und komplexe Konsistenzprüfungen (Writer). |
| Container | Docker & Compose | Multi-Stage Build (Node 20 Alpine) mit non-root Benutzerrechten für maximale Sicherheit. |
Lebenszyklus einer Anfrage
- Eingangsvalidierung: Fastify validiert den eingehenden JSON-Body über Zod-Schemata.
- Intent & Abfrageplanung: Der
router-modelAgent analysiert das Ziel der Szene und identifiziert benötigte Figuren, Schauplätze und Regeln. - Deterministisches Laden: Directus liefert kanonische Datensätze aus PostgreSQL via
@directus/sdk. - LLM-Synthese: Der
writer-modelAgent generiert die Prosa mit injiziertem Kanon-Wissen. - Persistenz & Rückgabe: Das Ergebnis wird optional in Directus (
scenes) gespeichert und an den Client übergeben.