# areium/ark-tavern architecture

> Architecture diagram of the GitHub repository areium/ark-tavern, 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/areium/ark-tavern
- Repository: https://github.com/areium/ark-tavern

## Overview

Ark Tavern is a local-first LLM-driven story and game platform. The main workflow is to create or select a save, enter an immersive conversation, and have the backend advance narrative using session context, worldbook material, and an LLM; the session can also hand encounters to a selected combat mode and receive outcomes. The README documents additional content-management and recovery capabilities. Backend and frontend call relationships are based on the supplied excerpts and README; unsampled subsystem wiring is not inferred.

Main entry points: [`frontend/src/hooks/useApi.ts`](https://github.com/areium/ark-tavern/blob/main/frontend/src/hooks/useApi.ts) (API client hook), [`src/SceneManager.py`](https://github.com/areium/ark-tavern/blob/main/src/SceneManager.py) (Scene manager), [`frontend/src/App.tsx`](https://github.com/areium/ark-tavern/blob/main/frontend/src/App.tsx) (Application shell), [`frontend/src/components/WorldBookManager.tsx`](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/WorldBookManager.tsx) (Worldbook workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_session_ui["Session hall"]
  node_chat_ui["Conversation views<br/>[ChatView.tsx]"]
  node_worldbook_ui["Worldbook workbench"]
  node_api_hook["API client hook<br/>[useApi.ts]"]
  node_combat_ui["Combat views<br/>[CombatView.tsx]"]
  node_settings["Configuration UI<br/>[SettingsPanel.tsx]"]
end

subgraph group_story["Sessions and story"]
  node_scene["Scene manager<br/>[SceneManager.py]"]
  node_agent["Character agent<br/>[CharacterAgent.py]"]
  node_session_mgr["Session manager<br/>[session_manager.py]"]
  node_memory[("Story memory<br/>[memory.py]")]
  node_story_graph["Plot graph<br/>[plot_graphs.py]"]
end

subgraph group_content["Content libraries"]
  node_worldbook["Worldbook engine<br/>[world_book.py]"]
  node_worldbook_store[("Worldbook storage")]
  node_characters["Character content<br/>[character_card.py]"]
end

subgraph group_play["Combat modes"]
  node_combat_api["Combat endpoints<br/>[combat.py]"]
  node_combat_engine["Tactical engine<br/>[engine.py]"]
  node_sideview["Sideview battle<br/>[sideview_combat.py]"]
end

subgraph group_services["Backend services"]
  node_session_api["Session endpoints<br/>[sessions.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_llm_manager["LLM routing"]
  node_llm_provider["Model providers<br/>[base.py]"]
end

node_player(("Player"))
node_cloud_model{{"Cloud model API"}}
node_ollama{{"Ollama"}}

node_player -->|"uses"| node_app
node_app -->|"opens"| node_session_ui
node_app -->|"opens"| node_chat_ui
node_app -->|"opens"| node_worldbook_ui
node_app -->|"opens"| node_combat_ui
node_session_ui -->|"requests"| node_api_hook
node_chat_ui -->|"requests"| node_api_hook
node_worldbook_ui -->|"requests"| node_api_hook
node_api_hook -->|"calls"| node_session_api
node_api_hook -->|"calls"| node_chat_api
node_session_api -->|"manages saves"| node_session_mgr
node_chat_api -->|"routes chat"| node_scene
node_scene -->|"routes dialogue"| node_agent
node_scene -->|"resolves context"| node_worldbook
node_scene -->|"requests generation"| node_llm_manager
node_scene -.->|"uses summaries"| node_memory
node_scene -.->|"uses plot beats"| node_story_graph
node_worldbook -->|"reads entries"| node_worldbook_store
node_worldbook_ui -->|"manages books"| node_worldbook_store
node_llm_manager -->|"creates clients"| node_llm_provider
node_llm_provider -.->|"sends prompts"| node_cloud_model
node_llm_provider -.->|"sends prompts"| node_ollama
node_combat_ui -->|"requests"| node_api_hook
node_api_hook -->|"calls"| node_combat_api
node_combat_api -->|"runs turns"| node_combat_engine
node_combat_api -.->|"dispatches mode"| node_sideview
node_settings -->|"updates config"| node_api_hook
node_api_hook -->|"configures models"| node_llm_manager
node_characters -.->|"supplies roster"| node_session_mgr

click node_app "https://github.com/areium/ark-tavern/blob/main/frontend/src/App.tsx"
click node_session_ui "https://github.com/areium/ark-tavern/blob/main/frontend/src/components/session/SessionManagerView.tsx"
click node_chat_ui "https://github.com/areium/ark-tavern/blob/main/frontend/src/components/ChatView.tsx"
click node_worldbook_ui "https://github.com/areium/ark-tavern/blob/main/frontend/src/components/WorldBookManager.tsx"
click node_api_hook "https://github.com/areium/ark-tavern/blob/main/frontend/src/hooks/useApi.ts"
click node_session_api "https://github.com/areium/ark-tavern/blob/main/src/blueprints/sessions.py"
click node_chat_api "https://github.com/areium/ark-tavern/blob/main/src/blueprints/chat.py"
click node_scene "https://github.com/areium/ark-tavern/blob/main/src/SceneManager.py"
click node_agent "https://github.com/areium/ark-tavern/blob/main/src/CharacterAgent.py"
click node_session_mgr "https://github.com/areium/ark-tavern/blob/main/src/session_manager.py"
click node_memory "https://github.com/areium/ark-tavern/blob/main/src/memory.py"
click node_story_graph "https://github.com/areium/ark-tavern/blob/main/src/plot_graphs.py"
click node_worldbook "https://github.com/areium/ark-tavern/blob/main/src/world_book.py"
click node_worldbook_store "https://github.com/areium/ark-tavern/blob/main/src/worldbook_folder_store.py"
click node_characters "https://github.com/areium/ark-tavern/blob/main/src/character_card.py"
click node_llm_manager "https://github.com/areium/ark-tavern/blob/main/src/llm_backend_manager.py"
click node_llm_provider "https://github.com/areium/ark-tavern/blob/main/src/providers/base.py"
click node_combat_api "https://github.com/areium/ark-tavern/blob/main/src/blueprints/combat.py"
click node_combat_engine "https://github.com/areium/ark-tavern/blob/main/src/combat_engine/engine.py"
click node_sideview "https://github.com/areium/ark-tavern/blob/main/src/sideview_combat.py"
click node_combat_ui "https://github.com/areium/ark-tavern/blob/main/frontend/src/components/combat/CombatView.tsx"
click node_settings "https://github.com/areium/ark-tavern/blob/main/frontend/src/components/SettingsPanel.tsx"

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_app,node_session_ui,node_chat_ui,node_worldbook_ui,node_api_hook,node_combat_ui,node_settings toneBlue
class node_scene,node_agent,node_session_mgr,node_memory,node_story_graph toneAmber
class node_worldbook,node_worldbook_store,node_characters,node_cloud_model toneMint
class node_combat_api,node_combat_engine,node_sideview toneRose
class node_session_api,node_chat_api,node_llm_manager,node_llm_provider,node_player,node_ollama toneIndigo
```

## Components

### Client experience

- [Application shell](https://github.com/areium/ark-tavern/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session hall](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/session/SessionManagerView.tsx): `frontend/src/components/session/SessionManagerView.tsx`
- [Conversation views](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/ChatView.tsx): `frontend/src/components/ChatView.tsx`
- [Worldbook workbench](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/WorldBookManager.tsx): `frontend/src/components/WorldBookManager.tsx`
- [API client hook](https://github.com/areium/ark-tavern/blob/main/frontend/src/hooks/useApi.ts): `frontend/src/hooks/useApi.ts`
- [Combat views](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/combat/CombatView.tsx): `frontend/src/components/combat/CombatView.tsx`
- [Configuration UI](https://github.com/areium/ark-tavern/blob/main/frontend/src/components/SettingsPanel.tsx): `frontend/src/components/SettingsPanel.tsx`

### Sessions and story

- [Scene manager](https://github.com/areium/ark-tavern/blob/main/src/SceneManager.py): `src/SceneManager.py`
- [Character agent](https://github.com/areium/ark-tavern/blob/main/src/CharacterAgent.py): `src/CharacterAgent.py`
- [Session manager](https://github.com/areium/ark-tavern/blob/main/src/session_manager.py): `src/session_manager.py`
- [Story memory](https://github.com/areium/ark-tavern/blob/main/src/memory.py): `src/memory.py`
- [Plot graph](https://github.com/areium/ark-tavern/blob/main/src/plot_graphs.py): `src/plot_graphs.py`

### Content libraries

- [Worldbook engine](https://github.com/areium/ark-tavern/blob/main/src/world_book.py): `src/world_book.py`
- [Worldbook storage](https://github.com/areium/ark-tavern/blob/main/src/worldbook_folder_store.py): `src/worldbook_folder_store.py`
- [Character content](https://github.com/areium/ark-tavern/blob/main/src/character_card.py): `src/character_card.py`

### Combat modes

- [Combat endpoints](https://github.com/areium/ark-tavern/blob/main/src/blueprints/combat.py): `src/blueprints/combat.py`
- [Tactical engine](https://github.com/areium/ark-tavern/blob/main/src/combat_engine/engine.py): `src/combat_engine/engine.py`
- [Sideview battle](https://github.com/areium/ark-tavern/blob/main/src/sideview_combat.py): `src/sideview_combat.py`

### Backend services

- [Session endpoints](https://github.com/areium/ark-tavern/blob/main/src/blueprints/sessions.py): `src/blueprints/sessions.py`
- [Chat endpoints](https://github.com/areium/ark-tavern/blob/main/src/blueprints/chat.py): `src/blueprints/chat.py`
- [LLM routing](https://github.com/areium/ark-tavern/blob/main/src/llm_backend_manager.py): `src/llm_backend_manager.py`
- [Model providers](https://github.com/areium/ark-tavern/blob/main/src/providers/base.py): `src/providers/base.py`

### Other components

- **Player**
- **Cloud model API**
- **Ollama**

## Connections

- Player → Application shell: uses
- Application shell → Session hall: opens
- Application shell → Conversation views: opens
- Application shell → Worldbook workbench: opens
- Application shell → Combat views: opens
- Session hall → API client hook: requests
- Conversation views → API client hook: requests
- Worldbook workbench → API client hook: requests
- API client hook → Session endpoints: calls
- API client hook → Chat endpoints: calls
- Session endpoints → Session manager: manages saves
- Chat endpoints → Scene manager: routes chat
- Scene manager → Character agent: routes dialogue
- Scene manager → Worldbook engine: resolves context
- Scene manager → LLM routing: requests generation
- Scene manager → Story memory: uses summaries
- Scene manager → Plot graph: uses plot beats
- Worldbook engine → Worldbook storage: reads entries
- Worldbook workbench → Worldbook storage: manages books
- LLM routing → Model providers: creates clients
- Model providers → Cloud model API: sends prompts
- Model providers → Ollama: sends prompts
- Combat views → API client hook: requests
- API client hook → Combat endpoints: calls
- Combat endpoints → Tactical engine: runs turns
- Combat endpoints → Sideview battle: dispatches mode
- Configuration UI → API client hook: updates config
- API client hook → LLM routing: configures models
- Character content → Session manager: supplies roster