# sizzlins/redstone-mini architecture

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

## Overview

redstone-mini parses Boolean recipes, turns them into placed and routed Minecraft redstone circuits, verifies their behavior, and exports a preview or commands for Minecraft. The CLI is the documented entry point; a local editor offers a separate compile-and-preview route. The source index identifies the principal modules and their references, but several implementation excerpts are partial, so uncertain internal call relationships are omitted or marked unverified.

Main entry points: [`redstone_mini.py`](https://github.com/sizzlins/redstone-mini/blob/master/redstone_mini.py) (CLI entry), [`serve.py`](https://github.com/sizzlins/redstone-mini/blob/master/serve.py) (Editor server), [`sim.py`](https://github.com/sizzlins/redstone-mini/blob/master/sim.py) (Build and verify), [`layout.py`](https://github.com/sizzlins/redstone-mini/blob/master/layout.py) (Circuit layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Recipe input"]
  node_editor["Live editor<br/>[editor.html]"]
  node_server["Editor server<br/>[serve.py]"]
  node_cli["CLI entry<br/>[redstone_mini.py]"]
end

subgraph group_compiler["Circuit compiler"]
  node_parser["Recipe parser<br/>[recipe.py]"]
  node_layout["Circuit layout<br/>[layout.py]"]
  node_compose["Compositional backend<br/>[compose.py]"]
  node_tiles["Gate tiles<br/>[tiles.py]"]
  node_core["Shared primitives<br/>[core.py]"]
end

subgraph group_verification["Verification and diagnostics"]
  node_sim["Build and verify<br/>[sim.py]"]
  node_snapshot["Build snapshots<br/>[snapshot.py]"]
  node_debug["Layout diagnostics<br/>[debug.py]"]
end

subgraph group_outputs["Preview and export"]
  node_export["Build exporters<br/>[export.py]"]
end

node_user(("User"))
node_minecraft(("Minecraft world"))

node_user -->|"runs"| node_cli
node_user -->|"edits recipe"| node_editor
node_editor -->|"submits recipe"| node_server
node_cli -->|"parses recipe"| node_parser
node_cli -->|"builds and verifies"| node_sim
node_cli -->|"exports build"| node_export
node_cli -->|"starts editor"| node_server
node_server -->|"parses recipe"| node_parser
node_server -->|"builds and verifies"| node_sim
node_server -->|"renders preview"| node_export
node_sim -.->|"uses layout"| node_layout
node_sim -.->|"uses backend"| node_compose
node_layout -.->|"uses tile builders"| node_tiles
node_layout -->|"dumps layout state"| node_debug
node_sim -.->|"uses snapshots"| node_snapshot
node_export -->|"exports build commands"| node_minecraft

click node_editor "https://github.com/sizzlins/redstone-mini/blob/master/editor.html"
click node_server "https://github.com/sizzlins/redstone-mini/blob/master/serve.py"
click node_cli "https://github.com/sizzlins/redstone-mini/blob/master/redstone_mini.py"
click node_parser "https://github.com/sizzlins/redstone-mini/blob/master/recipe.py"
click node_sim "https://github.com/sizzlins/redstone-mini/blob/master/sim.py"
click node_layout "https://github.com/sizzlins/redstone-mini/blob/master/layout.py"
click node_compose "https://github.com/sizzlins/redstone-mini/blob/master/compose.py"
click node_tiles "https://github.com/sizzlins/redstone-mini/blob/master/tiles.py"
click node_core "https://github.com/sizzlins/redstone-mini/blob/master/core.py"
click node_snapshot "https://github.com/sizzlins/redstone-mini/blob/master/snapshot.py"
click node_debug "https://github.com/sizzlins/redstone-mini/blob/master/debug.py"
click node_export "https://github.com/sizzlins/redstone-mini/blob/master/export.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_editor,node_server,node_cli,node_user toneBlue
class node_parser,node_layout,node_compose,node_tiles,node_core toneAmber
class node_sim,node_snapshot,node_debug toneMint
class node_export toneRose
class node_minecraft toneIndigo
```

## Components

### Recipe input

- [Live editor](https://github.com/sizzlins/redstone-mini/blob/master/editor.html): `editor.html`
- [Editor server](https://github.com/sizzlins/redstone-mini/blob/master/serve.py): `serve.py`
- [CLI entry](https://github.com/sizzlins/redstone-mini/blob/master/redstone_mini.py): `redstone_mini.py`

### Circuit compiler

- [Recipe parser](https://github.com/sizzlins/redstone-mini/blob/master/recipe.py): `recipe.py`
- [Circuit layout](https://github.com/sizzlins/redstone-mini/blob/master/layout.py): `layout.py`
- [Compositional backend](https://github.com/sizzlins/redstone-mini/blob/master/compose.py): `compose.py`
- [Gate tiles](https://github.com/sizzlins/redstone-mini/blob/master/tiles.py): `tiles.py`
- [Shared primitives](https://github.com/sizzlins/redstone-mini/blob/master/core.py): `core.py`

### Verification and diagnostics

- [Build and verify](https://github.com/sizzlins/redstone-mini/blob/master/sim.py): `sim.py`
- [Build snapshots](https://github.com/sizzlins/redstone-mini/blob/master/snapshot.py): `snapshot.py`
- [Layout diagnostics](https://github.com/sizzlins/redstone-mini/blob/master/debug.py): `debug.py`

### Preview and export

- [Build exporters](https://github.com/sizzlins/redstone-mini/blob/master/export.py): `export.py`

### Other components

- **User**
- **Minecraft world**

## Connections

- User → CLI entry: runs (evidence: `README.md`)
- User → Live editor: edits recipe (evidence: `README.md`)
- Live editor → Editor server: submits recipe (evidence: `serve.py`)
- CLI entry → Recipe parser: parses recipe (evidence: `redstone_mini.py`)
- CLI entry → Build and verify: builds and verifies (evidence: `redstone_mini.py`)
- CLI entry → Build exporters: exports build (evidence: `redstone_mini.py`)
- CLI entry → Editor server: starts editor (evidence: `redstone_mini.py`)
- Editor server → Recipe parser: parses recipe (evidence: `serve.py`)
- Editor server → Build and verify: builds and verifies (evidence: `serve.py`)
- Editor server → Build exporters: renders preview (evidence: `serve.py`)
- Build and verify → Circuit layout: uses layout (evidence: `sim.py`)
- Build and verify → Compositional backend: uses backend (evidence: `sim.py`)
- Circuit layout → Gate tiles: uses tile builders (evidence: `layout.py`)
- Circuit layout → Layout diagnostics: dumps layout state (evidence: `debug.py`)
- Build and verify → Build snapshots: uses snapshots (evidence: `sim.py`)
- Build exporters → Minecraft world: exports build commands (evidence: `README.md`)