# petermaginot/ai_piping_design architecture

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

- Interactive diagram: https://gitdiagram.com/petermaginot/ai_piping_design
- Repository: https://github.com/petermaginot/ai_piping_design

## Overview

AI Piping Design is an agent-guidance repository for turning piping prompts and visual references into FreeCAD models, then producing fabrication drawings or 2D artwork. Its principal loop is input interpretation, Quetzal-based modeling, and model verification; separate skills guide TechDraw and Draft work. FreeCAD, Quetzal, and MCP are external runtime dependencies, not implementations in this repository. The README documents these workflows, while the sampled source only confirms Quetzal discovery and table access, so finer internal call wiring is omitted.

Main entry points: [`quetzal_env.py`](https://github.com/petermaginot/ai_piping_design/blob/main/quetzal_env.py) (Quetzal locator), [`skills/quetzal-piping/SKILL.md`](https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/SKILL.md) (Build and verify), [`skills/techdraw-drawing/SKILL.md`](https://github.com/petermaginot/ai_piping_design/blob/main/skills/techdraw-drawing/SKILL.md) (TechDraw guidance), [`skills/draft-2d/SKILL.md`](https://github.com/petermaginot/ai_piping_design/blob/main/skills/draft-2d/SKILL.md) (Draft guidance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Piping modeling"]
  node_pipe_skill["Piping guidance<br/>[SKILL.md]"]
  node_specs["Piping specifications"]
  node_trap_guide["Pig trap guidance"]
  node_build_verify["Build and verify<br/>[SKILL.md]"]
  node_model["Piping model"]
end

subgraph group_outputs["Drawing outputs"]
  node_techdraw["TechDraw guidance<br/>[SKILL.md]"]
  node_fabrication["Fabrication drawing"]
  node_draft["Draft guidance<br/>[SKILL.md]"]
  node_artwork["2D artwork"]
end

subgraph group_runtime["CAD runtime"]
  node_mcp["FreeCAD MCP"]
  node_freecad["FreeCAD GUI"]
  node_quetzal["Quetzal workbench"]
  node_qenv["Quetzal locator<br/>[quetzal_env.py]"]
  node_tables[("Dimension tables")]
end

node_text(("Written prompt"))
node_sketch(("Sketch or drawing"))
node_photo(("Field photograph"))
node_agent(("AI agent"))

node_text -->|"prompts"| node_agent
node_sketch -->|"interprets"| node_agent
node_photo -->|"interprets"| node_agent
node_agent -->|"follows"| node_pipe_skill
node_agent -.->|"consults"| node_specs
node_agent -.->|"consults"| node_trap_guide
node_pipe_skill -->|"guides"| node_build_verify
node_agent -->|"applies"| node_build_verify
node_agent -->|"drives"| node_mcp
node_mcp -->|"controls"| node_freecad
node_freecad -->|"uses"| node_quetzal
node_agent -.->|"invokes"| node_qenv
node_qenv -->|"locates and imports"| node_quetzal
node_qenv -->|"reads"| node_tables
node_build_verify -->|"builds and checks"| node_model
node_techdraw -->|"guides creation"| node_fabrication
node_agent -->|"applies"| node_techdraw
node_model -->|"documents"| node_fabrication
node_draft -->|"guides creation"| node_artwork
node_agent -->|"applies"| node_draft
node_freecad -->|"creates"| node_artwork

click node_pipe_skill "https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/SKILL.md"
click node_specs "https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/references/spool_prompt_template.md"
click node_trap_guide "https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/references/pig_trap_guidelines.md"
click node_build_verify "https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/SKILL.md"
click node_qenv "https://github.com/petermaginot/ai_piping_design/blob/main/quetzal_env.py"
click node_techdraw "https://github.com/petermaginot/ai_piping_design/blob/main/skills/techdraw-drawing/SKILL.md"
click node_draft "https://github.com/petermaginot/ai_piping_design/blob/main/skills/draft-2d/SKILL.md"

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_pipe_skill,node_specs,node_trap_guide,node_build_verify,node_model toneBlue
class node_techdraw,node_fabrication,node_draft,node_artwork toneAmber
class node_mcp,node_freecad,node_quetzal,node_qenv,node_tables toneMint
class node_text,node_sketch,node_photo,node_agent toneIndigo
```

## Components

### Piping modeling

- [Piping guidance](https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/SKILL.md): `skills/quetzal-piping/SKILL.md`
- [Piping specifications](https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/references/spool_prompt_template.md): `skills/quetzal-piping/references/spool_prompt_template.md`
- [Pig trap guidance](https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/references/pig_trap_guidelines.md): `skills/quetzal-piping/references/pig_trap_guidelines.md`
- [Build and verify](https://github.com/petermaginot/ai_piping_design/blob/main/skills/quetzal-piping/SKILL.md): `skills/quetzal-piping/SKILL.md`
- **Piping model**

### Drawing outputs

- [TechDraw guidance](https://github.com/petermaginot/ai_piping_design/blob/main/skills/techdraw-drawing/SKILL.md): `skills/techdraw-drawing/SKILL.md`
- **Fabrication drawing**
- [Draft guidance](https://github.com/petermaginot/ai_piping_design/blob/main/skills/draft-2d/SKILL.md): `skills/draft-2d/SKILL.md`
- **2D artwork**

### CAD runtime

- **FreeCAD MCP**
- **FreeCAD GUI**
- **Quetzal workbench**
- [Quetzal locator](https://github.com/petermaginot/ai_piping_design/blob/main/quetzal_env.py): `quetzal_env.py`
- **Dimension tables**

### Other components

- **Written prompt**
- **Sketch or drawing**
- **Field photograph**
- **AI agent**

## Connections

- Written prompt → AI agent: prompts
- Sketch or drawing → AI agent: interprets
- Field photograph → AI agent: interprets
- AI agent → Piping guidance: follows
- AI agent → Piping specifications: consults
- AI agent → Pig trap guidance: consults
- Piping guidance → Build and verify: guides
- AI agent → Build and verify: applies
- AI agent → FreeCAD MCP: drives
- FreeCAD MCP → FreeCAD GUI: controls
- FreeCAD GUI → Quetzal workbench: uses
- AI agent → Quetzal locator: invokes
- Quetzal locator → Quetzal workbench: locates and imports
- Quetzal locator → Dimension tables: reads
- Build and verify → Piping model: builds and checks
- TechDraw guidance → Fabrication drawing: guides creation
- AI agent → TechDraw guidance: applies
- Piping model → Fabrication drawing: documents
- Draft guidance → 2D artwork: guides creation
- AI agent → Draft guidance: applies
- FreeCAD GUI → 2D artwork: creates