# augustzhang1/ai-builder-minecraft architecture

> Architecture diagram of the GitHub repository augustzhang1/ai-builder-minecraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/augustzhang1/ai-builder-minecraft
- Repository: https://github.com/augustzhang1/ai-builder-minecraft

## Overview

AI-Builder-Minecraft is a separate Python service that turns Minecraft chat commands into AI-designed or image-derived block builds, previews them, and places them through RCON. The graph preserves the documented design/render/voxelize/preview/place workflow and major command families. The README and source index support the main orchestration links; some specialized internal handoffs are not visible in the sampled excerpts and are left unconnected or marked unverified.

Main entry points: [`mcmcp/main.py`](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/main.py) (Command orchestrator), [`mcmcp/edit_prompt.py`](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_prompt.py) (AI build edits), [`mcmcp/build.py`](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/build.py) (Mesh voxelizer), [`mcmcp/interior.py`](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/interior.py) (Interior analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["Command Service"]
  node_main["Command orchestrator<br/>[main.py]"]
  node_config["Settings<br/>[config.py]"]
end

subgraph group_design["Design and Geometry"]
  node_ai["AI design and review<br/>[llm.py]"]
  node_openscad["OpenSCAD renderer"]
  node_voxel["Mesh voxelizer<br/>[build.py]"]
  node_preview["Build preview<br/>[preview.py]"]
  node_figure["Figure posing and color<br/>[figure.py]"]
end

subgraph group_editing["Build Editing"]
  node_interior["Interior analysis<br/>[interior.py]"]
  node_edit["AI build edits<br/>[edit_prompt.py]"]
  node_editops["Edit operations<br/>[edit_ops.py]"]
  node_undo["Edit undo<br/>[edit_undo.py]"]
  node_region["World region reader<br/>[region.py]"]
end

subgraph group_media["Image and Statue"]
  node_pixelart["Pixel-art converter<br/>[pixelart.py]"]
  node_statue["Statue generation<br/>[statue.py]"]
  node_statuegrid["Statue voxelizer<br/>[statue_grid.py]"]
  node_eyes["Face and eye coloring<br/>[statue_eyes.py]"]
end

subgraph group_world["World Interaction"]
  node_saves[("Saved designs<br/>[saves.py]")]
  node_schem["Schematic export<br/>[schem.py]"]
  node_rcon["RCON client<br/>[rcon.py]"]
  node_animation["Build animation<br/>[animate.py]"]
  node_ghost["Preview hologram<br/>[ghost.py]"]
end

node_operator(("Minecraft operator"))
node_minecraft["Minecraft server"]

node_operator -->|"sends commands"| node_main
node_main -->|"requests design"| node_ai
node_main -->|"renders and voxelizes"| node_voxel
node_voxel -->|"renders meshes"| node_openscad
node_main -->|"shows preview"| node_preview
node_main -->|"sends game commands"| node_rcon
node_rcon -->|"executes commands"| node_minecraft
node_main -->|"reads settings"| node_config
node_main -->|"poses figures"| node_figure
node_main -->|"requests furnishing"| node_interior
node_main -->|"requests edits"| node_edit
node_main -->|"applies edits"| node_editops
node_main -->|"undoes edits"| node_undo
node_main -->|"reads build region"| node_region
node_interior -->|"stamps details"| node_voxel
node_edit -->|"requests changes"| node_ai
node_edit -->|"uses analysis"| node_interior
node_edit -->|"renders edit views"| node_preview
node_main -->|"converts image"| node_pixelart
node_main -->|"requests statue"| node_statue
node_statue -.->|"voxelizes mesh"| node_statuegrid
node_statuegrid -->|"paints statue eyes"| node_eyes
node_main -->|"saves and loads"| node_saves
node_main -->|"exports schematic"| node_schem
node_main -->|"animates building"| node_animation
node_animation -->|"sends game commands"| node_rcon
node_main -->|"manages hologram"| node_ghost

click node_main "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/main.py"
click node_config "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/config.py"
click node_ai "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/llm.py"
click node_voxel "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/build.py"
click node_preview "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/preview.py"
click node_figure "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/figure.py"
click node_interior "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/interior.py"
click node_edit "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_prompt.py"
click node_editops "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_ops.py"
click node_undo "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_undo.py"
click node_region "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/region.py"
click node_pixelart "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/pixelart.py"
click node_statue "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue.py"
click node_statuegrid "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue_grid.py"
click node_eyes "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue_eyes.py"
click node_saves "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/saves.py"
click node_schem "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/schem.py"
click node_rcon "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/rcon.py"
click node_animation "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/animate.py"
click node_ghost "https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/ghost.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_main,node_config toneBlue
class node_ai,node_openscad,node_voxel,node_preview,node_figure toneAmber
class node_interior,node_edit,node_editops,node_undo,node_region,node_minecraft toneMint
class node_pixelart,node_statue,node_statuegrid,node_eyes toneRose
class node_saves,node_schem,node_rcon,node_animation,node_ghost,node_operator toneIndigo
```

## Components

### Command Service

- [Command orchestrator](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/main.py): `mcmcp/main.py`
- [Settings](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/config.py): `mcmcp/config.py`

### Design and Geometry

- [AI design and review](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/llm.py): `mcmcp/llm.py`
- **OpenSCAD renderer**
- [Mesh voxelizer](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/build.py): `mcmcp/build.py`
- [Build preview](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/preview.py): `mcmcp/preview.py`
- [Figure posing and color](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/figure.py): `mcmcp/figure.py`

### Build Editing

- [Interior analysis](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/interior.py): `mcmcp/interior.py`
- [AI build edits](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_prompt.py): `mcmcp/edit_prompt.py`
- [Edit operations](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_ops.py): `mcmcp/edit_ops.py`
- [Edit undo](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/edit_undo.py): `mcmcp/edit_undo.py`
- [World region reader](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/region.py): `mcmcp/region.py`

### Image and Statue

- [Pixel-art converter](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/pixelart.py): `mcmcp/pixelart.py`
- [Statue generation](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue.py): `mcmcp/statue.py`
- [Statue voxelizer](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue_grid.py): `mcmcp/statue_grid.py`
- [Face and eye coloring](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/statue_eyes.py): `mcmcp/statue_eyes.py`

### World Interaction

- [Saved designs](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/saves.py): `mcmcp/saves.py`
- [Schematic export](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/schem.py): `mcmcp/schem.py`
- [RCON client](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/rcon.py): `mcmcp/rcon.py`
- [Build animation](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/animate.py): `mcmcp/animate.py`
- [Preview hologram](https://github.com/augustzhang1/ai-builder-minecraft/blob/main/mcmcp/ghost.py): `mcmcp/ghost.py`

### Other components

- **Minecraft operator**
- **Minecraft server**

## Connections

- Minecraft operator → Command orchestrator: sends commands (evidence: `README.md`)
- Command orchestrator → AI design and review: requests design (evidence: `README.md`)
- Command orchestrator → Mesh voxelizer: renders and voxelizes (evidence: `README.md`)
- Mesh voxelizer → OpenSCAD renderer: renders meshes (evidence: `mcmcp/build.py`)
- Command orchestrator → Build preview: shows preview (evidence: `README.md`)
- Command orchestrator → RCON client: sends game commands (evidence: `README.md`)
- RCON client → Minecraft server: executes commands (evidence: `README.md`)
- Command orchestrator → Settings: reads settings (evidence: `mcmcp/main.py`)
- Command orchestrator → Figure posing and color: poses figures (evidence: `mcmcp/main.py`)
- Command orchestrator → Interior analysis: requests furnishing (evidence: `mcmcp/main.py`)
- Command orchestrator → AI build edits: requests edits (evidence: `mcmcp/main.py`)
- Command orchestrator → Edit operations: applies edits (evidence: `mcmcp/main.py`)
- Command orchestrator → Edit undo: undoes edits (evidence: `mcmcp/main.py`)
- Command orchestrator → World region reader: reads build region (evidence: `mcmcp/main.py`)
- Interior analysis → Mesh voxelizer: stamps details (evidence: `mcmcp/interior.py`)
- AI build edits → AI design and review: requests changes (evidence: `mcmcp/edit_prompt.py`)
- AI build edits → Interior analysis: uses analysis (evidence: `mcmcp/edit_prompt.py`)
- AI build edits → Build preview: renders edit views (evidence: `mcmcp/edit_prompt.py`)
- Command orchestrator → Pixel-art converter: converts image (evidence: `mcmcp/main.py`)
- Command orchestrator → Statue generation: requests statue (evidence: `mcmcp/main.py`)
- Statue generation → Statue voxelizer: voxelizes mesh
- Statue voxelizer → Face and eye coloring: paints statue eyes (evidence: `mcmcp/statue_grid.py`)
- Command orchestrator → Saved designs: saves and loads (evidence: `mcmcp/main.py`)
- Command orchestrator → Schematic export: exports schematic (evidence: `mcmcp/main.py`)
- Command orchestrator → Build animation: animates building (evidence: `mcmcp/main.py`)
- Build animation → RCON client: sends game commands (evidence: `mcmcp/animate.py`)
- Command orchestrator → Preview hologram: manages hologram (evidence: `mcmcp/main.py`)
