# sortedcord/omnia architecture

> Architecture diagram of the GitHub repository sortedcord/omnia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sortedcord/omnia
- Repository: https://github.com/sortedcord/omnia

## Overview

Omnia is a framework and GUI for multi-agent narrative simulations. A user configures providers, selects or creates a scenario, and runs or interacts with a simulation; the runtime coordinates character turns, validates proposed actions against structured world state, applies state changes, and retains session and character memory. The README also describes autonomous play, player control of any entity, per-character knowledge, deterministic time, and model selection per task. Some subsystem links reflect documented capabilities; unsampled implementation details are not inferred.

Main entry points: [`packages/runtime/src/turn-executor.ts`](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/turn-executor.ts) (Turn execution), [`packages/runtime/src/runtime-service.ts`](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/runtime-service.ts) (Session orchestration), [`apps/gui/src/components`](https://github.com/sortedcord/omnia/tree/master/apps/gui/src/components) (GUI views), [`apps/gui/src/app/actions.ts`](https://github.com/sortedcord/omnia/blob/master/apps/gui/src/app/actions.ts) (Server actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["GUI Experience"]
  node_gui["GUI views"]
  node_gui_actions["Server actions<br/>[actions.ts]"]
  node_gui_sim["Simulation client<br/>[index.ts]"]
  node_provider_config["Provider settings"]
end

subgraph group_runtime["Simulation Runtime"]
  node_runtime_service["Session orchestration<br/>[runtime-service.ts]"]
  node_turn["Turn execution<br/>[turn-executor.ts]"]
  node_session_store[("Session persistence")]
  node_session_db[("Simulation database<br/>[types.ts]")]
end

subgraph group_domain["World and Agency"]
  node_world["World state<br/>[world.ts]"]
  node_entity["Entities and attributes<br/>[entity.ts]"]
  node_repository[("World repository<br/>[repository.ts]")]
  node_actor["Character behavior<br/>[actor.ts]"]
  node_intent["Intent decoding<br/>[intent-decoder.ts]"]
  node_architect["Action validation<br/>[architect.ts]"]
end

subgraph group_models["Models and Memory"]
  node_memory["Character memory"]
  node_llm["Model routing"]
  node_providers["LLM providers"]
end

subgraph group_contracts["Scenario and API"]
  node_scenario["Scenario loading"]
  node_api_contracts["API schemas"]
end

node_user(("Player / operator"))

node_user -->|"operates"| node_gui
node_gui -->|"submits actions"| node_gui_actions
node_gui_actions -->|"requests simulation"| node_gui_sim
node_gui -->|"configures models"| node_provider_config
node_gui_actions -->|"controls sessions"| node_runtime_service
node_runtime_service -->|"loads scenario"| node_scenario
node_runtime_service -->|"advances turns"| node_turn
node_turn -->|"generates behavior"| node_actor
node_turn -->|"decodes proposals"| node_intent
node_turn -->|"validates intent"| node_architect
node_architect -->|"checks world state"| node_world
node_architect -->|"requests judgment"| node_llm
node_turn -->|"reads and applies state"| node_repository
node_repository -->|"stores world"| node_session_db
node_runtime_service -->|"saves session"| node_session_store
node_session_store -->|"reads and writes session"| node_session_db
node_turn -->|"uses character memory"| node_memory
node_runtime_service -->|"routes task models"| node_llm
node_llm -->|"dispatches generation"| node_providers
node_provider_config -->|"sets provider mappings"| node_runtime_service
node_gui_sim -->|"validates API data"| node_api_contracts

click node_gui "https://github.com/sortedcord/omnia/tree/master/apps/gui/src/components"
click node_gui_actions "https://github.com/sortedcord/omnia/blob/master/apps/gui/src/app/actions.ts"
click node_gui_sim "https://github.com/sortedcord/omnia/blob/master/apps/gui/src/lib/simulation/index.ts"
click node_provider_config "https://github.com/sortedcord/omnia/tree/master/apps/gui/src/components/config"
click node_scenario "https://github.com/sortedcord/omnia/tree/master/packages/scenario/src"
click node_runtime_service "https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/runtime-service.ts"
click node_turn "https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/turn-executor.ts"
click node_session_store "https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/persistence/sqlite-session-store.ts"
click node_session_db "https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/persistence/types.ts"
click node_world "https://github.com/sortedcord/omnia/blob/master/packages/core/src/world.ts"
click node_entity "https://github.com/sortedcord/omnia/blob/master/packages/core/src/entity.ts"
click node_repository "https://github.com/sortedcord/omnia/blob/master/packages/core/src/repository.ts"
click node_actor "https://github.com/sortedcord/omnia/blob/master/packages/actor/src/actor.ts"
click node_intent "https://github.com/sortedcord/omnia/blob/master/packages/intent/src/intent-decoder.ts"
click node_architect "https://github.com/sortedcord/omnia/blob/master/packages/architect/src/architect.ts"
click node_memory "https://github.com/sortedcord/omnia/tree/master/packages/memory/src"
click node_llm "https://github.com/sortedcord/omnia/tree/master/packages/llm/src"
click node_providers "https://github.com/sortedcord/omnia/tree/master/packages/llm/src/providers"
click node_api_contracts "https://github.com/sortedcord/omnia/tree/master/packages/api-contracts/src/v1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_gui_actions,node_gui_sim,node_provider_config toneBlue
class node_runtime_service,node_turn,node_session_store,node_session_db toneAmber
class node_world,node_entity,node_repository,node_actor,node_intent,node_architect toneMint
class node_memory,node_llm,node_providers toneRose
class node_scenario,node_api_contracts,node_user toneIndigo
```

## Components

### GUI Experience

- [GUI views](https://github.com/sortedcord/omnia/tree/master/apps/gui/src/components): `apps/gui/src/components`
- [Server actions](https://github.com/sortedcord/omnia/blob/master/apps/gui/src/app/actions.ts): `apps/gui/src/app/actions.ts`
- [Simulation client](https://github.com/sortedcord/omnia/blob/master/apps/gui/src/lib/simulation/index.ts): `apps/gui/src/lib/simulation/index.ts`
- [Provider settings](https://github.com/sortedcord/omnia/tree/master/apps/gui/src/components/config): `apps/gui/src/components/config`

### Simulation Runtime

- [Session orchestration](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/runtime-service.ts): `packages/runtime/src/runtime-service.ts`
- [Turn execution](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/turn-executor.ts): `packages/runtime/src/turn-executor.ts`
- [Session persistence](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/persistence/sqlite-session-store.ts): `packages/runtime/src/persistence/sqlite-session-store.ts`
- [Simulation database](https://github.com/sortedcord/omnia/blob/master/packages/runtime/src/persistence/types.ts): `packages/runtime/src/persistence/types.ts`

### World and Agency

- [World state](https://github.com/sortedcord/omnia/blob/master/packages/core/src/world.ts): `packages/core/src/world.ts`
- [Entities and attributes](https://github.com/sortedcord/omnia/blob/master/packages/core/src/entity.ts): `packages/core/src/entity.ts`
- [World repository](https://github.com/sortedcord/omnia/blob/master/packages/core/src/repository.ts): `packages/core/src/repository.ts`
- [Character behavior](https://github.com/sortedcord/omnia/blob/master/packages/actor/src/actor.ts): `packages/actor/src/actor.ts`
- [Intent decoding](https://github.com/sortedcord/omnia/blob/master/packages/intent/src/intent-decoder.ts): `packages/intent/src/intent-decoder.ts`
- [Action validation](https://github.com/sortedcord/omnia/blob/master/packages/architect/src/architect.ts): `packages/architect/src/architect.ts`

### Models and Memory

- [Character memory](https://github.com/sortedcord/omnia/tree/master/packages/memory/src): `packages/memory/src`
- [Model routing](https://github.com/sortedcord/omnia/tree/master/packages/llm/src): `packages/llm/src`
- [LLM providers](https://github.com/sortedcord/omnia/tree/master/packages/llm/src/providers): `packages/llm/src/providers`

### Scenario and API

- [Scenario loading](https://github.com/sortedcord/omnia/tree/master/packages/scenario/src): `packages/scenario/src`
- [API schemas](https://github.com/sortedcord/omnia/tree/master/packages/api-contracts/src/v1): `packages/api-contracts/src/v1`

### Other components

- **Player / operator**

## Connections

- Player / operator → GUI views: operates
- GUI views → Server actions: submits actions
- Server actions → Simulation client: requests simulation
- GUI views → Provider settings: configures models
- Server actions → Session orchestration: controls sessions
- Session orchestration → Scenario loading: loads scenario
- Session orchestration → Turn execution: advances turns
- Turn execution → Character behavior: generates behavior
- Turn execution → Intent decoding: decodes proposals
- Turn execution → Action validation: validates intent
- Action validation → World state: checks world state
- Action validation → Model routing: requests judgment
- Turn execution → World repository: reads and applies state
- World repository → Simulation database: stores world
- Session orchestration → Session persistence: saves session
- Session persistence → Simulation database: reads and writes session
- Turn execution → Character memory: uses character memory
- Session orchestration → Model routing: routes task models
- Model routing → LLM providers: dispatches generation
- Provider settings → Session orchestration: sets provider mappings
- Simulation client → API schemas: validates API data