# xiaoluolyg/god architecture

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

- Interactive diagram: https://gitdiagram.com/xiaoluolyg/god
- Repository: https://github.com/xiaoluolyg/god

## Overview

1. **This repo is a bundled operator platform for agent-society simulations**
   It combines two major upstream codebases: **AgentSociety** for simulation and replay, and **JiuwenClaw** for agent runtime, tool use, and multi-channel operator interfaces. The top-level project (`GOD`) adds the glue, local startup scripts, packaged scenarios, map assets, and published docs/site content.

2. **The user-facing surface is browser-first, with multiple frontends**
   There are two main React/Vite UIs:
   - `agentsociety/frontend`: the “Control Room” for setup, map studio, agent studio, replay, experiments, and live interventions.
   - `jiuwenclaw/jiuwenclaw/channels/web/frontend`: a richer operator console for chat, sessions, tools, config, logs, team state, and live interactions.
   There is also a terminal UI under `jiuwenclaw/jiuwenclaw/channels/tui/frontend` for CLI-style operator workflows.

3. **The core backend in AgentSociety owns the simulation-facing API**
   `agentsociety/packages/agentsociety2/agentsociety2/backend` is the main FastAPI service for:
   - agent packs
   - custom skills and packages
   - experiment configs/packs
   - maps and map studio
   - live experiments
   - replay access and public replay export
   This is the API the browser setup flow and replay UI talk to for simulation lifecycle operations.

4. **AgentSociety’s runtime model is built around experiments, agents, envs, skills, and replay storage**
   The package is organized as:
   - `agent/`: agent configuration, prompts, persistence, concurrent execution, and agent context/person models
   - `env/`: environment/router abstractions for simulation and benchmarking
   - `skills/`: higher-level analysis, literature, paper, web research, hypothesis, and experiment tooling
   - `society/`: workspace and CLI-style utilities for constructing studies and questionnaires
   - `storage/`: replay writer, schemas, metadata, and operator command persistence
   The key architectural boundary is that **experiments are declarative inputs**, while **replay/storage are the runtime outputs**.

5. **Maps are first-class scenario packages, not just assets**
   The repository ships and validates map packages under `agentsociety/custom/maps/`, with templates and concrete maps like `the_ville` and `pku`. A map package includes:
   - `map.yaml` metadata
   - `visuals/map.json` and tiled assets
   - optional `characters/` and `location_assets/`
   These maps are discovered by the backend and surfaced in setup; they define the spatial world that agent actions and replay rendering depend on.

6. **Custom skills are the main extension mechanism for agent behavior**
   There are two skill systems:
   - `agentsociety/custom/skills/…`: domain skills used by the simulation and content generation flow
   - `agentsociety/packages/agentsociety2/agentsociety2/skills/…`: reusable higher-level research/analysis/experiment utilities
   Each skill is a self-contained package with `SKILL.md`, a JSON manifest, and runnable scripts. The architecture treats skills as modular capabilities that can be generated, validated, imported, and executed independently of the core engine.

7. **JiuwenClaw is the out-of-process agent runtime and tool ecosystem**
   The `jiuwenclaw` subtree is a full application stack of its own:
   - `server/`: agent server, session management, skill manager, workspace, runtime adapters
   - `gateway/`: channel routing, IM platform adapters, cron, heartbeat, message handling
   - `agents/harness/`: prompt/rail/tool orchestration for agent execution
   - `common/` and `extensions/`: shared protocols, schema, security, and plugin hooks
   This runtime is what lets agents execute outside the browser/backend process and connect through channels and protocols.

8. **The runtime boundary is message-based and channel-aware**
   JiuwenClaw supports multiple ingress/egress channels: web, TUI, desktop, ACP, A2A, and several IM platforms such as WeChat, Feishu, DingTalk, Discord, Telegram, WhatsApp, and WeCom. The gateway normalizes inbound events, routes them to agent sessions, and sends responses back through the appropriate channel. This makes **channel adapters** the key integration boundary between external messaging systems and agent runtime state.

9. **Agent execution is mediated by harnesses, rails, tools, and memory**
   In JiuwenClaw, agent behavior is not hardcoded in a single loop. It is composed from:
   - harness layers for single-agent and team workflows
   - rails for permissions, response shaping, user prompts, project memory, and stream events
   - tools for browser, file, task, search, memory, audio/video, and phone-like actions
   - memory systems for internal/external/project memory
   This architecture separates policy/control from tool execution and keeps user-facing behavior configurable per agent or team.

10. **Data flows are local-first and mostly file-backed**
   From the README and package layout, the main persistent artifacts are:
   - experiment folders and map packages in the repo
   - local runtime state such as session data, agent snapshots, logs, and replay stores
   - published site data under `docs/site/public-data`
   - generated site pages and docs under `docs/site`
   The external dependency is typically only the configured **OpenAI-compatible model endpoint**; everything else runs locally.

11. **Replay is a dedicated read model, separate from live execution**
   Replay data is written by the simulation/storage layer and then served to the Control Room and public site. The repo contains live replay APIs, public replay exporters, and static replay bundles under `docs/site/public-data/replays/…`. This indicates a clear split between:
   - **live state**: ongoing simulation and operator interventions
   - **replay state**: immutable or exported step history for review and sharing

12. **Built-in scenarios are packaged as reproducible experiment folders**
   The `quick_experiments/` tree and `agentsociety/packages/agentsociety2/examples/` tree show that experiments are distributed as plain folders/scripts, not just database records. The setup wizard chooses one current experiment, and startup scripts operate against that selected experiment. This makes the experiment boundary portable, versionable, and easy to publish.

13. **Docs and site content are part of the deliverable, not an afterthought**
   The repository includes:
   - generated static documentation sites under `docs/site`
   - source docs for both user and developer audiences
   - localized content for English and Chinese
   - scripts for publishing public site assets
   For an architecture diagram, this is a distinct “published artifacts” lane fed from the codebase and data exports.

14. **Operationally, startup is orchestrated by repo-level scripts**
   `scripts/god.sh`, `scripts/god.cmd`, and related build/validation scripts act as the top-level orchestration layer. They bootstrap dependencies, select the current experiment, bring up the local services, and open the browser-based control room. So the overall system is best drawn as a **local workstation stack** with coordinated Python services, React UIs, and a model endpoint.

Main entry points: [`jiuwenclaw/jiuwenclaw/server/app_agentserver.py`](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/server/app_agentserver.py) (Agent server), [`scripts/god.sh`](https://github.com/xiaoluolyg/god/blob/main/scripts/god.sh) (Start scripts), [`agentsociety/packages/agentsociety2/agentsociety2/agent/base.py`](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/agent/base.py) (Agent runtime), [`agentsociety/packages/agentsociety2/agentsociety2/backend/app.py`](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/app.py) (Setup API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_root["GOD platform"]
  node_scripts_god["Start scripts<br/>orchestration<br/>[god.sh]"]
  node_scripts_publish["Publish site<br/>publishing"]
end

subgraph group_group_agentsociety["AgentSociety"]
  node_agentsociety_setup_backend["Setup API<br/>FastAPI backend<br/>[app.py]"]
  node_agentsociety_backend_routers["API routers<br/>HTTP endpoints<br/>[experiments.py]"]
  node_agentsociety_backend_services["Backend services<br/>domain services<br/>[replay_catalog.py]"]
  node_agentsociety_runtime_agent["Agent runtime<br/>agent model<br/>[base.py]"]
  node_agentsociety_runtime_env["Env routers<br/>simulation routing<br/>[router_react.py]"]
  node_agentsociety_runtime_skills["Research skills<br/>analysis/experiment skills<br/>[service.py]"]
  node_agentsociety_runtime_society["Society tools<br/>workspace/cli<br/>[workspace.py]"]
  node_agentsociety_runtime_storage[("Replay storage<br/>write model<br/>[replay_writer.py]")]
  node_agentsociety_custom_maps["Map packs<br/>scenario packages<br/>[map.yaml]"]
  node_agentsociety_custom_skills["Custom skills<br/>extension packages<br/>[SKILL.md]"]
  node_agentsociety_frontend_control["Control Room<br/>React/Vite UI<br/>[main.tsx]"]
end

subgraph group_group_jiuwenclaw["JiuwenClaw"]
  node_jiuwenclaw_server["Agent server<br/>session/runtime server<br/>[app_agentserver.py]"]
  node_jiuwenclaw_gateway["Gateway<br/>channel router<br/>[app_gateway.py]"]
  node_jiuwenclaw_harness["Harness<br/>agent orchestration<br/>[prompt_builder.py]"]
  node_jiuwenclaw_channels_web["Web console<br/>React/Vite UI<br/>[App.tsx]"]
  node_jiuwenclaw_channels_tui["TUI console<br/>terminal UI<br/>[index.ts]"]
  node_jiuwenclaw_common_extensions["Common + extensions<br/>protocol/plugin layer<br/>[wire_codec.py]"]
end

subgraph group_group_docs["Published artifacts"]
  node_site_public_data["Public data<br/>static exports<br/>[index.json]"]
  node_site_docs["Docs site<br/>static docs<br/>[index.html]"]
end

node_scripts_god -->|"boots"| node_agentsociety_setup_backend
node_scripts_god -->|"boots"| node_jiuwenclaw_server
node_scripts_god -->|"boots"| node_jiuwenclaw_gateway
node_scripts_god -->|"opens"| node_agentsociety_frontend_control
node_agentsociety_setup_backend -->|"mounts"| node_agentsociety_backend_routers
node_agentsociety_setup_backend -->|"uses"| node_agentsociety_backend_services
node_agentsociety_backend_routers -->|"reads"| node_agentsociety_custom_maps
node_agentsociety_backend_routers -->|"imports"| node_agentsociety_custom_skills
node_agentsociety_backend_services -->|"writes"| node_agentsociety_runtime_storage
node_agentsociety_runtime_agent -->|"drives"| node_agentsociety_runtime_env
node_agentsociety_runtime_agent -->|"invokes"| node_agentsociety_runtime_skills
node_agentsociety_runtime_agent -->|"persists"| node_agentsociety_runtime_storage
node_agentsociety_runtime_society -->|"builds"| node_agentsociety_runtime_agent
node_agentsociety_custom_maps -->|"feeds"| node_agentsociety_frontend_control
node_agentsociety_runtime_storage -->|"exports"| node_site_public_data
node_agentsociety_backend_services -->|"publishes"| node_site_public_data
node_agentsociety_frontend_control -->|"calls"| node_agentsociety_setup_backend
node_agentsociety_frontend_control -->|"views"| node_site_public_data
node_jiuwenclaw_server -->|"orchestrates"| node_jiuwenclaw_harness
node_jiuwenclaw_server -->|"depends on"| node_jiuwenclaw_common_extensions
node_jiuwenclaw_gateway -->|"normalizes"| node_jiuwenclaw_common_extensions
node_jiuwenclaw_gateway -->|"routes to"| node_jiuwenclaw_server
node_jiuwenclaw_harness -->|"uses"| node_jiuwenclaw_common_extensions
node_jiuwenclaw_channels_web -->|"connects"| node_jiuwenclaw_server
node_jiuwenclaw_channels_tui -->|"connects"| node_jiuwenclaw_server
node_scripts_publish -->|"builds"| node_site_docs
node_scripts_publish -->|"packages"| node_site_public_data

click node_scripts_god "https://github.com/xiaoluolyg/god/blob/main/scripts/god.sh"
click node_scripts_publish "https://github.com/xiaoluolyg/god/blob/main/scripts/publish_site_release_assets.py"
click node_agentsociety_setup_backend "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/app.py"
click node_agentsociety_backend_routers "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiments.py"
click node_agentsociety_backend_services "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/services/replay_catalog.py"
click node_agentsociety_runtime_agent "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/agent/base.py"
click node_agentsociety_runtime_env "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/env/router_react.py"
click node_agentsociety_runtime_skills "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/skills/analysis/service.py"
click node_agentsociety_runtime_society "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/society/workspace.py"
click node_agentsociety_runtime_storage "https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/storage/replay_writer.py"
click node_agentsociety_custom_maps "https://github.com/xiaoluolyg/god/blob/main/agentsociety/custom/maps/the_ville/map.yaml"
click node_agentsociety_custom_skills "https://github.com/xiaoluolyg/god/blob/main/agentsociety/custom/skills/care.basic/SKILL.md"
click node_agentsociety_frontend_control "https://github.com/xiaoluolyg/god/blob/main/agentsociety/frontend/src/main.tsx"
click node_jiuwenclaw_server "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/server/app_agentserver.py"
click node_jiuwenclaw_gateway "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/gateway/app_gateway.py"
click node_jiuwenclaw_harness "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/agents/harness/common/prompt/prompt_builder.py"
click node_jiuwenclaw_channels_web "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/channels/web/frontend/src/App.tsx"
click node_jiuwenclaw_channels_tui "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/channels/tui/frontend/src/index.ts"
click node_jiuwenclaw_common_extensions "https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/common/e2a/wire_codec.py"
click node_site_public_data "https://github.com/xiaoluolyg/god/blob/main/docs/site/public-data/experiments/index.json"
click node_site_docs "https://github.com/xiaoluolyg/god/blob/main/docs/site/index.html"

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_scripts_god,node_scripts_publish toneBlue
class node_agentsociety_setup_backend,node_agentsociety_backend_routers,node_agentsociety_backend_services,node_agentsociety_runtime_agent,node_agentsociety_runtime_env,node_agentsociety_runtime_skills,node_agentsociety_runtime_society,node_agentsociety_runtime_storage,node_agentsociety_custom_maps,node_agentsociety_custom_skills,node_agentsociety_frontend_control toneAmber
class node_jiuwenclaw_server,node_jiuwenclaw_gateway,node_jiuwenclaw_harness,node_jiuwenclaw_channels_web,node_jiuwenclaw_channels_tui,node_jiuwenclaw_common_extensions toneMint
class node_site_public_data,node_site_docs toneRose
```

## Components

### GOD platform

Repo-level orchestration and bundled deliverables

- [Start scripts](https://github.com/xiaoluolyg/god/blob/main/scripts/god.sh): orchestration · Repo-level bootstrap entrypoints for local workstation startup · `scripts/god.sh`
- [Publish site](https://github.com/xiaoluolyg/god/blob/main/scripts/publish_site_release_assets.py): publishing · Builds and validates public site assets and releases · `scripts/publish_site_release_assets.py`

### AgentSociety

Simulation platform, control room, replay, maps, and custom skills

- [Setup API](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/app.py): FastAPI backend · Simulation-facing API for packs, maps, experiments, replay, and imports · `agentsociety/packages/agentsociety2/agentsociety2/backend/app.py`
- [API routers](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiments.py): HTTP endpoints · Route layer for setup, maps, experiments, live runs, replay, and package import · `agentsociety/packages/agentsociety2/agentsociety2/backend/routers/experiments.py`
- [Backend services](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/backend/services/replay_catalog.py): domain services · Pack registry, map generation, archive/import handling, and public replay export · `agentsociety/packages/agentsociety2/agentsociety2/backend/services/replay_catalog.py`
- [Agent runtime](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/agent/base.py): agent model · Agent config, prompts, persistence, context, and concurrent execution · `agentsociety/packages/agentsociety2/agentsociety2/agent/base.py`
- [Env routers](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/env/router_react.py): simulation routing · Environment abstractions and router strategies for simulation and benchmarking · `agentsociety/packages/agentsociety2/agentsociety2/env/router_react.py`
- [Research skills](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/skills/analysis/service.py): analysis/experiment skills · Higher-level analysis, literature, paper, web research, hypothesis, and experiment utilities · `agentsociety/packages/agentsociety2/agentsociety2/skills/analysis/service.py`
- [Society tools](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/society/workspace.py): workspace/cli · Workspace, questionnaire, and study utilities for society-style workflows · `agentsociety/packages/agentsociety2/agentsociety2/society/workspace.py`
- [Replay storage](https://github.com/xiaoluolyg/god/blob/main/agentsociety/packages/agentsociety2/agentsociety2/storage/replay_writer.py): write model · Replay writer, operator commands, metadata, and schema management · `agentsociety/packages/agentsociety2/agentsociety2/storage/replay_writer.py`
- [Map packs](https://github.com/xiaoluolyg/god/blob/main/agentsociety/custom/maps/the_ville/map.yaml): scenario packages · Validated map packages with metadata, visuals, assets, and optional characters · `agentsociety/custom/maps/the_ville/map.yaml`
- [Custom skills](https://github.com/xiaoluolyg/god/blob/main/agentsociety/custom/skills/care.basic/SKILL.md): extension packages · Domain skills with SKILL.md manifests and runnable scripts · `agentsociety/custom/skills/care.basic/SKILL.md`
- [Control Room](https://github.com/xiaoluolyg/god/blob/main/agentsociety/frontend/src/main.tsx): React/Vite UI · Browser UI for setup, map studio, agent studio, replay, experiments, and interventions · `agentsociety/frontend/src/main.tsx`

### JiuwenClaw

Out-of-process agent runtime, gateway, harness, and operator consoles

- [Agent server](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/server/app_agentserver.py): session/runtime server · Session management, skill manager, workspace, and runtime adapters · `jiuwenclaw/jiuwenclaw/server/app_agentserver.py`
- [Gateway](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/gateway/app_gateway.py): channel router · Normalizes inbound events and routes across channels and protocols · `jiuwenclaw/jiuwenclaw/gateway/app_gateway.py`
- [Harness](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/agents/harness/common/prompt/prompt_builder.py): agent orchestration · Prompt, rails, tools, memory, and team execution layers · `jiuwenclaw/jiuwenclaw/agents/harness/common/prompt/prompt_builder.py`
- [Web console](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/channels/web/frontend/src/App.tsx): React/Vite UI · Browser operator console for chat, sessions, tools, config, logs, and team state · `jiuwenclaw/jiuwenclaw/channels/web/frontend/src/App.tsx`
- [TUI console](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/channels/tui/frontend/src/index.ts): terminal UI · CLI-style operator workflow UI with commands, transcripts, and session tools · `jiuwenclaw/jiuwenclaw/channels/tui/frontend/src/index.ts`
- [Common + extensions](https://github.com/xiaoluolyg/god/blob/main/jiuwenclaw/jiuwenclaw/common/e2a/wire_codec.py): protocol/plugin layer · Shared schemas, wire formats, security, and extension hooks · `jiuwenclaw/jiuwenclaw/common/e2a/wire_codec.py`

### Published artifacts

Static docs and site data exported from packages and scenarios

- [Public data](https://github.com/xiaoluolyg/god/blob/main/docs/site/public-data/experiments/index.json): static exports · Published maps, agent packs, experiments, and replay bundles · `docs/site/public-data/experiments/index.json`
- [Docs site](https://github.com/xiaoluolyg/god/blob/main/docs/site/index.html): static docs · Generated documentation and localized site pages · `docs/site/index.html`

## Connections

- Start scripts → Setup API: boots · Starts the simulation backend as part of the local stack
- Start scripts → Agent server: boots · Starts the out-of-process agent runtime/server
- Start scripts → Gateway: boots · Starts channel routing and message ingress/egress
- Start scripts → Control Room: opens · Launches the browser control room after services are ready
- Setup API → API routers: mounts · Exposes simulation and setup HTTP routes
- Setup API → Backend services: uses · Delegates pack, map, import, and replay operations
- API routers → Map packs: reads · Discovers and validates map packages
- API routers → Custom skills: imports · Scans custom skill packages for setup/runtime use
- Backend services → Replay storage: writes · Exports replay history and operator command records
- Agent runtime → Env routers: drives · Agent execution interacts with simulation environments
- Agent runtime → Research skills: invokes · Agents can call higher-level research and experiment skills
- Agent runtime → Replay storage: persists · Agent state and execution artifacts flow into replay/storage
- Society tools → Agent runtime: builds · Workspace and CLI tools construct agent-facing studies and outputs
- Map packs → Control Room: feeds · Map packages are surfaced in the Control Room setup and studio flows
- Replay storage → Public data: exports · Replay data is published as immutable public bundles
- Backend services → Public data: publishes · Agent packs, maps, experiments, and replays are exported to site data
- Control Room → Setup API: calls · Setup UI talks to the simulation-facing API
- Control Room → Public data: views · Replay and published scenario pages consume exported static data
- Agent server → Harness: orchestrates · Server coordinates harness execution, sessions, and tools
- Agent server → Common + extensions: depends on · Uses shared schemas, protocols, security, and plugin hooks
- Gateway → Common + extensions: normalizes · Converts platform messages into shared event and wire formats
- Gateway → Agent server: routes to · Forwards channel events into agent sessions and runtime state
- Harness → Common + extensions: uses · Harness layers rely on shared message and plugin contracts
- Web console → Agent server: connects · Web console streams session state and operator interactions
- TUI console → Agent server: connects · Terminal console drives sessions and commands through the server
- Publish site → Docs site: builds · Generates and validates the static documentation/site output
- Publish site → Public data: packages · Prepares public exports for site consumption and release
