# Text-to-CAD Project Structure: Modular Architecture for Natural Language CAD Generation > Explore the text-to-cad project structure, featuring modular architecture for natural language CAD generation. Convert prompts to STEP files, URDF, and G-code with isolated skills and reusable packages. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: architecture - Published: 2026-08-04 --- **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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh)), test runners ([`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md)** & **[`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/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 .cli`. 2. The skill calls geometry helpers from `packages/cadpy` or metadata utilities from `packages/cadpy_metadata`. 3. Generated artefacts write directly to `models//`. 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 ```bash # Install the URDF skill bash scripts/install/install-skills.sh urdf # Generate robot description python -m urdf.cli < description.txt # Output: models//robot.urdf ``` *Implementation reference:* [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) defines the manifest and CLI structure at [`skills/urdf/scripts/urdf/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/scripts/urdf/cli.py). ### Convert STEP Assemblies to Individual Parts ```bash 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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/step-parts/SKILL.md) and the underlying `packages/cadpy` topology utilities. ### Slice Meshes to Bambu-Labs Compatible G-code ```bash 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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/gcode/SKILL.md) and backend configurations documented in [`skills/gcode/references/slicer-backends.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/gcode/references/slicer-backends.md). ### Launch the Web Viewer for Inspection ```bash 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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad-viewer/SKILL.md) using the `viewer/` application code. ### Execute the Full Test Suite ```bash bash scripts/test/test.sh # Runs Python, JavaScript, and global policy validation ``` *Implementation reference:* Consolidated test harness in [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh). ## Critical Source Files | File Path | Purpose | |-----------|---------| | [`skills/urdf/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/urdf/SKILL.md) | Manifest for URDF generation workflow and prompt parsing specifications | | [`skills/step-parts/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/step-parts/SKILL.md) | STEP decomposition skill definition and usage contracts | | [`skills/gcode/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/gcode/SKILL.md) | G-code generation skill including slicer backend integration | | [`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/README.md) | Python CAD library API for STEP/GLB manipulation | | [`packages/cadjs/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/README.md) | JavaScript rendering pipeline and geometry utilities | | [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/README.md) | Viewer deployment and configuration instructions | | [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh) | Automated skill installation and dependency resolution | | [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) manifest defining the workflow, implement the CLI entrypoint referencing appropriate `packages/` libraries, and add installation logic to [`scripts/install/install-skills.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/install/install-skills.sh). Follow the branching and symlink conventions documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) before submitting changes.