# anteloc/ldraw-nova architecture

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

- Interactive diagram: https://gitdiagram.com/anteloc/ldraw-nova
- Repository: https://github.com/anteloc/ldraw-nova

## Overview

ldraw-nova is agent-oriented Python tooling for creating and reviewing LEGO models in LDraw. Its principal workflow is an agent planning a model, producing and executing a generator, and delivering LDraw source; the README describes this workflow, while the sampled code shows assembly-plan building and validation components. Separate capabilities include part and example discovery, geometry/connectivity checks, flexible-element synthesis and review, and vehicle/Technic workflows. The web app and rendering infrastructure are described as sibling-repository capabilities, not implemented in this tree. Source excerpts are partial, so uncertain runtime links are omitted.

Main entry points: [`ldraw_tools/builder.py`](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/builder.py) (Plan builder), [`ldraw_tools/discovery.py`](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/discovery.py) (Part and model discovery), [`ldraw_tools/connectivity.py`](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/connectivity.py) (Connection analysis), [`ldraw_tools/flex.py`](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex.py) (Flex synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Model authoring"]
  node_cli["Agent tools CLI<br/>[cli.py]"]
  node_plan["Assembly plan"]
  node_builder["Plan builder<br/>[builder.py]"]
  node_ldraw["LDraw model"]
  node_document["Model documents<br/>[document.py]"]
  node_validation["Source validation<br/>[validation.py]"]
end

subgraph group_discovery["Discovery and references"]
  node_discovery["Part and model discovery<br/>[discovery.py]"]
  node_catalog["Part catalog<br/>[catalog.py]"]
  node_knowledge["Building knowledge<br/>[knowledge.py]"]
  node_manuals["Build manuals<br/>[manuals.py]"]
  node_categories[("Part categories")]
end

subgraph group_engineering["Geometry and review"]
  node_connectivity["Connection analysis<br/>[connectivity.py]"]
  node_geometry["Geometry analysis<br/>[geometry.py]"]
  node_collision["Collision checks<br/>[collision.py]"]
  node_technic["Technic review<br/>[technic_review.py]"]
end

subgraph group_specialized["Specialized workflows"]
  node_flex_authoring["Flex constraints<br/>[flex_authoring.py]"]
  node_flex["Flex synthesis<br/>[flex.py]"]
  node_flex_review["Flex review<br/>[flex_review.py]"]
  node_vehicle_review["Vehicle review<br/>[vehicle_review.py]"]
  node_external{{"LSynth engine"}}
end

node_agent(("AI agent"))

node_agent -->|"produces"| node_plan
node_plan -->|"builds from"| node_builder
node_builder -->|"generates"| node_ldraw
node_agent -->|"finds parts"| node_discovery
node_agent -->|"finds examples"| node_discovery
node_cli -->|"invokes"| node_builder
node_cli -->|"invokes"| node_discovery
node_builder -->|"parses sources"| node_document
node_builder -->|"snaps placements"| node_connectivity
node_document -->|"uses validation"| node_validation
node_discovery -->|"inspects models"| node_document
node_discovery -->|"uses catalog"| node_catalog
node_manuals -->|"uses builder"| node_builder
node_manuals -->|"uses discovery"| node_discovery
node_knowledge -->|"uses manuals"| node_manuals
node_geometry -->|"uses connection data"| node_connectivity
node_connectivity -->|"checks collisions"| node_collision
node_connectivity -->|"reviews placements"| node_technic
node_flex_authoring -->|"writes constraints"| node_flex
node_flex -->|"dispatches synthesis"| node_external
node_flex_review -->|"reads flex engine"| node_flex
node_vehicle_review -->|"uses geometry"| node_geometry
node_agent -->|"checks structure"| node_technic
node_agent -.->|"builds flex parts"| node_flex
node_agent -->|"builds vehicles"| node_vehicle_review

click node_cli "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/cli.py"
click node_builder "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/builder.py"
click node_document "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/document.py"
click node_validation "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/validation.py"
click node_discovery "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/discovery.py"
click node_catalog "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/catalog.py"
click node_knowledge "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/knowledge.py"
click node_manuals "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/manuals.py"
click node_categories "https://github.com/anteloc/ldraw-nova/tree/master/data/categories/parts"
click node_connectivity "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/connectivity.py"
click node_geometry "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/geometry.py"
click node_collision "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/collision.py"
click node_technic "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/technic_review.py"
click node_flex_authoring "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex_authoring.py"
click node_flex "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex.py"
click node_flex_review "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex_review.py"
click node_vehicle_review "https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/vehicle_review.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_plan,node_builder,node_ldraw,node_document,node_validation toneBlue
class node_discovery,node_catalog,node_knowledge,node_manuals,node_categories toneAmber
class node_connectivity,node_geometry,node_collision,node_technic toneMint
class node_flex_authoring,node_flex,node_flex_review,node_vehicle_review,node_external toneRose
class node_agent toneIndigo
```

## Components

### Model authoring

- [Agent tools CLI](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/cli.py): `ldraw_tools/cli.py`
- **Assembly plan**
- [Plan builder](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/builder.py): `ldraw_tools/builder.py`
- **LDraw model**
- [Model documents](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/document.py): `ldraw_tools/document.py`
- [Source validation](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/validation.py): `ldraw_tools/validation.py`

### Discovery and references

- [Part and model discovery](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/discovery.py): `ldraw_tools/discovery.py`
- [Part catalog](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/catalog.py): `ldraw_tools/catalog.py`
- [Building knowledge](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/knowledge.py): `ldraw_tools/knowledge.py`
- [Build manuals](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/manuals.py): `ldraw_tools/manuals.py`
- [Part categories](https://github.com/anteloc/ldraw-nova/tree/master/data/categories/parts): `data/categories/parts`

### Geometry and review

- [Connection analysis](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/connectivity.py): `ldraw_tools/connectivity.py`
- [Geometry analysis](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/geometry.py): `ldraw_tools/geometry.py`
- [Collision checks](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/collision.py): `ldraw_tools/collision.py`
- [Technic review](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/technic_review.py): `ldraw_tools/technic_review.py`

### Specialized workflows

- [Flex constraints](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex_authoring.py): `ldraw_tools/flex_authoring.py`
- [Flex synthesis](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex.py): `ldraw_tools/flex.py`
- [Flex review](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/flex_review.py): `ldraw_tools/flex_review.py`
- [Vehicle review](https://github.com/anteloc/ldraw-nova/blob/master/ldraw_tools/vehicle_review.py): `ldraw_tools/vehicle_review.py`
- **LSynth engine**

### Other components

- **AI agent**

## Connections

- AI agent → Assembly plan: produces
- Assembly plan → Plan builder: builds from
- Plan builder → LDraw model: generates
- AI agent → Part and model discovery: finds parts
- AI agent → Part and model discovery: finds examples
- Agent tools CLI → Plan builder: invokes (evidence: `ldraw_tools/cli.py`)
- Agent tools CLI → Part and model discovery: invokes (evidence: `ldraw_tools/cli.py`)
- Plan builder → Model documents: parses sources (evidence: `ldraw_tools/builder.py`)
- Plan builder → Connection analysis: snaps placements (evidence: `ldraw_tools/builder.py`)
- Model documents → Source validation: uses validation (evidence: `ldraw_tools/document.py`)
- Part and model discovery → Model documents: inspects models (evidence: `ldraw_tools/discovery.py`)
- Part and model discovery → Part catalog: uses catalog (evidence: `ldraw_tools/discovery.py`)
- Build manuals → Plan builder: uses builder (evidence: `ldraw_tools/manuals.py`)
- Build manuals → Part and model discovery: uses discovery (evidence: `ldraw_tools/manuals.py`)
- Building knowledge → Build manuals: uses manuals (evidence: `ldraw_tools/knowledge.py`)
- Geometry analysis → Connection analysis: uses connection data (evidence: `ldraw_tools/geometry.py`)
- Connection analysis → Collision checks: checks collisions (evidence: `ldraw_tools/connectivity.py`)
- Connection analysis → Technic review: reviews placements (evidence: `ldraw_tools/connectivity.py`)
- Flex constraints → Flex synthesis: writes constraints (evidence: `ldraw_tools/flex_authoring.py`)
- Flex synthesis → LSynth engine: dispatches synthesis (evidence: `ldraw_tools/flex.py`)
- Flex review → Flex synthesis: reads flex engine (evidence: `ldraw_tools/flex_review.py`)
- Vehicle review → Geometry analysis: uses geometry (evidence: `ldraw_tools/vehicle_review.py`)
- AI agent → Technic review: checks structure
- AI agent → Flex synthesis: builds flex parts
- AI agent → Vehicle review: builds vehicles