Text-to-CAD Project Structure: Modular Architecture for Natural Language CAD Generation

The text-to-cad repository organizes code into isolated skills, reusable language-specific packages, a web-based viewer, and automation scripts to convert natural language prompts into STEP files, URDF robot definitions, and G-code.

The text-to-cad project by earthtojake provides an extensible workbench for turning text descriptions into manufacturable CAD artefacts. Understanding the Text-to-CAD project structure reveals how the system balances specialized AI agents with shared geometry libraries to maintain clean separation between generation logic and rendering.

Top-Level Directory Layout

The repository follows a strict organizational convention that separates domain-specific workflows from shared infrastructure:

• skills/ – Individual agent implementations for specific CAD tasks (URDF generation, STEP decomposition, G-code slicing). Each skill contains a SKILL.md manifest and independent CLI entrypoints.
• packages/ – Language-agnostic shared libraries vendored into skill runtimes:
  • cadpy/ – Python utilities for STEP/GLB processing and topology operations.
  • cadpy_metadata/ – Lightweight metadata handling for URDF/SRDF generation without heavy dependencies.
  • cadjs/ – Core JavaScript CAD runtime and render pipeline.
  • implicitjs/ – Standalone implicit CAD engine for mesh sampling and export.
• viewer/ – Vite-based web application that consumes compiled packages and renders artefacts from the models/ directory.
• scripts/ – Development and CI automation, including skill installers (scripts/install/install-skills.sh), test runners (scripts/test/test.sh), and release tooling.
• models/ – Canonical storage for all generated outputs (STEP assemblies, STL meshes, URDF/SRDF definitions, G-code). This directory is strictly governed by policy tests.
• benchmarks/ – Markdown project descriptions and GIF renderings demonstrating generated CAD capabilities.
• docs/ – Vite-built documentation site covering usage and API references.
• AGENTS.md & CONTRIBUTING.md – Repository policies governing branching strategies, symlink layouts, and release workflows.

Skill Execution Architecture

Skills operate as self-contained units that import only necessary subsets of the shared packages, ensuring zero cross-skill dependencies.

Execution flow:

1. A skill CLI parses the user prompt via python -m <skill>.cli.
2. The skill calls geometry helpers from packages/cadpy or metadata utilities from packages/cadpy_metadata.
3. Generated artefacts write directly to models/<project>/.
4. The viewer (npm --prefix viewer run serve) detects new files and renders them using packages/cadjs and packages/implicitjs runtimes.

Practical Usage Examples

Generate URDF Robot Definitions from Text

# Install the URDF skill

bash scripts/install/install-skills.sh urdf

# Generate robot description

python -m urdf.cli < description.txt

# Output: models/<project>/robot.urdf

Implementation reference: skills/urdf/SKILL.md defines the manifest and CLI structure at skills/urdf/scripts/urdf/cli.py.

Convert STEP Assemblies to Individual Parts

bash scripts/install/install-skills.sh step-parts
python -m step_parts.cli --input models/assembly.step --output models/parts/

Implementation reference: skills/step-parts/SKILL.md and the underlying packages/cadpy topology utilities.

Slice Meshes to Bambu-Labs Compatible G-code

bash scripts/install/install-skills.sh gcode
python -m gcode.cli --mesh models/part.stl --printer bambu-labs

# Output: models/part.gcode

Implementation reference: skills/gcode/SKILL.md and backend configurations documented in skills/gcode/references/slicer-backends.md.

Launch the Web Viewer for Inspection

npm --prefix viewer run serve -- --host 127.0.0.1 --dir $(pwd)/models --shutdown-after 12h --json

# Returns JSON with port; open URL in browser to inspect generated artefacts

Implementation reference: Viewer startup documented in skills/cad-viewer/SKILL.md using the viewer/ application code.

Execute the Full Test Suite

bash scripts/test/test.sh

# Runs Python, JavaScript, and global policy validation

Implementation reference: Consolidated test harness in scripts/test/test.sh.

Critical Source Files

File Path	Purpose
skills/urdf/SKILL.md	Manifest for URDF generation workflow and prompt parsing specifications
skills/step-parts/SKILL.md	STEP decomposition skill definition and usage contracts
skills/gcode/SKILL.md	G-code generation skill including slicer backend integration
packages/cadpy/README.md	Python CAD library API for STEP/GLB manipulation
packages/cadjs/README.md	JavaScript rendering pipeline and geometry utilities
viewer/README.md	Viewer deployment and configuration instructions
scripts/install/install-skills.sh	Automated skill installation and dependency resolution
AGENTS.md	Repository governance policies including branch strategy and symlink conventions

Summary

• The text-to-cad architecture isolates CAD workflows in skills/ directories with standardized SKILL.md manifests.
• Shared packages in packages/ provide reusable Python (cadpy) and JavaScript (cadjs, implicitjs) geometry processing without cross-skill coupling.
• All generated artefacts land in the models/ directory, immediately viewable via the viewer/ web application.
• Automation scripts in scripts/ handle installation, testing, and release workflows according to policies defined in AGENTS.md.

Frequently Asked Questions

What is the role of the skills/ directory?

The skills/ directory houses independent agent implementations for specific CAD tasks. Each skill operates as a standalone module with its own CLI, documentation, and dependencies, importing only necessary utilities from packages/ to prevent circular dependencies across workflows.

How do Python and JavaScript components interact in this architecture?

Python components in packages/cadpy/ handle heavy geometry processing, file conversion, and metadata generation, while JavaScript components in packages/cadjs/ and implicitjs/ manage browser-based rendering and implicit modeling. The viewer bridges these by consuming files generated via Python skills and rendering them through the JavaScript runtime.

Where should I store generated CAD files?

All generated artefacts must write to the models/ directory at the repository root. This location is strictly governed by policy tests to ensure consistency, and the viewer automatically detects new files here for immediate inspection.

How do I add a new CAD workflow to the repository?

Create a new subdirectory under skills/ with a SKILL.md manifest defining the workflow, implement the CLI entrypoint referencing appropriate packages/ libraries, and add installation logic to scripts/install/install-skills.sh. Follow the branching and symlink conventions documented in AGENTS.md before submitting changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}