> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.loreos.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.loreos.app/_mcp/server.

# 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.

```text
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:

```text
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.