# mattzh72/articraft architecture

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

## Overview

Articraft turns a prompt (optionally with a reference image) into an articulated 3D record, then exposes records through a browser-based viewer. The principal path is CLI → agent run and tool loop → model code using the SDK → compiled/persisted record; users can also fork/edit records and inspect library metadata, runs, trajectories, and geometry. The README documents generation, editing, library maintenance, and viewing; SOURCE INDEX references support several internal links. Unsampled implementations are represented only at the exact paths available in the tree, with uncertain wiring omitted.

Main entry points: [`agent/harness.py`](https://github.com/mattzh72/articraft/blob/main/agent/harness.py) (Generation harness), [`viewer/web/src/App.tsx`](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/App.tsx) (Viewer application), [`storage/repo.py`](https://github.com/mattzh72/articraft/blob/main/storage/repo.py) (Record repository), [`agent/runner.py`](https://github.com/mattzh72/articraft/blob/main/agent/runner.py) (Agent runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Generation agent"]
  node_runner["Agent runner<br/>[runner.py]"]
  node_harness["Generation harness<br/>[harness.py]"]
  node_prompts["Prompt loading<br/>[loader.py]"]
  node_provider["Provider selection<br/>[factory.py]"]
  node_llm["LLM providers"]
  node_tools["Agent tools"]
  node_feedback["Feedback and evaluation<br/>[feedback.py]"]
end

subgraph group_modeling["3D modeling"]
  node_sdk["Articulated asset SDK"]
  node_cadquery["CadQuery extension<br/>[cadquery.py]"]
  node_compile["Model compilation<br/>[compiler.py]"]
end

subgraph group_records["Records and library"]
  node_storage[("Record repository<br/>[repo.py]")]
  node_revisions["Revision history<br/>[revisions.py]"]
  node_manifest["Library manifest"]
  node_persistence["Run persistence"]
end

subgraph group_viewer["Viewer"]
  node_api["Viewer API<br/>[app.py]"]
  node_routes["Record and run routes"]
  node_geometry["3D scene loader<br/>[useUrdfLoader.ts]"]
  node_urdf["URDF parser<br/>[urdf-parser.ts]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Articraft CLI<br/>[main.py]"]
  node_web["Viewer application<br/>[App.tsx]"]
  node_browser["Record browser<br/>[RecordBrowser.tsx]"]
  node_inspector["Asset inspector<br/>[InspectPanel.tsx]"]
end

node_user(("User"))
node_model_scripts["Generated model code"]
node_provider_service(("Model provider service"))

node_user -->|"requests generation"| node_cli
node_cli -->|"starts run"| node_runner
node_runner -.->|"runs agent"| node_harness
node_harness -->|"loads prompts"| node_prompts
node_harness -->|"selects provider"| node_provider
node_provider -->|"creates client"| node_llm
node_llm -.->|"sends requests"| node_provider_service
node_harness -->|"dispatches tools"| node_tools
node_tools -->|"edits and checks"| node_model_scripts
node_model_scripts -->|"builds asset"| node_sdk
node_sdk -.->|"optional extension"| node_cadquery
node_tools -.->|"compiles model"| node_compile
node_harness -->|"records feedback"| node_feedback
node_runner -.->|"saves run"| node_persistence
node_persistence -.->|"writes records"| node_storage
node_storage -->|"tracks revisions"| node_revisions
node_storage -->|"indexes library"| node_manifest
node_user -->|"browses assets"| node_web
node_web -.->|"requests data"| node_api
node_api -->|"registers routes"| node_routes
node_routes -.->|"reads records"| node_storage
node_web -.->|"renders browser"| node_browser
node_web -.->|"renders inspector"| node_inspector
node_inspector -.->|"loads geometry"| node_geometry
node_geometry -->|"parses URDF"| node_urdf

click node_cli "https://github.com/mattzh72/articraft/blob/main/cli/main.py"
click node_runner "https://github.com/mattzh72/articraft/blob/main/agent/runner.py"
click node_harness "https://github.com/mattzh72/articraft/blob/main/agent/harness.py"
click node_prompts "https://github.com/mattzh72/articraft/blob/main/agent/prompts/loader.py"
click node_provider "https://github.com/mattzh72/articraft/blob/main/agent/providers/factory.py"
click node_llm "https://github.com/mattzh72/articraft/tree/main/agent/providers"
click node_tools "https://github.com/mattzh72/articraft/tree/main/agent/tools"
click node_feedback "https://github.com/mattzh72/articraft/blob/main/agent/feedback.py"
click node_sdk "https://github.com/mattzh72/articraft/tree/main/sdk/v0"
click node_cadquery "https://github.com/mattzh72/articraft/blob/main/sdk/_extensions/cadquery/v0/cadquery.py"
click node_compile "https://github.com/mattzh72/articraft/blob/main/agent/compiler.py"
click node_storage "https://github.com/mattzh72/articraft/blob/main/storage/repo.py"
click node_revisions "https://github.com/mattzh72/articraft/blob/main/storage/revisions.py"
click node_manifest "https://github.com/mattzh72/articraft/blob/main/storage/library_manifest.py"
click node_persistence "https://github.com/mattzh72/articraft/blob/main/agent/record_persistence.py"
click node_api "https://github.com/mattzh72/articraft/blob/main/viewer/api/app.py"
click node_routes "https://github.com/mattzh72/articraft/tree/main/viewer/api/routes"
click node_web "https://github.com/mattzh72/articraft/blob/main/viewer/web/src/App.tsx"
click node_browser "https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/browser/RecordBrowser.tsx"
click node_inspector "https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/inspector/InspectPanel.tsx"
click node_geometry "https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/viewer3d/useUrdfLoader.ts"
click node_urdf "https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/viewer3d/urdf-parser.ts"

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_runner,node_harness,node_prompts,node_provider,node_llm,node_tools,node_feedback,node_user toneBlue
class node_sdk,node_cadquery,node_compile toneAmber
class node_storage,node_revisions,node_manifest,node_persistence toneMint
class node_api,node_routes,node_geometry,node_urdf toneRose
class node_cli,node_web,node_browser,node_inspector,node_model_scripts,node_provider_service toneIndigo
```

## Components

### Generation agent

- [Agent runner](https://github.com/mattzh72/articraft/blob/main/agent/runner.py): `agent/runner.py`
- [Generation harness](https://github.com/mattzh72/articraft/blob/main/agent/harness.py): `agent/harness.py`
- [Prompt loading](https://github.com/mattzh72/articraft/blob/main/agent/prompts/loader.py): `agent/prompts/loader.py`
- [Provider selection](https://github.com/mattzh72/articraft/blob/main/agent/providers/factory.py): `agent/providers/factory.py`
- [LLM providers](https://github.com/mattzh72/articraft/tree/main/agent/providers): `agent/providers`
- [Agent tools](https://github.com/mattzh72/articraft/tree/main/agent/tools): `agent/tools`
- [Feedback and evaluation](https://github.com/mattzh72/articraft/blob/main/agent/feedback.py): `agent/feedback.py`

### 3D modeling

- [Articulated asset SDK](https://github.com/mattzh72/articraft/tree/main/sdk/v0): `sdk/v0`
- [CadQuery extension](https://github.com/mattzh72/articraft/blob/main/sdk/_extensions/cadquery/v0/cadquery.py): `sdk/_extensions/cadquery/v0/cadquery.py`
- [Model compilation](https://github.com/mattzh72/articraft/blob/main/agent/compiler.py): `agent/compiler.py`

### Records and library

- [Record repository](https://github.com/mattzh72/articraft/blob/main/storage/repo.py): `storage/repo.py`
- [Revision history](https://github.com/mattzh72/articraft/blob/main/storage/revisions.py): `storage/revisions.py`
- [Library manifest](https://github.com/mattzh72/articraft/blob/main/storage/library_manifest.py): `storage/library_manifest.py`
- [Run persistence](https://github.com/mattzh72/articraft/blob/main/agent/record_persistence.py): `agent/record_persistence.py`

### Viewer

- [Viewer API](https://github.com/mattzh72/articraft/blob/main/viewer/api/app.py): `viewer/api/app.py`
- [Record and run routes](https://github.com/mattzh72/articraft/tree/main/viewer/api/routes): `viewer/api/routes`
- [3D scene loader](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/viewer3d/useUrdfLoader.ts): `viewer/web/src/components/viewer3d/useUrdfLoader.ts`
- [URDF parser](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/viewer3d/urdf-parser.ts): `viewer/web/src/components/viewer3d/urdf-parser.ts`

### User interfaces

- [Articraft CLI](https://github.com/mattzh72/articraft/blob/main/cli/main.py): `cli/main.py`
- [Viewer application](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/App.tsx): `viewer/web/src/App.tsx`
- [Record browser](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/browser/RecordBrowser.tsx): `viewer/web/src/components/browser/RecordBrowser.tsx`
- [Asset inspector](https://github.com/mattzh72/articraft/blob/main/viewer/web/src/components/inspector/InspectPanel.tsx): `viewer/web/src/components/inspector/InspectPanel.tsx`

### Other components

- **User**
- **Generated model code**
- **Model provider service**

## Connections

- User → Articraft CLI: requests generation (evidence: `README.md`)
- Articraft CLI → Agent runner: starts run (evidence: `cli/main.py`)
- Agent runner → Generation harness: runs agent
- Generation harness → Prompt loading: loads prompts (evidence: `agent/harness.py`)
- Generation harness → Provider selection: selects provider (evidence: `agent/harness.py`)
- Provider selection → LLM providers: creates client (evidence: `agent/providers/factory.py`)
- LLM providers → Model provider service: sends requests
- Generation harness → Agent tools: dispatches tools (evidence: `agent/harness.py`)
- Agent tools → Generated model code: edits and checks (evidence: `agent/tools/__init__.py`)
- Generated model code → Articulated asset SDK: builds asset (evidence: `README.md`)
- Articulated asset SDK → CadQuery extension: optional extension (evidence: `sdk/_extensions/cadquery/v0/cadquery.py`)
- Agent tools → Model compilation: compiles model
- Generation harness → Feedback and evaluation: records feedback (evidence: `agent/harness.py`)
- Agent runner → Run persistence: saves run
- Run persistence → Record repository: writes records
- Record repository → Revision history: tracks revisions (evidence: `storage/revisions.py`)
- Record repository → Library manifest: indexes library (evidence: `storage/library_manifest.py`)
- User → Viewer application: browses assets (evidence: `README.md`)
- Viewer application → Viewer API: requests data
- Viewer API → Record and run routes: registers routes (evidence: `viewer/api/app.py`)
- Record and run routes → Record repository: reads records
- Viewer application → Record browser: renders browser
- Viewer application → Asset inspector: renders inspector
- Asset inspector → 3D scene loader: loads geometry
- 3D scene loader → URDF parser: parses URDF (evidence: `viewer/web/src/components/viewer3d/useUrdfLoader.ts`)
