# ziyulisiyuan/ai-grouproleplay architecture

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

- Interactive diagram: https://gitdiagram.com/ziyulisiyuan/ai-grouproleplay
- Repository: https://github.com/ziyulisiyuan/ai-grouproleplay

## Overview

群像本 is a local-first, multi-character roleplay engine. A user works through the web UI to configure a group and its characters, then sends a message; the server passes it to a GroupSession, which judges routing, presence and knowledge boundaries before generating character output and recording the turn. Its other major capabilities include scene-map authoring, status and verbatim-memory ledgers, auditable judgments, and replayable file storage. The README documents the runtime flow; sampled source confirms several module calls, while some feature-level links are documented but not source-verified.

Main entry points: [`src/group/engine.ts`](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/engine.ts) (GroupSession), [`src/server.ts`](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/server.ts) (HTTP server), [`src/llm/chat.ts`](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/llm/chat.ts) (LLM transport), [`web/src/App.tsx`](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/App.tsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_chatui["Chat interface<br/>[chat.tsx]"]
  node_groupui["Group editor<br/>[groupinfo.tsx]"]
  node_api["Web API client<br/>[api.ts]"]
  node_android["Android shell<br/>[MainActivity.java]"]
end

subgraph group_runtime["Conversation runtime"]
  node_server["HTTP server<br/>[server.ts]"]
  node_session["GroupSession<br/>[engine.ts]"]
  node_llmhost["Generation host<br/>[host.ts]"]
  node_llm["LLM transport<br/>[chat.ts]"]
end

subgraph group_domain["Roleplay systems"]
  node_director["Judge and router<br/>[host.ts]"]
  node_router["Fallback routing<br/>[router.ts]"]
  node_presence["Presence and map<br/>[presence.ts]"]
  node_knowledge["Knowledge ledger<br/>[knowledge.ts]"]
  node_status["Status ledger<br/>[status.ts]"]
  node_persona["Character assets<br/>[persona.ts]"]
  node_scaffold["Group authoring<br/>[scaffold.ts]"]
  node_scene["Scene authoring<br/>[scene.ts]"]
end

subgraph group_storage["Local state and models"]
  node_store[("StoryStore<br/>[store.ts]")]
  node_files["Local files<br/>[store.ts]"]
  node_settings["Model settings<br/>[settings.ts]"]
  node_thinking["Judgment traces<br/>[thinking.ts]"]
end

node_user(("User"))
node_provider(("Configured model"))

node_user -->|"uses"| node_webapp
node_webapp -->|"opens chat"| node_chatui
node_webapp -->|"edits group"| node_groupui
node_chatui -->|"sends messages"| node_api
node_groupui -->|"saves settings"| node_api
node_api -->|"calls /api"| node_server
node_server -->|"runs turns"| node_session
node_server -->|"updates assets"| node_scaffold
node_server -->|"saves descriptions"| node_scene
node_session -->|"opens and records"| node_store
node_session -->|"loads characters"| node_persona
node_session -->|"requests judgments"| node_director
node_session -->|"loads scene state"| node_presence
node_session -->|"loads status"| node_status
node_session -->|"manages knowledge"| node_knowledge
node_director -.->|"falls back to"| node_router
node_director -->|"requests judgments"| node_llm
node_session -.->|"generates replies"| node_llmhost
node_llmhost -->|"streams output"| node_llm
node_llm -->|"resolves provider"| node_settings
node_llm -->|"sends model requests"| node_provider
node_settings -->|"reads configuration"| node_files
node_store -->|"appends story log"| node_files
node_session -.->|"records judgments"| node_thinking
node_scaffold -->|"creates character assets"| node_persona
node_scene -.->|"persists scene data"| node_files
node_android -->|"hosts on device"| node_server

click node_webapp "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/App.tsx"
click node_chatui "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/chat.tsx"
click node_groupui "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/groupinfo.tsx"
click node_api "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/api.ts"
click node_server "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/server.ts"
click node_session "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/engine.ts"
click node_director "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/host.ts"
click node_router "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/router.ts"
click node_presence "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/presence.ts"
click node_knowledge "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/knowledge.ts"
click node_status "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/status.ts"
click node_persona "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/persona.ts"
click node_scaffold "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/scaffold.ts"
click node_scene "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/scene.ts"
click node_store "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/store.ts"
click node_files "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/store.ts"
click node_settings "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/settings.ts"
click node_llmhost "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/host.ts"
click node_llm "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/llm/chat.ts"
click node_thinking "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/thinking.ts"
click node_android "https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/android/app/src/main/java/com/roleplay/groupchat/MainActivity.java"

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_webapp,node_chatui,node_groupui,node_api,node_android,node_user toneBlue
class node_server,node_session,node_llmhost,node_llm toneAmber
class node_director,node_router,node_presence,node_knowledge,node_status,node_persona,node_scaffold,node_scene toneMint
class node_store,node_files,node_settings,node_thinking toneRose
class node_provider toneIndigo
```

## Components

### User interface

- [Web app](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Chat interface](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/chat.tsx): `web/src/chat.tsx`
- [Group editor](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/groupinfo.tsx): `web/src/groupinfo.tsx`
- [Web API client](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/web/src/api.ts): `web/src/api.ts`
- [Android shell](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/android/app/src/main/java/com/roleplay/groupchat/MainActivity.java): `android/app/src/main/java/com/roleplay/groupchat/MainActivity.java`

### Conversation runtime

- [HTTP server](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/server.ts): `src/server.ts`
- [GroupSession](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/engine.ts): `src/group/engine.ts`
- [Generation host](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/host.ts): `src/host.ts`
- [LLM transport](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/llm/chat.ts): `src/llm/chat.ts`

### Roleplay systems

- [Judge and router](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/host.ts): `src/group/host.ts`
- [Fallback routing](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/router.ts): `src/group/router.ts`
- [Presence and map](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/presence.ts): `src/group/presence.ts`
- [Knowledge ledger](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/knowledge.ts): `src/group/knowledge.ts`
- [Status ledger](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/status.ts): `src/group/status.ts`
- [Character assets](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/persona.ts): `src/group/persona.ts`
- [Group authoring](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/scaffold.ts): `src/group/scaffold.ts`
- [Scene authoring](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/scene.ts): `src/group/scene.ts`

### Local state and models

- [StoryStore](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/store.ts): `src/store.ts`
- [Local files](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/store.ts): `src/store.ts`
- [Model settings](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/settings.ts): `src/settings.ts`
- [Judgment traces](https://github.com/ziyulisiyuan/ai-grouproleplay/blob/main/src/group/thinking.ts): `src/group/thinking.ts`

### Other components

- **User**
- **Configured model**

## Connections

- User → Web app: uses (evidence: `README.md`)
- Web app → Chat interface: opens chat (evidence: `web/src/App.tsx`)
- Web app → Group editor: edits group (evidence: `web/src/App.tsx`)
- Chat interface → Web API client: sends messages (evidence: `web/src/chat.tsx`)
- Group editor → Web API client: saves settings (evidence: `web/src/groupinfo.tsx`)
- Web API client → HTTP server: calls /api (evidence: `README.md`)
- HTTP server → GroupSession: runs turns (evidence: `README.md`)
- HTTP server → Group authoring: updates assets (evidence: `src/server.ts`)
- HTTP server → Scene authoring: saves descriptions (evidence: `src/server.ts`)
- GroupSession → StoryStore: opens and records (evidence: `src/group/engine.ts`)
- GroupSession → Character assets: loads characters (evidence: `src/group/engine.ts`)
- GroupSession → Judge and router: requests judgments (evidence: `src/group/engine.ts`)
- GroupSession → Presence and map: loads scene state (evidence: `src/group/engine.ts`)
- GroupSession → Status ledger: loads status (evidence: `src/group/engine.ts`)
- GroupSession → Knowledge ledger: manages knowledge (evidence: `src/group/engine.ts`)
- Judge and router → Fallback routing: falls back to (evidence: `src/group/host.ts`)
- Judge and router → LLM transport: requests judgments (evidence: `src/group/host.ts`)
- GroupSession → Generation host: generates replies (evidence: `src/group/engine.ts`)
- Generation host → LLM transport: streams output (evidence: `src/host.ts`)
- LLM transport → Model settings: resolves provider (evidence: `src/host.ts`)
- LLM transport → Configured model: sends model requests (evidence: `README.md`)
- Model settings → Local files: reads configuration (evidence: `src/settings.ts`)
- StoryStore → Local files: appends story log (evidence: `src/store.ts`)
- GroupSession → Judgment traces: records judgments (evidence: `src/group/engine.ts`)
- Group authoring → Character assets: creates character assets (evidence: `src/group/scaffold.ts`)
- Scene authoring → Local files: persists scene data
- Android shell → HTTP server: hosts on device (evidence: `README.md`)
