# junjianchi/artiscene architecture

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

- Interactive diagram: https://gitdiagram.com/junjianchi/artiscene
- Repository: https://github.com/junjianchi/artiscene

## Overview

artiscene converts a natural-language scene brief into an authored, validated USD scene for Isaac Sim. Its principal workflow runs Shell, Furniture, and Physics design stages over shared SceneState, then deterministically authors the composed scene and reviews its quality. The product also exposes generation and session inspection through a CLI and catalog browsing/generation through MCP. The README documents the full stage order and optional integrations; several subsystem links below are omitted or marked unverified where the sampled source does not show their calls.

Main entry points: [`articscene/pipeline/pipeline.py`](https://github.com/junjianchi/artiscene/blob/main/articscene/pipeline/pipeline.py) (Stage Pipeline), [`articscene/mechanical/scene_author.py`](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/scene_author.py) (Scene Author), [`articscene/core/scene_state.py`](https://github.com/junjianchi/artiscene/blob/main/articscene/core/scene_state.py) (Shared Scene State), [`articscene/agents/furniture/agent.py`](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/furniture/agent.py) (Furniture Design)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_mcp_tools["MCP Tools<br/>[tools.py]"]
end

subgraph group_workflow["Scene Workflow"]
  node_pipeline["Stage Pipeline<br/>[pipeline.py]"]
  node_state["Shared Scene State<br/>[scene_state.py]"]
  node_shell["Shell Design<br/>[agent.py]"]
  node_furniture["Furniture Design<br/>[agent.py]"]
  node_physics["Physics Design<br/>[agent.py]"]
  node_review["Scene Review<br/>[agent.py]"]
  node_agent_loop["Designer Critic Loop<br/>[base.py]"]
end

subgraph group_authoring["Asset Authoring"]
  node_catalog[("Articraft Catalog")]
  node_materials["Material Retrieval"]
  node_author["Scene Author<br/>[scene_author.py]"]
  node_room_compose["Room Composition<br/>[room.py]"]
  node_urdf_usd["Articulated USD<br/>[urdf_to_usd.py]"]
  node_prop_author["Static Prop Authoring<br/>[authoring.py]"]
  node_isaac_scene["Isaac Scene Composition"]
end

subgraph group_runtime["Runtime and Sessions"]
  node_runtime_context["Runtime Configuration<br/>[context.py]"]
  node_providers["LLM Providers<br/>[factory.py]"]
  node_storage_layout["Session Layout<br/>[storage_layout.py]"]
  node_session_writer["Session Persistence<br/>[session_writer.py]"]
end

node_user(("Scene Requester"))
node_isaac["Isaac Sim"]
node_ambientcg["AmbientCG"]
node_meshy["Meshy"]
node_openai["OpenAI"]

node_user -->|"submits prompt"| node_cli
node_user -->|"requests generation"| node_mcp
node_mcp -->|"serves tools"| node_mcp_tools
node_mcp_tools -->|"invokes workflow"| node_pipeline
node_cli -.->|"starts generation"| node_pipeline
node_pipeline -->|"uses configuration"| node_runtime_context
node_pipeline -->|"creates provider"| node_providers
node_pipeline -->|"runs stages"| node_shell
node_pipeline -->|"runs stages"| node_furniture
node_pipeline -->|"runs stages"| node_physics
node_pipeline -->|"authors scene"| node_author
node_pipeline -->|"runs stages"| node_review
node_pipeline -->|"hands off state"| node_state
node_shell -->|"updates state"| node_state
node_furniture -->|"updates state"| node_state
node_physics -->|"updates state"| node_state
node_review -->|"records verdict"| node_state
node_shell -.->|"inherits loop"| node_agent_loop
node_furniture -->|"inherits loop"| node_agent_loop
node_physics -->|"inherits loop"| node_agent_loop
node_furniture -->|"retrieves assets"| node_catalog
node_physics -->|"inspects assets"| node_catalog
node_author -->|"reads scene data"| node_state
node_author -->|"composes room"| node_room_compose
node_author -->|"authors articulated assets"| node_urdf_usd
node_author -->|"authors props"| node_prop_author
node_author -->|"composes layers"| node_isaac_scene
node_room_compose -->|"uses material builder"| node_materials
node_pipeline -->|"resolves textures"| node_ambientcg
node_pipeline -->|"generates props"| node_meshy
node_pipeline -->|"generates decal images"| node_openai
node_pipeline -->|"resolves session paths"| node_storage_layout
node_pipeline -->|"persists session"| node_session_writer
node_isaac_scene -->|"loads USD scene"| node_isaac

click node_cli "https://github.com/junjianchi/artiscene/blob/main/articscene/cli/main.py"
click node_mcp "https://github.com/junjianchi/artiscene/blob/main/articscene/mcp/server.py"
click node_mcp_tools "https://github.com/junjianchi/artiscene/blob/main/articscene/mcp/tools.py"
click node_pipeline "https://github.com/junjianchi/artiscene/blob/main/articscene/pipeline/pipeline.py"
click node_state "https://github.com/junjianchi/artiscene/blob/main/articscene/core/scene_state.py"
click node_shell "https://github.com/junjianchi/artiscene/blob/main/articscene/agents/shell/agent.py"
click node_furniture "https://github.com/junjianchi/artiscene/blob/main/articscene/agents/furniture/agent.py"
click node_physics "https://github.com/junjianchi/artiscene/blob/main/articscene/agents/physics/agent.py"
click node_review "https://github.com/junjianchi/artiscene/blob/main/articscene/agents/scene_review/agent.py"
click node_agent_loop "https://github.com/junjianchi/artiscene/blob/main/articscene/agents/base.py"
click node_catalog "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/articraft_catalog.py"
click node_materials "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/material_retrieval.py"
click node_author "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/scene_author.py"
click node_room_compose "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/compose/room.py"
click node_urdf_usd "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/urdf_to_usd.py"
click node_prop_author "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/static_props/authoring.py"
click node_isaac_scene "https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/compose_isaac_scene.py"
click node_runtime_context "https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/context.py"
click node_providers "https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/providers/factory.py"
click node_storage_layout "https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/storage_layout.py"
click node_session_writer "https://github.com/junjianchi/artiscene/blob/main/articscene/storage/session_writer.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_cli,node_mcp,node_mcp_tools toneBlue
class node_pipeline,node_state,node_shell,node_furniture,node_physics,node_review,node_agent_loop toneAmber
class node_catalog,node_materials,node_author,node_room_compose,node_urdf_usd,node_prop_author,node_isaac_scene,node_user toneMint
class node_runtime_context,node_providers,node_storage_layout,node_session_writer toneRose
class node_isaac,node_ambientcg,node_meshy,node_openai toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/junjianchi/artiscene/blob/main/articscene/cli/main.py): `articscene/cli/main.py`
- [MCP Server](https://github.com/junjianchi/artiscene/blob/main/articscene/mcp/server.py): `articscene/mcp/server.py`
- [MCP Tools](https://github.com/junjianchi/artiscene/blob/main/articscene/mcp/tools.py): `articscene/mcp/tools.py`

### Scene Workflow

- [Stage Pipeline](https://github.com/junjianchi/artiscene/blob/main/articscene/pipeline/pipeline.py): `articscene/pipeline/pipeline.py`
- [Shared Scene State](https://github.com/junjianchi/artiscene/blob/main/articscene/core/scene_state.py): `articscene/core/scene_state.py`
- [Shell Design](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/shell/agent.py): `articscene/agents/shell/agent.py`
- [Furniture Design](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/furniture/agent.py): `articscene/agents/furniture/agent.py`
- [Physics Design](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/physics/agent.py): `articscene/agents/physics/agent.py`
- [Scene Review](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/scene_review/agent.py): `articscene/agents/scene_review/agent.py`
- [Designer Critic Loop](https://github.com/junjianchi/artiscene/blob/main/articscene/agents/base.py): `articscene/agents/base.py`

### Asset Authoring

- [Articraft Catalog](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/articraft_catalog.py): `articscene/mechanical/articraft_catalog.py`
- [Material Retrieval](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/material_retrieval.py): `articscene/mechanical/material_retrieval.py`
- [Scene Author](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/scene_author.py): `articscene/mechanical/scene_author.py`
- [Room Composition](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/compose/room.py): `articscene/mechanical/compose/room.py`
- [Articulated USD](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/urdf_to_usd.py): `articscene/mechanical/urdf_to_usd.py`
- [Static Prop Authoring](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/static_props/authoring.py): `articscene/mechanical/static_props/authoring.py`
- [Isaac Scene Composition](https://github.com/junjianchi/artiscene/blob/main/articscene/mechanical/compose_isaac_scene.py): `articscene/mechanical/compose_isaac_scene.py`

### Runtime and Sessions

- [Runtime Configuration](https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/context.py): `articscene/runtime/context.py`
- [LLM Providers](https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/providers/factory.py): `articscene/runtime/providers/factory.py`
- [Session Layout](https://github.com/junjianchi/artiscene/blob/main/articscene/runtime/storage_layout.py): `articscene/runtime/storage_layout.py`
- [Session Persistence](https://github.com/junjianchi/artiscene/blob/main/articscene/storage/session_writer.py): `articscene/storage/session_writer.py`

### Other components

- **Scene Requester**
- **Isaac Sim**
- **AmbientCG**
- **Meshy**
- **OpenAI**

## Connections

- Scene Requester → CLI: submits prompt (evidence: `README.md`)
- Scene Requester → MCP Server: requests generation (evidence: `README.md`)
- MCP Server → MCP Tools: serves tools (evidence: `articscene/mcp/server.py`)
- MCP Tools → Stage Pipeline: invokes workflow (evidence: `articscene/mcp/tools.py`)
- CLI → Stage Pipeline: starts generation
- Stage Pipeline → Runtime Configuration: uses configuration (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → LLM Providers: creates provider (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → Shell Design: runs stages (evidence: `README.md`)
- Stage Pipeline → Furniture Design: runs stages (evidence: `README.md`)
- Stage Pipeline → Physics Design: runs stages (evidence: `README.md`)
- Stage Pipeline → Scene Author: authors scene (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → Scene Review: runs stages (evidence: `README.md`)
- Stage Pipeline → Shared Scene State: hands off state (evidence: `articscene/pipeline/pipeline.py`)
- Shell Design → Shared Scene State: updates state (evidence: `articscene/core/scene_state.py`)
- Furniture Design → Shared Scene State: updates state (evidence: `articscene/core/scene_state.py`)
- Physics Design → Shared Scene State: updates state (evidence: `articscene/core/scene_state.py`)
- Scene Review → Shared Scene State: records verdict (evidence: `articscene/core/scene_state.py`)
- Shell Design → Designer Critic Loop: inherits loop
- Furniture Design → Designer Critic Loop: inherits loop (evidence: `articscene/agents/furniture/agent.py`)
- Physics Design → Designer Critic Loop: inherits loop (evidence: `articscene/agents/physics/agent.py`)
- Furniture Design → Articraft Catalog: retrieves assets (evidence: `articscene/agents/furniture/agent.py`)
- Physics Design → Articraft Catalog: inspects assets (evidence: `articscene/agents/physics/agent.py`)
- Scene Author → Shared Scene State: reads scene data (evidence: `articscene/mechanical/scene_author.py`)
- Scene Author → Room Composition: composes room (evidence: `articscene/mechanical/compose/room.py`)
- Scene Author → Articulated USD: authors articulated assets (evidence: `articscene/mechanical/scene_author.py`)
- Scene Author → Static Prop Authoring: authors props (evidence: `articscene/mechanical/scene_author.py`)
- Scene Author → Isaac Scene Composition: composes layers (evidence: `articscene/mechanical/scene_author.py`)
- Room Composition → Material Retrieval: uses material builder (evidence: `articscene/mechanical/compose/room.py`)
- Stage Pipeline → AmbientCG: resolves textures (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → Meshy: generates props (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → OpenAI: generates decal images (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → Session Layout: resolves session paths (evidence: `articscene/pipeline/pipeline.py`)
- Stage Pipeline → Session Persistence: persists session (evidence: `articscene/pipeline/pipeline.py`)
- Isaac Scene Composition → Isaac Sim: loads USD scene (evidence: `README.md`)