Hathor Domain — Architecture

Worldbuilding, Narrative Design, and World Simulation Platform

Hathor is the creative worldbuilding platform within the Oshun monorepo. Its purpose is to give writers, game designers, and production teams a single, structured environment for designing fictional worlds and bringing them to life. A world author works in the visual Workbench, models factions, economies, and lore using the domain libraries, runs background simulations to watch the world evolve, and finally exports the results as engine-native assets for game engines or industry-standard formats for film production.

The domain spans 17 libraries and 7 applications covering world modeling, narrative systems, simulation engines, LLM-powered NPC intelligence, lore validation, lore compilation, game design theory, pre-production tooling, the Veilborn Chronicles game services, and cross-domain integration.

Hathor is a creative pipeline: worlds are designed in the Workbench, populated via the domain model libraries, simulated in the background worker, and exported to game engines and film production tools through the lore compiler and Bellona integration.

1. System Overview#

Core Responsibilities#

• World Modeling — Engine-agnostic domain types for factions, economies, laws, cultures, geography, timelines, characters, and locations
• Narrative Systems — Quest design, branching dialogue, non-linear story graphs, journal/codex, and narrative export
• World Simulation — Economy, politics, culture, and scenario simulation with NPC behavior trees and physics
• NPC Intelligence — LLM-powered personality, emotion, memory, world awareness, dialogue generation, and multi-platform AI integration
• Lore Validation — Timeline, causality, taxonomy, and contradiction checking
• Lore Compilation — Engine-native artifact generation for Unreal, Unity, Godot, Blender, and film formats
• Theory and Pre-Production — MDA framework, narrative theory, cinematography planning, chronicle parsing, storyboarding, and project management
• Cross-Domain Integration — Event-driven integration with Sophia, Isis, Yemaya, and Bellona

2. Service Architecture#

2.1 Applications#

The core worldbuilding work is spread across three Hono HTTP services plus a React SPA. The diagram below shows how they connect to each other and to the shared PostgreSQL database.

                     @hathor/workbench
                     (React SPA, Vite)
                            |
               +------------+------------+
               |                         |
    +----------v---------+  +------------v-----------+
    |   @hathor/world-api |  | @hathor/narrative-api  |
    |   (Hono, Port 3001) |  | (Hono, Port 3002)      |
    |                     |  |                        |
    | - World CRUD        |  | - Story graph CRUD     |
    | - Branch management |  | - Quest CRUD           |
    | - Version control   |  | - Dialogue CRUD        |
    | - Merge requests    |  | - Runtime sessions     |
    | - Query engine      |  | - Narrative validation |
    | - Collaborators     |  +------------------------+
    +----------+----------+
               |
    +----------v-------------------+
    |  @hathor/simulation-worker   |
    |  (Hono, Port 3004)           |
    |                              |
    | Background simulation jobs:  |
    | - Economy simulation         |
    | - Politics simulation        |
    | - Culture simulation         |
    | - Scenario generation        |
    | - Full world simulation      |
    +----------+-------------------+
               |
    +----------v----------+
    |  @hathor/database    |
    |  PostgreSQL          |
    |  (Prisma, no schema  |
    |   namespace)         |
    +---------------------+

The diagram above shows the three Hono worldbuilding services and the database. Three further applications sit alongside them: the @hathor/workbench React SPA, the @hathor/studio-web content-map package, and the two Veilborn Chronicles Fastify game services (@hathor/veilborn-core, @hathor/veilborn-strategy) — see § 2.2.

2.2 Application Details#

@hathor/world-api (Port 3001)#

Hono-based HTTP API server for world state management. This is the primary persistence boundary for world data: all world CRUD, versioning, branching, merge requests, entity management, and the query engine flow through this service.

• Framework: Hono with @hono/zod-validator validation
• Dependencies: @oshun/event-bus, @hathor/event-handlers, @hathor/event-publisher
• Auth: X-User-ID header forwarded from API gateway
• Rate limit: 100 req/min per IP on /api/* routes

@hathor/narrative-api (Port 3002)#

Hono-based HTTP API server for narrative resources. While the World API owns world structure and entities, the Narrative API owns the storytelling layer: story graphs, quests, dialogues, journal entries, and narrative validation.

• Framework: Hono with @hono/zod-validator
• Key feature: Runtime dialogue sessions with state tracking

@hathor/simulation-worker (Port 3004)#

Background worker process for running world simulations. Rather than blocking the World API, long-running simulation jobs are submitted here and processed asynchronously by a configurable worker pool. The worker reports progress via ticks and publishes a completion event when done.

• Concurrency: Configurable worker pool with health monitoring
• Job types: economy, politics, culture, scenario, integrated
• State: PostgreSQL for job records, Redis for state caching

@hathor/workbench (React SPA)#

React-based single-page application for visual worldbuilding. Provides a browser UI that covers the most common world design workflows without requiring SDK or API knowledge. Seven primary pages: Dashboard, Worlds, World Editor, Characters, Factions, Locations, Timeline.

• Technology: React 18, React Router DOM, TanStack Query, Zustand, Tailwind CSS, Lucide React, Highlight.js, DOMPurify
• Build: Vite

@hathor/veilborn-core (apps/hathor/svc-veilborn-core)#

Fastify service implementing the core game engine for Veilborn Chronicles, a tabletop RPG and wargame. This application demonstrates Hathor's capabilities as a game engine, not just an authoring tool. Built on @lilith/fastify-core and @lilith/service-lib. The HTTP surface exposes health/readiness/metrics endpoints; the game systems are ~30 fully tested domain-logic modules under src/ (hex-grid combat, character creation, abilities, cards, dice, seeded procedural world generation, wargame, AI, social, persistence).

@hathor/veilborn-strategy (apps/hathor/svc-veilborn-strategy)#

Fastify service implementing the "The Veil War" strategic game mode of Veilborn Chronicles. REST API for game management, state queries with fog-of-war, action submission, and save/load snapshots, plus optional @fastify/websocket real-time sync and JWT auth. Five game modes (Echoes of Fate, Resonance Wars, Weave Conspiracy, Eternal Game, Grand Campaign) each have their own engine, AI opponent, and route module, alongside a balance pipeline.

@hathor/studio-web (apps/hathor/studio-web)#

Small package defining the V2 fighting-game narrative content map (narrative surfaces, content packs, beats, and compiled-artifact plans). Depends only on @hathor/lore-compiler. Not an HTTP server.

3. Library Architecture#

3.1 Layer Overview#

Libraries follow a strict layered architecture to enforce unidirectional dependencies. The data layer sits at the bottom; integration and client layers sit at the top. Domain libraries may not import from the integration or client layers, which keeps the core world model testable in isolation.

Data layer:
  @hathor/database            — Prisma client and schema

Domain layer (core data):
  @hathor/domain-models       — Engine-agnostic world type system

Domain layer (systems):
  @hathor/narrative           — Quest, dialogue, story graph, journal, export
  @hathor/simulation          — Economy, politics, culture, scenario, NPC behavior, physics
  @hathor/validation          — Timeline, causality, taxonomy, contradiction checking
  @hathor/llm-npc             — LLM-powered NPC brain, dialogue, behavior, platforms
  @hathor/theory              — MDA framework, narrative theory, cinematography
  @hathor/pre-production      — Chronicle parsing, storyboarding, project mgmt, virtual production
  @hathor/lore-compiler       — Engine/film artifact compilation

Façade layer (cross-domain / CGI adapters):
  @hathor/characters          — CGI character-definition import facade
  @hathor/world               — CGI scene-definition import facade
  @hathor/timeline            — Narrative scene-order facade
  @hathor/quests              — Scene-dependency / story-arc capture facade

Integration layer:
  @hathor/sophia-integration  — Research grounding via Sophia
  @hathor/event-handlers      — Incoming event subscriptions
  @hathor/event-publisher     — Outgoing event publishing

Client layer:
  @hathor/client              — TypeScript SDK

The full library roster (17 total): database, domain-models, narrative, simulation, validation, llm-npc, theory, pre-production, lore-compiler, characters, world, timeline, quests, sophia-integration, event-handlers, event-publisher, client.

3.2 Library Descriptions#

@hathor/database#

Prisma-based database schema and client for Hathor. This library is the single source of truth for all persisted world data. It provides lifecycle management (getHathorClient, createHathorClient, disconnectHathorClient), database operations, and comprehensive TypeScript type definitions mirroring the schema (all enums, status types, entity types — available without code generation).

Tags: scope:hathor, layer:data

@hathor/domain-models#

Engine-agnostic worldbuilding domain models providing comprehensive type definitions for every aspect of a fictional world. This library deliberately has no runtime dependencies — it is pure TypeScript types, constants, factories, and validators that any other library or application can import without pulling in database or HTTP concerns.

Tags: scope:hathor, layer:domain

@hathor/narrative#

Engine-agnostic narrative systems with five subsystems. The library is intentionally separate from @hathor/domain-models because narrative structures (quest state machines, dialogue sessions, story graph traversal) carry runtime behaviour, not just type definitions.

Tags: scope:hathor, layer:domain

@hathor/simulation#

The largest library in the Hathor domain, providing four simulation managers, an NPC behavior tree system, state persistence, and a physics engine. Each simulation manager owns a distinct slice of world dynamics so they can run independently or be composed into a full integrated simulation.

• Economy: EconomyManager — markets, resources, trade routes, currencies, guilds
• Politics: PoliticsManager — factions, leaders, alliances, conflicts, treaties, elections
• Culture: CultureManager — trait evolution, cultural contacts, innovations, subcultures
• Scenario: ScenarioManager — configurable scenario generation with timelines and templates
• NPC Behavior: Full behavior tree (leaf, composite, decorator nodes) with BehaviorTreeBuilder and common patterns
• State Persistence: SimulationStateStore with in-memory, PostgreSQL, and Redis backends
• Physics: PhysicsEngine with rigid bodies, colliders, constraints, force fields, raycasting, and presets

Tags: scope:hathor, layer:domain

@hathor/llm-npc#

Comprehensive LLM-powered NPC system. The library is organized into four modules — brain, dialogue, behavior, and platform integrations — so that the cognitive model (personality, emotion, memory) is decoupled from the specific AI platform used to generate speech.

Brain Module:

• PersonalityManager — Big Five + Enneagram type system + BDI model
• EmotionalStateManager — Real-time emotional state tracking
• MemorySystem — Short-term and long-term memory with consolidation
• WorldAwarenessManager — Spatial awareness and world knowledge

Dialogue Module:

• DialogueGenerator — Real-time dialogue from personality, emotion, context
• SafetyFilter — Content safety and lore consistency guardrails

Behavior Module:

• BehaviorController — Goal-driven scheduling with GOAP and HTN
• NPCConversationManager — Multi-NPC autonomous conversation management

Platform Integrations:

• LLMClient (generic OpenAI-compatible)
• NVIDIAAceClient (NVIDIA ACE with blendshapes, Riva, Audio2Face)
• InworldClient (sessions, triggers, knowledge, goals)
• ConvaiClient (sessions, actions, face data, function calls)

Provider Chain: ProviderChain with circuit breakers and automatic failover across the above platforms.

Tags: scope:hathor, layer:domain, type:lib

@hathor/validation#

Four-layer lore validation engine. Each validator targets a specific class of consistency problem; createLoreValidator() composes all four into a single combined pass.

Combined: createLoreValidator() runs all four checks and produces a unified LoreValidationResult.

Tags: scope:hathor, layer:domain

@hathor/theory#

Three integrated theory subsystems that bring academic frameworks for game design and storytelling into the authoring pipeline.

• MDA Framework: MDAManager — mechanics, dynamics, aesthetics analysis with feedback loops, flow analysis, and experience evaluation
• Narrative Theory: NarrativeManager — fabula/syuzhet, pacing, beat sheets, character arc templates, structure templates (Hero's Journey, Three Act, Five Act, Kishōtenketsu)
• Cinematography: CinematographyManager — shot design, composition, lighting, color, rhythm, continuity

Tags: scope:hathor, layer:domain

@hathor/pre-production#

Pre-production tools that help a team move from a written world document into a production-ready plan.

• Scriptwriting: Chronicle parser with era/event headings, speaker attribution, diagnostic reporting; narrative structure analysis with template adherence scoring
• Storyboard: StoryboardManager for visual planning with frames, sequences, layers, camera specs, transitions, character placement, exports, timeline linking
• Planning: a ProjectManager for worldbuilding project management (phases, milestones, tasks, dependencies, built-in checklists, project health) plus a large library of virtual-production / on-set systems (~240 *-system.ts and drone-* modules: drone choreography and safety, virtual sets, LED-wall ICVFX, relighting, motion capture, switching, color, and continuity), each with a matching test file

Tags: scope:hathor, layer:domain

@hathor/lore-compiler#

Compiles narrative content into engine-ready and film-ready artifacts. This library is the bridge between the world-as-data (stored in Hathor) and world-as-executable-artifact (consumed by game engines and Bellona).

Tags: scope:hathor, layer:domain

@hathor/sophia-integration#

Direct integration layer between Hathor and the Sophia research domain. Sophia owns a large corpus of indexed documents and a knowledge graph; this library gives Hathor access to that corpus so that world lore can be grounded in real-world research rather than invented wholesale.

• CitationService — Link world lore to research sources via Sophia search
• ResearchGroundingService — Generate world content grounded in researched knowledge
• LoreValidationService — Fact-check world lore against Sophia's research corpus

Tags: scope:hathor, layer:domain

Façade libraries (@hathor/characters, @hathor/world, @hathor/timeline, @hathor/quests)#

Four thin façade libraries adapt Hathor domain types for cross-domain (CGI / production) consumption. Each façade exports metadata, a packet builder, a validator, and a serializer. The façade boundary exists because CGI pipelines (e.g., a VFX pipeline consuming character definitions) need a stable, minimal interface — not the full richness of the internal domain model.

• @hathor/characters — CGI character-definition import facade; maps Character records into a CGI character packet (appearance, costume designs, visual references). Depends on @hathor/domain-models and @hathor/pre-production.
• @hathor/world — CGI scene-definition import facade. Depends on @hathor/domain-models.
• @hathor/timeline — narrative scene-order facade (story-order vs. shoot-order reconciliation, causal-dependency checking, world-state continuity). Depends on @hathor/domain-models.
• @hathor/quests — scene-dependency / story-arc capture facade. Depends on @hathor/narrative.

@hathor/event-handlers#

Handles incoming events from Sophia, Isis, and Yemaya using @oshun/event-bus. setupHathorEventHandlers initializes all subscriptions with consumer group support, logging, and graceful shutdown.

Tags: scope:hathor, type:lib, layer:integration

@hathor/event-publisher#

Type-safe event publisher for all Hathor domain events. Singleton pattern: getHathorEventPublisher / createHathorEventPublisher.

The following event payload types are published:

• HathorWorldCreatedPayload
• HathorWorldPublishedPayload
• HathorElementAddedPayload
• HathorNarrativeGeneratedPayload
• HathorSimulationStartedPayload
• HathorSimulationCompletedPayload
• HathorWorldValidatedPayload

Tags: scope:hathor, type:lib, layer:integration

@hathor/client#

TypeScript SDK for the Hathor HTTP APIs. Provides WorldResource, NarrativeResource, and SimulationResource with pagination, a comprehensive error hierarchy, branded ID types, and helper functions.

Tags: scope:hathor, layer:clients

4. Data Flow#

The following flows trace a world's lifecycle through the Hathor pipeline.

4.1 World Creation and Editing Flow#

A world begins as an API call from the Workbench or any SDK client. Each entity change produces a new immutable WorldVersion record, and a domain event is published so downstream consumers (such as analytics) can react.

Workbench / API Client
        |
        v
world-api (POST /api/v1/worlds)
        |
        +-- Create World record in PostgreSQL
        +-- Create initial WorldVersion (v1, main branch)
        |
        v
Entity operations (addEntity, updateEntity, removeEntity)
        |
        +-- Update Entity table in PostgreSQL
        +-- Create new WorldVersion (with changes delta)
        |
        v
hathor.element.added event  ─────────────>  Event consumers (analytics)

4.2 Branching and Merge Flow#

The branching model mirrors git: branches diverge from a specific version and can be merged back via a merge request. Conflicts must be resolved individually before the merge can be executed.

world-api POST /branches
        |
        +-- Create Branch record (branchPointVersionId = current)
        |
entity changes on branch
        |
        +-- WorldVersion records linked to Branch
        |
POST /merge-requests
        |
        +-- Diff source and target versions
        +-- Identify conflicts (same entity, different changes)
        |
POST /merge-requests/:mrId/conflicts/resolve
        |
        +-- Record resolution per conflict (source / target / custom)
        |
POST /merge-requests/:mrId/merge
        |
        +-- Apply resolved changes
        +-- Create new WorldVersion on target branch
        +-- Set MergeRequest status = MERGED

4.3 Simulation Flow#

Simulation jobs are decoupled from the World API. An external trigger (an API call or a Yemaya event) submits a job to the simulation worker, which processes it asynchronously and publishes a completion event when finished. The separation keeps the World API responsive while long-running simulations run in the background.

API Client / Event (yemaya.build.requested)
        |
        v
simulation-worker POST /api/jobs
        |
        +-- Create SimulationRun record (PENDING)
        +-- Enqueue job in worker pool
        |
        v
Worker picks up job
        |
        +-- Load world state from PostgreSQL
        +-- Run simulation ticks:
        |       Economy: EconomyManager
        |       Politics: PoliticsManager
        |       Culture: CultureManager
        |       Scenario: ScenarioManager
        |
        +-- Emit SimulationEvents per tick
        +-- Save SimulationSnapshot at intervals
        +-- Update progress on SimulationRun
        |
        v
SimulationRun.status = COMPLETED
        |
        v
Publish: hathor.simulation.completed

4.4 Lore Compilation Flow#

When a world is published, both Hathor and Bellona act on the event. Hathor's @hathor/lore-compiler produces compiled intermediate artifacts; Bellona's own integration library then converts those into engine-native project assets.

Publish: hathor.world.published
        |
        v
@hathor/event-handlers (Bellona handles this too)
        |
        v
@hathor/lore-compiler (QuestCompiler, ScreenplayCompiler, BellonaPackageBuilder)
        |
        +-- Compile quests, dialogues, NPCs into engine-native format:
        |       Unreal: Blueprints + DataTables
        |       Unity:  C# ScriptableObjects
        |       Godot:  GDScript + Resources
        |
        v
Bellona package: world data + quest data + dialogue data + manifest
        |
        v
Bellona domain consumes package for engine project generation

5. Key Design Patterns#

5.1 Layered Domain Architecture#

Libraries are organized in strict layers (data → domain → integration → client) to enforce unidirectional dependencies. Domain libraries do not import from integration or client layers. This means the pure world model (@hathor/domain-models, @hathor/narrative, @hathor/simulation) can be tested without any HTTP, database, or event-bus dependencies in scope.

5.2 Factory Functions Throughout#

All managers and services expose factory functions (createEconomyManager, createPoliticsManager, createLoreValidator, etc.) rather than requiring direct instantiation. This enables dependency injection and clean testing without having to subclass or monkey-patch anything.

5.3 JSON Properties for Polymorphic Entities#

The Entity table uses a properties: Json field for type-specific data rather than per-type tables. This enables the world model to accommodate all 10 entity types (and custom types) without schema migrations when new types are added. Type-specific validation is handled in @hathor/domain-models validators rather than at the database level.

5.4 Git-Like Version Model#

The versioning model mirrors git: WorldVersion records form a parent-child chain (commits), Branch records track named development lines, and MergeRequest tracks the review and merge workflow. isCurrent on WorldVersion marks the HEAD of each branch. This model makes it safe to experiment with alternative world timelines (e.g. "what if the empire never fell?") without losing the main world state.

5.5 Behavior Tree Composability#

The NPC behavior tree system follows the standard behavior tree pattern with leaf (Action, Condition), composite (Sequence, Selector, Parallel), and decorator (Inverter, Repeater, Timeout, etc.) nodes. The BehaviorTreeBuilder provides a fluent API for constructing trees without manual node wiring. Trees are serializable so their execution state can be saved and restored across simulation ticks.

5.6 Provider Chain with Circuit Breaker#

The @hathor/llm-npc ProviderChain implements the circuit breaker pattern across multiple AI platform clients. When a provider fails a configurable number of times in a row, its circuit opens and traffic fails over to the next healthy provider automatically. This makes the NPC system resilient to third-party AI platform outages.

6. Technology Stack#

Technology Rationale#

• Hono chosen for the World API for its lightweight footprint, native Zod OpenAPI integration, and TypeScript-first design
• JSON properties field on Entity enables flexible entity models without schema migrations as new world element types are introduced
• Redis for simulation state caching enables low-latency state access across simulation ticks without hitting PostgreSQL on every tick
• nx:run-commands used for libraries (@hathor/llm-npc, @hathor/client) that require custom build steps beyond standard TypeScript compilation

7. Project Structure#

The Hathor file tree below maps each directory to its library or application.

apps/hathor/
  world-api/             # World state, versioning, branching, query engine (Hono, 3001)
  narrative-api/         # Story graphs, quests, dialogues, validation (Hono, 3002)
  simulation-worker/     # Background world simulation jobs (Hono, 3004)
  workbench/             # React SPA for visual worldbuilding
  studio-web/            # V2 fighting-game narrative content map
  svc-veilborn-core/     # Veilborn Chronicles core game engine (Fastify)
  svc-veilborn-strategy/ # Veilborn "The Veil War" strategy game (Fastify)

libs/hathor/
  client/              # TypeScript SDK
  database/            # Prisma schema and generated client
  domain-models/       # Engine-agnostic world type system
  event-handlers/      # Cross-domain event subscriptions
  event-publisher/     # Outgoing event publishing
  llm-npc/             # LLM-powered NPC intelligence
  narrative/           # Quest, dialogue, story graph, journal, export
  pre-production/      # Chronicle parsing, storyboarding, project mgmt, virtual production
  simulation/          # Economy, politics, culture, scenario, NPC behavior, physics
  sophia-integration/  # Research grounding via Sophia
  theory/              # MDA framework, narrative theory, cinematography
  validation/          # Lore consistency validation
  lore-compiler/       # Engine and film artifact compilation
  characters/          # CGI character-definition import facade
  world/               # CGI scene-definition import facade
  timeline/            # Narrative scene-order facade
  quests/              # Scene-dependency / story-arc capture facade

8. Cross-Domain Dependencies#

Hathor both consumes from and publishes to other Oshun domains. Understanding these boundaries matters because they determine which side owns a given piece of data and which side must wait for an event.

Why These Boundaries Exist#

• Sophia → Hathor: Sophia owns the research corpus and knowledge graph. Hathor cannot replicate that data, so it calls Sophia synchronously for citation lookups and subscribes to document-ingestion events so new research can flow into world lore automatically.
• Isis → Hathor: Isis owns asset generation (AI-generated images, concept art). When Isis produces an asset, Hathor links it to the corresponding world entity — Hathor does not generate assets itself.
• Yemaya → Hathor: Yemaya is the creative studio management domain. When a new project or character is created there, Hathor needs to know so it can create or update the corresponding world record.
• Hathor → Bellona: Bellona owns game engine project generation. Hathor publishes a world.published event with compiled artifacts; Bellona consumes it to build engine-native project assets. The boundary is at the compiled artifact — Hathor does not know about Bellona's engine project format.

Upstream Events Consumed#

Downstream Events Produced#

Sophia Direct Integration#

@hathor/sophia-integration calls Sophia's search API directly (not via events) for citation search, lore fact-checking, and research grounding operations that require synchronous responses. The event subscription handles asynchronous document ingestion; the direct API call handles interactive "check this fact now" workflows.

Shared Oshun Libraries Used#