# alienet1109/bookworld architecture

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

## Overview

BookWorld turns a configured fictional world into a scene-based, multi-agent story that users can monitor and control in the web interface. Novel-data extraction and character-card conversion are separate preparation routes that create inputs for simulations. The graph follows the documented workflow and the sampled server, history, embedding, database, and frontend code; some internal agent-to-agent and persistence wiring is not shown in the excerpts, so uncertain links are omitted.

Main entry points: [`frontend/js/message.js`](https://github.com/alienet1109/bookworld/blob/main/frontend/js/message.js) (Story interface), [`modules/main_role_agent.py`](https://github.com/alienet1109/bookworld/blob/main/modules/main_role_agent.py) (Character agents), [`modules/llm`](https://github.com/alienet1109/bookworld/tree/main/modules/llm) (LLM adapters), [`BookWorld.py`](https://github.com/alienet1109/bookworld/blob/main/BookWorld.py) (Simulation controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_web_ui["Story interface<br/>[message.js]"]
  node_map_panel["World map<br/>[map-panel.js]"]
  node_profile_panel["Character profiles<br/>[profile-panel.js]"]
  node_scene_panel["Scene controls<br/>[scene-panel.js]"]
  node_server["WebSocket server<br/>[server.py]"]
end

subgraph group_simulation["Story simulation"]
  node_bookworld["Simulation controller<br/>[BookWorld.py]"]
  node_world_agent["World agent<br/>[world_agent.py]"]
  node_role_agents["Character agents<br/>[main_role_agent.py]"]
  node_eval_agent["Story evaluation<br/>[eval_agent.py]"]
  node_role_prompts["Character prompts"]
  node_world_prompts["World prompts"]
  node_llm_adapters["LLM adapters"]
end

subgraph group_agent_state["Agent state"]
  node_history["Simulation history<br/>[history_manager.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_vector_store[("ChromaDB<br/>[ChromaDB.py]")]
  node_embedding["Embedding models<br/>[embedding.py]"]
end

subgraph group_preparation["World preparation"]
  node_novel_extract["Novel extraction<br/>[extract_data.py]"]
  node_settings_extract["Setting extraction"]
  node_card_converter["Card conversion"]
end

node_user(("User"))

node_user -->|"controls"| node_web_ui
node_web_ui -->|"WebSocket messages"| node_server
node_server -->|"story and status"| node_web_ui
node_server -->|"controls simulation"| node_bookworld
node_bookworld -->|"story and state"| node_server
node_bookworld -->|"orchestrates world"| node_world_agent
node_world_agent -->|"coordinates characters"| node_role_agents
node_role_agents -->|"uses prompts"| node_role_prompts
node_world_agent -->|"uses prompts"| node_world_prompts
node_role_agents -->|"generates dialogue"| node_llm_adapters
node_world_agent -->|"generates world"| node_llm_adapters
node_eval_agent -->|"requests evaluation"| node_llm_adapters
node_bookworld -->|"records progression"| node_history
node_role_agents -->|"updates memories"| node_memory
node_memory -->|"stores and retrieves"| node_vector_store
node_vector_store -->|"embeds text"| node_embedding
node_novel_extract -.->|"extracts story data"| node_llm_adapters
node_settings_extract -.->|"extracts settings"| node_llm_adapters
node_card_converter -.->|"prepares role data"| node_role_agents
node_web_ui -->|"shows map"| node_map_panel
node_web_ui -->|"shows characters"| node_profile_panel
node_web_ui -->|"selects scenes"| node_scene_panel

click node_web_ui "https://github.com/alienet1109/bookworld/blob/main/frontend/js/message.js"
click node_map_panel "https://github.com/alienet1109/bookworld/blob/main/frontend/js/left-section/map-panel.js"
click node_profile_panel "https://github.com/alienet1109/bookworld/blob/main/frontend/js/left-section/profile-panel.js"
click node_scene_panel "https://github.com/alienet1109/bookworld/blob/main/frontend/js/right-section/scene-panel.js"
click node_server "https://github.com/alienet1109/bookworld/blob/main/server.py"
click node_bookworld "https://github.com/alienet1109/bookworld/blob/main/BookWorld.py"
click node_world_agent "https://github.com/alienet1109/bookworld/blob/main/modules/world_agent.py"
click node_role_agents "https://github.com/alienet1109/bookworld/blob/main/modules/main_role_agent.py"
click node_eval_agent "https://github.com/alienet1109/bookworld/blob/main/modules/eval_agent.py"
click node_role_prompts "https://github.com/alienet1109/bookworld/blob/main/modules/prompt/role_agent_prompt_en.py"
click node_world_prompts "https://github.com/alienet1109/bookworld/blob/main/modules/prompt/world_agent_prompt_en.py"
click node_history "https://github.com/alienet1109/bookworld/blob/main/modules/history_manager.py"
click node_memory "https://github.com/alienet1109/bookworld/blob/main/modules/memory.py"
click node_vector_store "https://github.com/alienet1109/bookworld/blob/main/modules/db/ChromaDB.py"
click node_embedding "https://github.com/alienet1109/bookworld/blob/main/modules/embedding.py"
click node_llm_adapters "https://github.com/alienet1109/bookworld/tree/main/modules/llm"
click node_novel_extract "https://github.com/alienet1109/bookworld/blob/main/extract_data/extract_data.py"
click node_settings_extract "https://github.com/alienet1109/bookworld/blob/main/extract_data/extract_settings.py"
click node_card_converter "https://github.com/alienet1109/bookworld/blob/main/convert_sillytavern_cards_to_data.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_web_ui,node_map_panel,node_profile_panel,node_scene_panel,node_server,node_user toneBlue
class node_bookworld,node_world_agent,node_role_agents,node_eval_agent,node_role_prompts,node_world_prompts,node_llm_adapters toneAmber
class node_history,node_memory,node_vector_store,node_embedding toneMint
class node_novel_extract,node_settings_extract,node_card_converter toneRose
```

## Components

### Web interface

- [Story interface](https://github.com/alienet1109/bookworld/blob/main/frontend/js/message.js): `frontend/js/message.js`
- [World map](https://github.com/alienet1109/bookworld/blob/main/frontend/js/left-section/map-panel.js): `frontend/js/left-section/map-panel.js`
- [Character profiles](https://github.com/alienet1109/bookworld/blob/main/frontend/js/left-section/profile-panel.js): `frontend/js/left-section/profile-panel.js`
- [Scene controls](https://github.com/alienet1109/bookworld/blob/main/frontend/js/right-section/scene-panel.js): `frontend/js/right-section/scene-panel.js`
- [WebSocket server](https://github.com/alienet1109/bookworld/blob/main/server.py): `server.py`

### Story simulation

- [Simulation controller](https://github.com/alienet1109/bookworld/blob/main/BookWorld.py): `BookWorld.py`
- [World agent](https://github.com/alienet1109/bookworld/blob/main/modules/world_agent.py): `modules/world_agent.py`
- [Character agents](https://github.com/alienet1109/bookworld/blob/main/modules/main_role_agent.py): `modules/main_role_agent.py`
- [Story evaluation](https://github.com/alienet1109/bookworld/blob/main/modules/eval_agent.py): `modules/eval_agent.py`
- [Character prompts](https://github.com/alienet1109/bookworld/blob/main/modules/prompt/role_agent_prompt_en.py): `modules/prompt/role_agent_prompt_en.py`
- [World prompts](https://github.com/alienet1109/bookworld/blob/main/modules/prompt/world_agent_prompt_en.py): `modules/prompt/world_agent_prompt_en.py`
- [LLM adapters](https://github.com/alienet1109/bookworld/tree/main/modules/llm): `modules/llm`

### Agent state

- [Simulation history](https://github.com/alienet1109/bookworld/blob/main/modules/history_manager.py): `modules/history_manager.py`
- [Agent memory](https://github.com/alienet1109/bookworld/blob/main/modules/memory.py): `modules/memory.py`
- [ChromaDB](https://github.com/alienet1109/bookworld/blob/main/modules/db/ChromaDB.py): `modules/db/ChromaDB.py`
- [Embedding models](https://github.com/alienet1109/bookworld/blob/main/modules/embedding.py): `modules/embedding.py`

### World preparation

- [Novel extraction](https://github.com/alienet1109/bookworld/blob/main/extract_data/extract_data.py): `extract_data/extract_data.py`
- [Setting extraction](https://github.com/alienet1109/bookworld/blob/main/extract_data/extract_settings.py): `extract_data/extract_settings.py`
- [Card conversion](https://github.com/alienet1109/bookworld/blob/main/convert_sillytavern_cards_to_data.py): `convert_sillytavern_cards_to_data.py`

### Other components

- **User**

## Connections

- User → Story interface: controls
- Story interface → WebSocket server: WebSocket messages
- WebSocket server → Story interface: story and status
- WebSocket server → Simulation controller: controls simulation
- Simulation controller → WebSocket server: story and state
- Simulation controller → World agent: orchestrates world
- World agent → Character agents: coordinates characters
- Character agents → Character prompts: uses prompts
- World agent → World prompts: uses prompts
- Character agents → LLM adapters: generates dialogue
- World agent → LLM adapters: generates world
- Story evaluation → LLM adapters: requests evaluation
- Simulation controller → Simulation history: records progression
- Character agents → Agent memory: updates memories
- Agent memory → ChromaDB: stores and retrieves
- ChromaDB → Embedding models: embeds text
- Novel extraction → LLM adapters: extracts story data
- Setting extraction → LLM adapters: extracts settings
- Card conversion → Character agents: prepares role data
- Story interface → World map: shows map
- Story interface → Character profiles: shows characters
- Story interface → Scene controls: selects scenes