docs/architecture-plan.md

# NaturalCAD Architecture Plan

## Current State (2026-04-12)

We successfully pivoted away from a complex (and broken) Fly.io worker and Hugging Face Docker setup, replacing the backend engine entirely with **Modal**.

### What's Working
- ✅ **LLM Code Generation**: Using `Qwen/Qwen2.5-Coder-32B-Instruct` via Hugging Face Serverless Inference API inside Modal.
- ✅ **CAD Execution Engine**: Modal spins up a `python:3.10-slim` container with proper Linux OpenGL libraries (`libgl1`, `libglib2.0-0`, etc). `build123d` runs locally on the T4 GPU container.
- ✅ **Artifact Upload**: Modal container runs CAD, creates STL, STEP, and a browser-ready GLB using `trimesh`, and uploads directly to Supabase Storage, returning public URLs.
- ✅ **HF Spaces UI**: Front-end UI remains on Hugging Face Spaces.

### What's Deprecated
- ❌ Fly.io backend routing and worker loops (too much complexity/overhead for MVP).
- ❌ Hugging Face native Docker CAD execution (lacks host graphics libs for VTK).

---

## Target Architecture

```
┌─────────────┐
│   User      │────▶ HF Spaces (Gradio UI)
│  Prompt    │
└─────────────┘
      │
      ▼
┌───────────────────────────────────────┐
│              Modal Web Endpoint        │
│                                       │
│ 1. Calls HF Inference API (Qwen 2.5)  │
│ 2. LLM writes build123d Python script │
│ 3. Executes script on Modal Container │
│ 4. Generates STL + STEP + GLB preview │
│ 5. Uploads files to Supabase          │
│ 6. Returns 3 URLs back to HF Space    │
└───────────────────────────────────────┘
      │
      ▼
┌──────────────┐
│  Supabase    │
│  Storage     │
└──────────────┘
```

## Services

| Service | Role | Cost | Status |
|---------|------|-----|--------|
| **HF Spaces** | UI/Frontend | Free tier | ✅ Ready |
| **Modal** | Web API + LLM call + CAD Execution | Pay-per-use GPU | ✅ Ready |
| **HF Inference API**| LLM (text→code) | Free within limits | ✅ Ready |
| **Supabase** | DB + Storage | Free tier | ✅ Ready |

---

## Implementation Order

1. ✅ **Create Modal function** for CAD execution
2. ✅ **Add LLM generation via HF** to the Modal container
3. ✅ **Add Supabase Artifact Upload** returning public URL
4. 🔲 **Deploy Modal Web Endpoint** to get a live URL
5. 🔲 **Wire HF Spaces** to hit the Modal endpoint, parsing out the STL, STEP, and GLB urls into the Gradio UI.

---

*Updated: 2026-04-12*