Architecture

LoreOS is built as a managed Character OS: a set of ledgers, state compilers, generation workflows, delivery adapters, and observability surfaces. The public API stays simple, but the runtime behind it is stateful.

Developer app
  |
  | 1. Create characters, upload visual assets, start sessions, send messages
  v
LoreOS REST API
  |
  | 2. Auth, app isolation, validation, metering reservation
  v
Async runtime orchestration
  |
  | 3. Reply, image, delivery, Story Room, and scheduled jobs
  v
Character state projection
  |
  | 4. Compile persona, memory, character facts, relationship state,
  |    world context, visual state, and safe Story Room context
  v
Generation and delivery workflows
  |
  | 5. Produce replies or images, deliver through events or channels
  v
Session events, traces, usage, and observability

Runtime layers

1. App and tenancy

Every API key resolves to one app. Characters, sessions, external users, usage, and delivery channels are scoped to that app.

2. Character authoring

A character starts with a slug and display name, then gains persona, voice, long-term character direction, visual identity, and readiness signals. Use character readiness and runtime preview before launching.

3. Session runtime

When you send a message, LoreOS starts an async run. The response is not returned inline: you read it from session events or stream it over SSE.

4. State projection

The runtime compiles a current character state from ledgers such as character facts, memory, relationship state, user agency, visual state, Story Room outputs, and recent events. This compiled state is what downstream generation uses.

5. Story and life simulation

Story Room can create weekly soft arcs, daily-life packages, scene cards, proactive-hook candidates, and safe runtime context. The chat actor only consumes that safe context.

State wiring

The runtime is wired around source-of-truth ledgers and a compiled read model:

Authoring data
  persona, voice, character direction, visual identity
Session data
  messages, runs, events, relationship state, user-specific memory
World data
  character facts, world context, routines, supporting cast, obligations
Story Room data
  daily-life packages, scene cards, safe runtime context, proactive-hook candidates
Visual data
  identity images, assets, inventory, probes, image readiness
        |
        v
Character state projection
        |
        +--> Text reply runtime
        +--> Image runtime
        +--> Delivery channels
        +--> Observability and traces

The projection is a compiled view for execution. It is not a second source of truth.

6. Visual pipeline

Visual assets and identity images provide the basis for image readiness, inventory generation, image probes, and character image delivery.

7. Delivery and observability

Delivery adapters project runtime output to your app or to managed channels such as Telegram. Usage, runs, traces, and health views make the runtime inspectable.

Design principle

LoreOS treats the database as the source of truth. Models propose candidates, but code validates visibility, ownership, lifecycle, and commit boundaries.

That is why the API stays predictable even though the runtime uses model-generated behavior internally.