# artem-xox/tavern architecture

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

- Interactive diagram: https://gitdiagram.com/artem-xox/tavern
- Repository: https://github.com/artem-xox/tavern

## Overview

The Last Inn is a browser sandbox game simulating an evening at a border inn with autonomous guests. The main workflow is to open a scenario, run a live world in which guests arrive, choose activities, navigate and interact, and display the evolving evening in the browser. Guests make local or model-assisted choices; conversation turns and intentions add social and reflective behavior. The graph preserves the documented gameplay branches, but several links are based on README descriptions because their implementation files were not sampled.

Main entry points: [`backend/tavern/server/runtime.py`](https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/runtime.py) (Live session runtime), [`backend/tavern/hall/state.py`](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/state.py) (Authoritative world), [`backend/tavern/hall/lifecycle.py`](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/lifecycle.py) (World lifecycle), [`frontend/src/main.ts`](https://github.com/artem-xox/tavern/blob/main/frontend/src/main.ts) (Game interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_browser["Game interface<br/>[main.ts]"]
  node_dashboard["Evening dashboard<br/>[dashboard.ts]"]
  node_renderer["Room renderer<br/>[scene.ts]"]
  node_connection["Server connection<br/>[connection.ts]"]
end

subgraph group_service["Session service"]
  node_api["HTTP API<br/>[api.py]"]
  node_sessions["Session management<br/>[sessions.py]"]
  node_runtime["Live session runtime<br/>[runtime.py]"]
end

subgraph group_world["Inn world"]
  node_scenario["Evening scenario<br/>[scenario.py]"]
  node_worldstate[("Authoritative world<br/>[state.py]")]
  node_lifecycle["World lifecycle<br/>[lifecycle.py]"]
  node_room["Room and furniture<br/>[room.py]"]
  node_routing["Guest navigation<br/>[routes.py]"]
end

subgraph group_guests["Guest behavior"]
  node_activities["Guest activities<br/>[activities.py]"]
  node_queues["Guest queues<br/>[queues.py]"]
  node_hearing["Attention and hearing<br/>[hearing.py]"]
end

subgraph group_social["Social and AI"]
  node_decisions["Guest decisions<br/>[agents.py]"]
  node_intentions["Guest intentions<br/>[intentions.py]"]
  node_scenes["Conversation scenes<br/>[scenes.py]"]
  node_turns["Conversation turns<br/>[turns.py]"]
  node_memory["Events and memories<br/>[memory.py]"]
end

node_player(("Player"))
node_jev{{"Jev model service"}}

node_player -->|"plays"| node_browser
node_browser -->|"renders"| node_dashboard
node_browser -->|"renders"| node_renderer
node_browser -->|"connects"| node_connection
node_connection -.->|"exchanges state"| node_api
node_api -.->|"routes requests"| node_sessions
node_sessions -->|"manages"| node_runtime
node_runtime -->|"opens scenario"| node_scenario
node_runtime -->|"advances"| node_worldstate
node_scenario -->|"creates guests"| node_worldstate
node_lifecycle -->|"updates"| node_worldstate
node_lifecycle -->|"runs actions"| node_activities
node_lifecycle -->|"updates queues"| node_queues
node_lifecycle -->|"updates scenes"| node_scenes
node_routing -->|"finds routes"| node_room
node_runtime -->|"requests choices"| node_decisions
node_runtime -->|"requests intentions"| node_intentions
node_runtime -->|"runs turn writing"| node_turns
node_decisions -.->|"scores options"| node_jev
node_turns -->|"speaks in"| node_scenes
node_activities -->|"records events"| node_memory
node_memory -->|"emits sounds"| node_hearing
node_worldstate -.->|"supplies snapshot"| node_renderer
node_worldstate -.->|"supplies status"| node_dashboard

click node_browser "https://github.com/artem-xox/tavern/blob/main/frontend/src/main.ts"
click node_dashboard "https://github.com/artem-xox/tavern/blob/main/frontend/src/dashboard.ts"
click node_renderer "https://github.com/artem-xox/tavern/blob/main/frontend/src/scene.ts"
click node_connection "https://github.com/artem-xox/tavern/blob/main/frontend/src/connection.ts"
click node_api "https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/api.py"
click node_sessions "https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/sessions.py"
click node_runtime "https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/runtime.py"
click node_scenario "https://github.com/artem-xox/tavern/blob/main/backend/tavern/evening/scenario.py"
click node_worldstate "https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/state.py"
click node_lifecycle "https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/lifecycle.py"
click node_room "https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/room.py"
click node_routing "https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/routes.py"
click node_activities "https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/activities.py"
click node_queues "https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/queues.py"
click node_hearing "https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/hearing.py"
click node_decisions "https://github.com/artem-xox/tavern/blob/main/backend/tavern/mind/agents.py"
click node_intentions "https://github.com/artem-xox/tavern/blob/main/backend/tavern/mind/intentions.py"
click node_scenes "https://github.com/artem-xox/tavern/blob/main/backend/tavern/social/scenes.py"
click node_turns "https://github.com/artem-xox/tavern/blob/main/backend/tavern/social/turns.py"
click node_memory "https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/memory.py"

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_browser,node_dashboard,node_renderer,node_connection toneBlue
class node_api,node_sessions,node_runtime toneAmber
class node_scenario,node_worldstate,node_lifecycle,node_room,node_routing toneMint
class node_activities,node_queues,node_hearing toneRose
class node_decisions,node_intentions,node_scenes,node_turns,node_memory,node_player,node_jev toneIndigo
```

## Components

### Browser client

- [Game interface](https://github.com/artem-xox/tavern/blob/main/frontend/src/main.ts): `frontend/src/main.ts`
- [Evening dashboard](https://github.com/artem-xox/tavern/blob/main/frontend/src/dashboard.ts): `frontend/src/dashboard.ts`
- [Room renderer](https://github.com/artem-xox/tavern/blob/main/frontend/src/scene.ts): `frontend/src/scene.ts`
- [Server connection](https://github.com/artem-xox/tavern/blob/main/frontend/src/connection.ts): `frontend/src/connection.ts`

### Session service

- [HTTP API](https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/api.py): `backend/tavern/server/api.py`
- [Session management](https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/sessions.py): `backend/tavern/server/sessions.py`
- [Live session runtime](https://github.com/artem-xox/tavern/blob/main/backend/tavern/server/runtime.py): `backend/tavern/server/runtime.py`

### Inn world

- [Evening scenario](https://github.com/artem-xox/tavern/blob/main/backend/tavern/evening/scenario.py): `backend/tavern/evening/scenario.py`
- [Authoritative world](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/state.py): `backend/tavern/hall/state.py`
- [World lifecycle](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/lifecycle.py): `backend/tavern/hall/lifecycle.py`
- [Room and furniture](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/room.py): `backend/tavern/hall/room.py`
- [Guest navigation](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/routes.py): `backend/tavern/hall/routes.py`

### Guest behavior

- [Guest activities](https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/activities.py): `backend/tavern/body/activities.py`
- [Guest queues](https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/queues.py): `backend/tavern/body/queues.py`
- [Attention and hearing](https://github.com/artem-xox/tavern/blob/main/backend/tavern/body/hearing.py): `backend/tavern/body/hearing.py`

### Social and AI

- [Guest decisions](https://github.com/artem-xox/tavern/blob/main/backend/tavern/mind/agents.py): `backend/tavern/mind/agents.py`
- [Guest intentions](https://github.com/artem-xox/tavern/blob/main/backend/tavern/mind/intentions.py): `backend/tavern/mind/intentions.py`
- [Conversation scenes](https://github.com/artem-xox/tavern/blob/main/backend/tavern/social/scenes.py): `backend/tavern/social/scenes.py`
- [Conversation turns](https://github.com/artem-xox/tavern/blob/main/backend/tavern/social/turns.py): `backend/tavern/social/turns.py`
- [Events and memories](https://github.com/artem-xox/tavern/blob/main/backend/tavern/hall/memory.py): `backend/tavern/hall/memory.py`

### Other components

- **Player**
- **Jev model service**

## Connections

- Player → Game interface: plays (evidence: `README.md`)
- Game interface → Evening dashboard: renders (evidence: `frontend/src/main.ts`)
- Game interface → Room renderer: renders (evidence: `frontend/src/main.ts`)
- Game interface → Server connection: connects (evidence: `frontend/src/main.ts`)
- Server connection → HTTP API: exchanges state
- HTTP API → Session management: routes requests
- Session management → Live session runtime: manages (evidence: `backend/tavern/server/sessions.py`)
- Live session runtime → Evening scenario: opens scenario (evidence: `backend/tavern/server/runtime.py`)
- Live session runtime → Authoritative world: advances (evidence: `backend/tavern/server/runtime.py`)
- Evening scenario → Authoritative world: creates guests (evidence: `backend/tavern/evening/scenario.py`)
- World lifecycle → Authoritative world: updates (evidence: `backend/tavern/hall/lifecycle.py`)
- World lifecycle → Guest activities: runs actions (evidence: `backend/tavern/hall/lifecycle.py`)
- World lifecycle → Guest queues: updates queues (evidence: `backend/tavern/hall/lifecycle.py`)
- World lifecycle → Conversation scenes: updates scenes (evidence: `backend/tavern/hall/lifecycle.py`)
- Guest navigation → Room and furniture: finds routes (evidence: `backend/tavern/hall/routes.py`)
- Live session runtime → Guest decisions: requests choices (evidence: `backend/tavern/server/runtime.py`)
- Live session runtime → Guest intentions: requests intentions (evidence: `backend/tavern/server/runtime.py`)
- Live session runtime → Conversation turns: runs turn writing (evidence: `backend/tavern/server/runtime.py`)
- Guest decisions → Jev model service: scores options
- Conversation turns → Conversation scenes: speaks in (evidence: `backend/tavern/social/turns.py`)
- Guest activities → Events and memories: records events (evidence: `backend/tavern/body/activities.py`)
- Events and memories → Attention and hearing: emits sounds (evidence: `backend/tavern/hall/memory.py`)
- Authoritative world → Room renderer: supplies snapshot
- Authoritative world → Evening dashboard: supplies status
