Technische Gesamtarchitektur, Technologie-Entscheidungen und Komponenten-Zusammenspiel

Technische Gesamtarchitektur

Der LoreKeeper Service ist ein zustandsloser Backend-Dienst auf Basis von Node.js, Fastify v5 (TypeScript ESM) und containerisierter KI-Proxy-Architektur.

Er trennt strikt zwischen Speicherung (Directus), KI-Inferenz (LiteLLM) und Anwendungslogik / Agentic-Loop (Fastify).

Komponenten-Übersicht

graph TD
    User[Endnutzer / Leser] -->|HTTP / React| Web[Next.js Web-Portal & E-Reader :3000 / web/]
    Creator[Autor / Entwickler] -->|Vite / React| MC[Mission Control Studio :5173 / :3999]
    
    Web -->|REST API :3005| Fastify[Fastify v5 Backend Service :3005]
    MC -->|REST API :3005| Fastify
    
    subgraph Core Engine
        Fastify --> Services[Services & ReAct Engine]
        Services --> AgentChat[AgenticChatService]
        Services --> LoreService[AgenticLoreService]
    end
    
    subgraph Data & Persistence
        Fastify -->|@directus/sdk Typed| Directus[Remote Directus Headless CMS]
        Directus --> Postgres[(PostgreSQL DB)]
    end
    
    subgraph AI Orchestration
        Services -->|OpenAI SDK Function Calling| LiteLLM[LiteLLM Proxy :4000]
        LiteLLM --> GeminiFlash[Google Gemini 2.5 Flash]
        LiteLLM --> GeminiPro[Google Gemini 2.5 Pro]
    end

Technische Kernmodule

Universelle Buch-Ingestion & Sprach-Mappings

Generische 2-Phasen Ingestion, modulare Sprach-Mappings (de/en), unüberwachtes Bild-Clustering und Zero-Fallback.

Agentic Loop & Tool Execution

Multi-Turn ReAct Loop, Function-Calling Tools gegen Directus und Inferenz-Orchestrierung.

Datenbank-Schema & Relationen

PostgreSQL-Tabellen, Indizes, M2O-Verknüpfungen und bitemporale Snapshot-Logik.

API-Architektur & Validation

Zod-Schemas, Error-Handling, OpenAPI 3.1 Spezifikation und REST-Endpoints.

Deployment & Container

Multi-Stage Dockerfile, Docker Compose, Port-Belegungen und Fail-Fast Healthchecks.

Technologie-Entscheidungen

Komponente	Wahl	Begründung
Framework	Fastify v5 (TypeScript)	Extrem geringer Overhead (hohe RPS), native Schema-Validierung, Plugin-Kapselung.
CMS / DB-Layer	Directus Headless CMS	Bietet Autoren ein vollwertiges Web-UI und Entwicklern eine typisierte REST/GraphQL-API via `@directus/sdk`.
KI-Proxy	LiteLLM	Normalisiert alle Modellaufrufe auf das OpenAI-Format. Ermöglicht logische Modellnamen (`router-model`, `writer-model`) und Provider-Austausch ohne Code-Änderungen.
Validierung	Zod v4	Strikte Typsicherheit zur Laufzeit und Fail-Fast Environment-Validierung beim Booten.

Technische Architektur & Stack