# matthew-kissinger/kiln architecture

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

- Interactive diagram: https://gitdiagram.com/matthew-kissinger/kiln
- Repository: https://github.com/matthew-kissinger/kiln

## Overview

Kiln is a local toolkit for creating and revising procedural 3D assets with a coding agent. The main loop is agent-authored JavaScript, execution into an asset, rendered views and structural checks for review, then GLB export; source can be retained and edited through immutable revisions. CLI and MCP expose the engine, while Discovery, optional requirements, animation review, scene composition, and the interactive asset viewer are distinct capabilities. README workflow descriptions guide the high-level links; sampled source confirms selected module responsibilities, but not every connection between subsystems.

Main entry points: [`src/agent/run.ts`](https://github.com/matthew-kissinger/kiln/blob/main/src/agent/run.ts) (Agent tool loop), [`src/evaluator/index.ts`](https://github.com/matthew-kissinger/kiln/blob/main/src/evaluator/index.ts) (Program evaluator), [`src/views/index.ts`](https://github.com/matthew-kissinger/kiln/blob/main/src/views/index.ts) (View capture), [`src/cli.ts`](https://github.com/matthew-kissinger/kiln/blob/main/src/cli.ts) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP server<br/>[mcp-server.ts]"]
end

subgraph group_authoring["Authoring and discovery"]
  node_discovery["Helper discovery<br/>[service.ts]"]
  node_agentloop["Agent tool loop<br/>[run.ts]"]
  node_toolregistry["Tool registry<br/>[registry.ts]"]
  node_programtools["Program tools<br/>[programs.ts]"]
end

subgraph group_asset["Asset construction"]
  node_evaluator["Program evaluator<br/>[index.ts]"]
  node_geometry["Geometry helpers<br/>[geometry.ts]"]
  node_materials["Material recipes"]
  node_composer["Scene composer<br/>[index.ts]"]
end

subgraph group_review["Review and rendering"]
  node_views["View capture<br/>[index.ts]"]
  node_qa["Structural checks<br/>[index.ts]"]
  node_animation["Animation review<br/>[animation-cli.ts]"]
  node_renderclient["Render service client"]
  node_renderhost["Render service<br/>[server.mjs]"]
end

subgraph group_outputs["Revision and delivery"]
  node_programstore[("Program revisions<br/>[program-store.ts]")]
  node_edit["Anchored editing<br/>[edit-cli.ts]"]
  node_export["GLB exporter<br/>[asset-export.ts]"]
  node_viewer["Asset viewer<br/>[app.ts]"]
  node_gallery["Web gallery<br/>[App.tsx]"]
end

node_agent(("Coding agent"))

node_agent -->|"invokes"| node_cli
node_agent -->|"invokes tools"| node_mcp
node_cli -->|"queries helpers"| node_discovery
node_mcp -->|"queries helpers"| node_discovery
node_agent -->|"authors asset"| node_agentloop
node_agentloop -->|"uses tools"| node_toolregistry
node_toolregistry -->|"dispatches"| node_programtools
node_programtools -->|"runs program"| node_evaluator
node_evaluator -->|"evaluates helpers"| node_geometry
node_evaluator -->|"evaluates helpers"| node_materials
node_evaluator -.->|"evaluates scenes"| node_composer
node_agentloop -->|"requests views"| node_views
node_views -->|"renders program"| node_evaluator
node_views -->|"requests rendering"| node_renderclient
node_renderclient -->|"sends render request"| node_renderhost
node_agentloop -->|"checks asset"| node_qa
node_agentloop -.->|"reviews animation"| node_animation
node_agentloop -->|"stores source"| node_programstore
node_agent -->|"requests edits"| node_edit
node_edit -->|"reads revisions"| node_programstore
node_agentloop -->|"exports asset"| node_export
node_export -->|"provides GLB"| node_viewer
node_gallery -->|"opens specimen"| node_viewer

click node_cli "https://github.com/matthew-kissinger/kiln/blob/main/src/cli.ts"
click node_mcp "https://github.com/matthew-kissinger/kiln/blob/main/src/mcp-server.ts"
click node_discovery "https://github.com/matthew-kissinger/kiln/blob/main/src/discovery/service.ts"
click node_agentloop "https://github.com/matthew-kissinger/kiln/blob/main/src/agent/run.ts"
click node_toolregistry "https://github.com/matthew-kissinger/kiln/blob/main/src/tools/registry.ts"
click node_programtools "https://github.com/matthew-kissinger/kiln/blob/main/src/tools/programs.ts"
click node_evaluator "https://github.com/matthew-kissinger/kiln/blob/main/src/evaluator/index.ts"
click node_geometry "https://github.com/matthew-kissinger/kiln/blob/main/src/geometry.ts"
click node_materials "https://github.com/matthew-kissinger/kiln/blob/main/src/material-recipes.ts"
click node_composer "https://github.com/matthew-kissinger/kiln/blob/main/src/composer/index.ts"
click node_views "https://github.com/matthew-kissinger/kiln/blob/main/src/views/index.ts"
click node_qa "https://github.com/matthew-kissinger/kiln/blob/main/src/qa/index.ts"
click node_animation "https://github.com/matthew-kissinger/kiln/blob/main/src/animation-cli.ts"
click node_renderclient "https://github.com/matthew-kissinger/kiln/blob/main/src/render-service-client.ts"
click node_renderhost "https://github.com/matthew-kissinger/kiln/blob/main/render-service/src/server.mjs"
click node_programstore "https://github.com/matthew-kissinger/kiln/blob/main/src/program-store.ts"
click node_edit "https://github.com/matthew-kissinger/kiln/blob/main/src/edit-cli.ts"
click node_export "https://github.com/matthew-kissinger/kiln/blob/main/src/asset-export.ts"
click node_viewer "https://github.com/matthew-kissinger/kiln/blob/main/src/viewer/app.ts"
click node_gallery "https://github.com/matthew-kissinger/kiln/blob/main/site/src/App.tsx"

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 toneBlue
class node_discovery,node_agentloop,node_toolregistry,node_programtools toneAmber
class node_evaluator,node_geometry,node_materials,node_composer toneMint
class node_views,node_qa,node_animation,node_renderclient,node_renderhost toneRose
class node_programstore,node_edit,node_export,node_viewer,node_gallery,node_agent toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/matthew-kissinger/kiln/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/matthew-kissinger/kiln/blob/main/src/mcp-server.ts): `src/mcp-server.ts`

### Authoring and discovery

- [Helper discovery](https://github.com/matthew-kissinger/kiln/blob/main/src/discovery/service.ts): `src/discovery/service.ts`
- [Agent tool loop](https://github.com/matthew-kissinger/kiln/blob/main/src/agent/run.ts): `src/agent/run.ts`
- [Tool registry](https://github.com/matthew-kissinger/kiln/blob/main/src/tools/registry.ts): `src/tools/registry.ts`
- [Program tools](https://github.com/matthew-kissinger/kiln/blob/main/src/tools/programs.ts): `src/tools/programs.ts`

### Asset construction

- [Program evaluator](https://github.com/matthew-kissinger/kiln/blob/main/src/evaluator/index.ts): `src/evaluator/index.ts`
- [Geometry helpers](https://github.com/matthew-kissinger/kiln/blob/main/src/geometry.ts): `src/geometry.ts`
- [Material recipes](https://github.com/matthew-kissinger/kiln/blob/main/src/material-recipes.ts): `src/material-recipes.ts`
- [Scene composer](https://github.com/matthew-kissinger/kiln/blob/main/src/composer/index.ts): `src/composer/index.ts`

### Review and rendering

- [View capture](https://github.com/matthew-kissinger/kiln/blob/main/src/views/index.ts): `src/views/index.ts`
- [Structural checks](https://github.com/matthew-kissinger/kiln/blob/main/src/qa/index.ts): `src/qa/index.ts`
- [Animation review](https://github.com/matthew-kissinger/kiln/blob/main/src/animation-cli.ts): `src/animation-cli.ts`
- [Render service client](https://github.com/matthew-kissinger/kiln/blob/main/src/render-service-client.ts): `src/render-service-client.ts`
- [Render service](https://github.com/matthew-kissinger/kiln/blob/main/render-service/src/server.mjs): `render-service/src/server.mjs`

### Revision and delivery

- [Program revisions](https://github.com/matthew-kissinger/kiln/blob/main/src/program-store.ts): `src/program-store.ts`
- [Anchored editing](https://github.com/matthew-kissinger/kiln/blob/main/src/edit-cli.ts): `src/edit-cli.ts`
- [GLB exporter](https://github.com/matthew-kissinger/kiln/blob/main/src/asset-export.ts): `src/asset-export.ts`
- [Asset viewer](https://github.com/matthew-kissinger/kiln/blob/main/src/viewer/app.ts): `src/viewer/app.ts`
- [Web gallery](https://github.com/matthew-kissinger/kiln/blob/main/site/src/App.tsx): `site/src/App.tsx`

### Other components

- **Coding agent**

## Connections

- Coding agent → CLI: invokes
- Coding agent → MCP server: invokes tools
- CLI → Helper discovery: queries helpers
- MCP server → Helper discovery: queries helpers
- Coding agent → Agent tool loop: authors asset
- Agent tool loop → Tool registry: uses tools
- Tool registry → Program tools: dispatches
- Program tools → Program evaluator: runs program
- Program evaluator → Geometry helpers: evaluates helpers
- Program evaluator → Material recipes: evaluates helpers
- Program evaluator → Scene composer: evaluates scenes
- Agent tool loop → View capture: requests views
- View capture → Program evaluator: renders program
- View capture → Render service client: requests rendering
- Render service client → Render service: sends render request
- Agent tool loop → Structural checks: checks asset
- Agent tool loop → Animation review: reviews animation
- Agent tool loop → Program revisions: stores source
- Coding agent → Anchored editing: requests edits
- Anchored editing → Program revisions: reads revisions
- Agent tool loop → GLB exporter: exports asset
- GLB exporter → Asset viewer: provides GLB
- Web gallery → Asset viewer: opens specimen