# jansen-liang/graphworld architecture

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

## Overview

GraphWorld is a platform for building interactive building-scale scene assets, running embodied-agent simulations, and evaluating task performance through web and runtime adapters. The principal workflow is scene preparation, agent or human action, world-state evolution, and replay/metrics output. The graph preserves the API, scene/run services, generation, runtime, and evaluation branches. Evidence is limited to the README and the supplied source excerpts and index; unsampled connections are omitted or marked unverified.

Main entry points: [`backend/app/services/run_service.py`](https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/run_service.py) (Run service), [`backend/runtime/world/graph.py`](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/world/graph.py) (World graph), [`frontend/web/src/app/App.tsx`](https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/app/App.tsx) (Web application), [`backend/app/services/scene_service.py`](https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/scene_service.py) (Scene service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_scene_ui["Scene tools"]
  node_run_ui["Run and replay UI<br/>[RunDetailPage.tsx]"]
end

subgraph group_api["Platform API"]
  node_api_app["HTTP API<br/>[main.py]"]
  node_scene_service["Scene service<br/>[scene_service.py]"]
  node_scene_import["Scene importer<br/>[scene_importer.py]"]
  node_run_service["Run service<br/>[run_service.py]"]
  node_simulation_service["Live simulation"]
  node_db_models[("Persistent records")]
end

subgraph group_world["World model"]
  node_generation["Scene generation"]
  node_core_nodes["Nodes and state<br/>[node.py]"]
  node_core_edges["Relations<br/>[edge.py]"]
  node_core_actions["Action model<br/>[action.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_world_graph["World graph<br/>[graph.py]"]
  node_action_engine["Action resolution<br/>[action_engine.py]"]
  node_action_executor["Action execution<br/>[action_executor.py]"]
  node_input_adapter["Input adapter<br/>[input_adapter.py]"]
  node_scene_prep["Scene preparation"]
  node_adapters["Runtime adapters"]
end

subgraph group_research["Agent and evaluation"]
  node_agent_decision["Agent decision<br/>[decision.py]"]
  node_agent_planning["Agent planning<br/>[planning.py]"]
  node_evaluation["Task evaluation"]
  node_experiment_records["Replay and metrics<br/>[episode_records.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_scene_ui
node_webapp -->|"routes to"| node_run_ui
node_scene_service -->|"imports"| node_scene_import
node_run_service -->|"uses records"| node_db_models
node_run_service -->|"uses repository"| node_scene_service
node_run_service -->|"chooses actions"| node_agent_decision
node_run_service -->|"uses"| node_input_adapter
node_scene_service -->|"prepares scenes"| node_scene_prep
node_simulation_service -->|"resolves input"| node_input_adapter
node_simulation_service -->|"executes actions"| node_action_executor
node_scene_import -->|"imports schema"| node_core_nodes
node_generation -.->|"creates assets"| node_core_nodes
node_generation -.->|"defines relations"| node_core_edges
node_input_adapter -.->|"resolves input"| node_action_engine
node_action_engine -->|"binds actions"| node_core_actions
node_action_executor -->|"delegates resolution"| node_action_engine
node_action_executor -->|"mutates world"| node_world_graph
node_world_graph -->|"stores nodes"| node_core_nodes
node_world_graph -->|"stores relations"| node_core_edges
node_agent_decision -->|"uses planning"| node_agent_planning
node_run_service -.->|"evaluates runs"| node_evaluation
node_experiment_records -->|"records evaluation"| node_evaluation
node_world_graph -.->|"exports snapshots"| node_adapters
node_adapters -.->|"renders world"| node_webapp
node_run_service -.->|"emits replay and metrics"| node_experiment_records

click node_webapp "https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/app/App.tsx"
click node_scene_ui "https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/features/scene-builder/SceneBuilderPage.tsx"
click node_run_ui "https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/features/run-monitor/RunDetailPage.tsx"
click node_api_app "https://github.com/jansen-liang/graphworld/blob/main/backend/app/main.py"
click node_scene_service "https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/scene_service.py"
click node_scene_import "https://github.com/jansen-liang/graphworld/blob/main/backend/app/runtime/scene_importer.py"
click node_run_service "https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/run_service.py"
click node_simulation_service "https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/simulation_service.py"
click node_db_models "https://github.com/jansen-liang/graphworld/tree/main/backend/app/db/models"
click node_generation "https://github.com/jansen-liang/graphworld/tree/main/backend/generation"
click node_core_nodes "https://github.com/jansen-liang/graphworld/blob/main/backend/core/node.py"
click node_core_edges "https://github.com/jansen-liang/graphworld/blob/main/backend/core/edge.py"
click node_core_actions "https://github.com/jansen-liang/graphworld/blob/main/backend/core/action.py"
click node_world_graph "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/world/graph.py"
click node_action_engine "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/action_engine.py"
click node_action_executor "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/action_executor.py"
click node_input_adapter "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/input_adapter.py"
click node_scene_prep "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/scene_preparation.py"
click node_agent_decision "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/agent/decision.py"
click node_agent_planning "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/agent/planning.py"
click node_evaluation "https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/eval/matrix_evaluator.py"
click node_experiment_records "https://github.com/jansen-liang/graphworld/blob/main/backend/experiments/episode_records.py"
click node_adapters "https://github.com/jansen-liang/graphworld/tree/main/backend/adapter"

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_scene_ui,node_run_ui toneBlue
class node_api_app,node_scene_service,node_scene_import,node_run_service,node_simulation_service,node_db_models toneAmber
class node_generation,node_core_nodes,node_core_edges,node_core_actions toneMint
class node_world_graph,node_action_engine,node_action_executor,node_input_adapter,node_scene_prep,node_adapters toneRose
class node_agent_decision,node_agent_planning,node_evaluation,node_experiment_records,node_researcher toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/app/App.tsx): `frontend/web/src/app/App.tsx`
- [Scene tools](https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/features/scene-builder/SceneBuilderPage.tsx): `frontend/web/src/features/scene-builder/SceneBuilderPage.tsx`
- [Run and replay UI](https://github.com/jansen-liang/graphworld/blob/main/frontend/web/src/features/run-monitor/RunDetailPage.tsx): `frontend/web/src/features/run-monitor/RunDetailPage.tsx`

### Platform API

- [HTTP API](https://github.com/jansen-liang/graphworld/blob/main/backend/app/main.py): `backend/app/main.py`
- [Scene service](https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/scene_service.py): `backend/app/services/scene_service.py`
- [Scene importer](https://github.com/jansen-liang/graphworld/blob/main/backend/app/runtime/scene_importer.py): `backend/app/runtime/scene_importer.py`
- [Run service](https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/run_service.py): `backend/app/services/run_service.py`
- [Live simulation](https://github.com/jansen-liang/graphworld/blob/main/backend/app/services/simulation_service.py): `backend/app/services/simulation_service.py`
- [Persistent records](https://github.com/jansen-liang/graphworld/tree/main/backend/app/db/models): `backend/app/db/models`

### World model

- [Scene generation](https://github.com/jansen-liang/graphworld/tree/main/backend/generation): `backend/generation`
- [Nodes and state](https://github.com/jansen-liang/graphworld/blob/main/backend/core/node.py): `backend/core/node.py`
- [Relations](https://github.com/jansen-liang/graphworld/blob/main/backend/core/edge.py): `backend/core/edge.py`
- [Action model](https://github.com/jansen-liang/graphworld/blob/main/backend/core/action.py): `backend/core/action.py`

### Simulation runtime

- [World graph](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/world/graph.py): `backend/runtime/world/graph.py`
- [Action resolution](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/action_engine.py): `backend/runtime/action_engine.py`
- [Action execution](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/action_executor.py): `backend/runtime/action_executor.py`
- [Input adapter](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/input_adapter.py): `backend/runtime/input_adapter.py`
- [Scene preparation](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/scene_preparation.py): `backend/runtime/scene_preparation.py`
- [Runtime adapters](https://github.com/jansen-liang/graphworld/tree/main/backend/adapter): `backend/adapter`

### Agent and evaluation

- [Agent decision](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/agent/decision.py): `backend/runtime/agent/decision.py`
- [Agent planning](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/agent/planning.py): `backend/runtime/agent/planning.py`
- [Task evaluation](https://github.com/jansen-liang/graphworld/blob/main/backend/runtime/eval/matrix_evaluator.py): `backend/runtime/eval/matrix_evaluator.py`
- [Replay and metrics](https://github.com/jansen-liang/graphworld/blob/main/backend/experiments/episode_records.py): `backend/experiments/episode_records.py`

### Other components

- **Researcher**

## Connections

- Researcher → Web application: uses
- Web application → Scene tools: routes to (evidence: `frontend/web/src/app/App.tsx`)
- Web application → Run and replay UI: routes to (evidence: `frontend/web/src/app/App.tsx`)
- Scene service → Scene importer: imports (evidence: `backend/app/services/scene_service.py`)
- Run service → Persistent records: uses records (evidence: `backend/app/services/run_service.py`)
- Run service → Scene service: uses repository (evidence: `backend/app/services/run_service.py`)
- Run service → Agent decision: chooses actions (evidence: `backend/app/services/run_service.py`)
- Run service → Input adapter: uses (evidence: `backend/app/services/run_service.py`)
- Scene service → Scene preparation: prepares scenes (evidence: `backend/app/services/scene_service.py`)
- Live simulation → Input adapter: resolves input (evidence: `backend/app/services/simulation_service.py`)
- Live simulation → Action execution: executes actions (evidence: `backend/app/services/simulation_service.py`)
- Scene importer → Nodes and state: imports schema (evidence: `backend/app/runtime/scene_importer.py`)
- Scene generation → Nodes and state: creates assets (evidence: `backend/generation/symbolic_scene_generator.py`)
- Scene generation → Relations: defines relations (evidence: `backend/generation/ontology/model.py`)
- Input adapter → Action resolution: resolves input
- Action resolution → Action model: binds actions (evidence: `backend/runtime/action_engine.py`)
- Action execution → Action resolution: delegates resolution (evidence: `backend/runtime/action_executor.py`)
- Action execution → World graph: mutates world (evidence: `backend/runtime/action_executor.py`)
- World graph → Nodes and state: stores nodes (evidence: `backend/runtime/world/graph.py`)
- World graph → Relations: stores relations (evidence: `backend/runtime/world/graph.py`)
- Agent decision → Agent planning: uses planning (evidence: `backend/runtime/agent/decision.py`)
- Run service → Task evaluation: evaluates runs (evidence: `backend/app/services/run_service.py`)
- Replay and metrics → Task evaluation: records evaluation (evidence: `backend/experiments/episode_records.py`)
- World graph → Runtime adapters: exports snapshots (evidence: `backend/runtime/world/graph.py`)
- Runtime adapters → Web application: renders world
- Run service → Replay and metrics: emits replay and metrics
