# ajithgoveas/cad_copilot architecture

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

- Interactive diagram: https://gitdiagram.com/ajithgoveas/cad_copilot
- Repository: https://github.com/ajithgoveas/cad_copilot

## Overview

1. **System shape**
   - This repo is a three-part monorepo: a **Next.js web workspace** (`web-ui`), a **FastAPI AI/rendering service** (`ai-engine`), and **PostgreSQL** for session persistence.
   - The UI is not just a frontend; it also acts as a **BFF/proxy layer** that mediates all calls to the AI engine and stores session metadata.

2. **Primary responsibility split**
   - `web-ui` owns user interaction: prompt entry, image/PDF upload, chat-style interaction, parameter editing, code editing, history, and 3D preview.
   - `ai-engine` owns compute-heavy work: **LLM-based build123d code generation** and **Python CAD execution/rendering**.
   - PostgreSQL stores durable session state; generated artifacts themselves live in the AI engine’s output area.

3. **Frontend workspace boundary**
   - The main user surface is `web-ui/components/HitlWorkspace.tsx`, which appears to compose the chat panel, parameter inputs, code editor, history drawer, and STL/CAD viewport components.
   - Rendering is split between UI concerns (`ChatBubble`, `ChatPanel`, `EditorDrawer`, `ParameterInput`, `CadViewport`, `StlMesh`) and shared UI primitives in `components/ui`.
   - This is a human-in-the-loop workflow: users can accept generated code, edit parameters, then manually sync changes back to the engine.

4. **Next.js BFF/API layer**
   - `web-ui/app/api/generate/route.ts` proxies generation requests to the AI engine and likely handles request validation and session creation.
   - `web-ui/app/api/render/route.ts` proxies render requests, normalizes payloads, and persists returned artifact URLs into the session record.
   - `web-ui/app/api/sessions/route.ts` provides session listing/history behavior, tying the UI to PostgreSQL through Prisma.

5. **Persistence layer**
   - Prisma is the ORM boundary in `web-ui/lib/prisma.ts`, backed by `web-ui/prisma/schema.prisma`.
   - The database is used for **session persistence**, not for geometry storage; it tracks user sessions, generated code/state, and likely artifact references.
   - `docker-compose.yml` provides the PostgreSQL service for local development.

6. **Generation pipeline**
   - The prompt/upload flow starts in the UI, then `POST /api/generate` is sent as a multipart request to `ai-engine`.
   - `ai-engine/app/services/llm_codegen.py` handles Gemini-driven generation of a Python CAD script.
   - Generation is streamed back as **SSE** with events like status/token/done/error, so the UI can show progressive output instead of waiting for a single blocking response.

7. **Code contract between generator and UI**
   - The generated script is expected to expose a top-level `PARAMETERS` structure and a `build_model(params)` style entrypoint, because the UI supports parameter extraction and later re-rendering.
   - `ai-engine/app/models/schemas.py` and `app/api/v1/router.py` define the request/response contract for these generation/render endpoints.
   - This contract is the key boundary between “LLM code synthesis” and “deterministic CAD execution.”

8. **Render pipeline**
   - `web-ui` sends edited Python script plus parameter values to `POST /api/render`, which forwards JSON to `ai-engine /api/v1/render`.
   - `ai-engine/app/services/parameter_render.py` is responsible for executing the script, applying parameters, and exporting geometry artifacts.
   - The render response returns artifact URLs, typically for **STL and STEP**, which the UI can immediately load or download.

9. **Artifact serving and preview**
   - The AI engine serves generated files from `ai-engine/outputs` through `GET /outputs/{file}`.
   - The UI uses a 3D viewport path (`CadViewport`, `StlMesh`) to display the latest STL, with cache-busting behavior noted in the README to avoid stale geometry.
   - This creates a clear separation: the engine produces files, while the UI is responsible for visualizing and downloading them.

10. **External dependency and runtime boundaries**
   - The only major external AI dependency is **Google Gemini** via `GOOGLE_API_KEY`, making model availability and quota a key runtime factor for generation.
   - The stack spans **Node.js/Next.js** on the frontend and **Python/FastAPI** on the backend, so the API boundary is the main integration seam.
   - Docker is used for local infra, while browser-side rendering is handled by the Next.js client components and Three.js/react-three-fiber-based visualization.

11. **Operational and validation surfaces**
   - `ai-engine/scripts/validate.py` suggests there is explicit validation around generated scripts or payloads.
   - Environment templates in both apps show the repo is designed for local development with separate runtime configuration for API URL, database URL, and model credentials.
   - The docs under `docs/` and `ai-engine/ARCHITECTURE.md` appear to describe the engine’s internal flow and are likely the best source for deeper service-level boundaries.

Main entry points: [`ai-engine/app/api/v1/router.py`](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/api/v1/router.py) (API Router), [`web-ui/components/HitlWorkspace.tsx`](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/HitlWorkspace.tsx) (Hitl Workspace), [`web-ui/lib/prisma.ts`](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/lib/prisma.ts) (Prisma), [`web-ui/app/api/generate/route.ts`](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/generate/route.ts) (Generate API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web_ui["web-ui"]
  node_workspace["Hitl Workspace<br/>workspace shell<br/>[HitlWorkspace.tsx]"]
  node_chat_panel["Chat Panel<br/>interaction ui<br/>[ChatPanel.tsx]"]
  node_parameter_input["Parameters<br/>form ui<br/>[ParameterInput.tsx]"]
  node_editor_drawer["Code Editor<br/>editor ui<br/>[EditorDrawer.tsx]"]
  node_history_drawer["History<br/>session ui<br/>[HistoryDrawer.tsx]"]
  node_cad_viewport["CAD Viewport<br/>3d preview<br/>[CadViewport.tsx]"]
  node_stl_mesh["STL Mesh<br/>mesh viewer<br/>[StlMesh.tsx]"]
  node_generate_api["Generate API<br/>next bff<br/>[route.ts]"]
  node_render_api["Render API<br/>next bff<br/>[route.ts]"]
  node_sessions_api["Sessions API<br/>next bff<br/>[route.ts]"]
  node_prisma["Prisma<br/>orm boundary<br/>[prisma.ts]"]
  node_schema["Schema<br/>[schema.prisma]"]
end

subgraph group_ai_engine["ai-engine"]
  node_router["API Router<br/>[router.py]"]
  node_schemas["Schemas<br/>pydantic models<br/>[schemas.py]"]
  node_llm_codegen["LLM Codegen<br/>generation service<br/>[llm_codegen.py]"]
  node_parameter_render["Parameter Render<br/>render service"]
  node_outputs[("Outputs<br/>artifact store")]
  node_validate_script["Validate<br/>validation script<br/>[validate.py]"]
end

subgraph group_persistence["persistence"]
  node_postgres[("PostgreSQL<br/>session db<br/>[docker-compose.yml]")]
end

node_gemini(("Gemini<br/>external llm"))

node_workspace -->|"compose"| node_chat_panel
node_workspace -->|"compose"| node_parameter_input
node_workspace -->|"compose"| node_editor_drawer
node_workspace -->|"compose"| node_history_drawer
node_workspace -->|"compose"| node_cad_viewport
node_cad_viewport -->|"renders"| node_stl_mesh
node_chat_panel -->|"submit prompt"| node_generate_api
node_generate_api -->|"proxy"| node_router
node_render_api -->|"proxy"| node_router
node_sessions_api -->|"query"| node_prisma
node_prisma -->|"maps"| node_schema
node_generate_api -->|"persist session"| node_prisma
node_render_api -->|"persist artifacts"| node_prisma
node_router -->|"validates"| node_schemas
node_router -->|"generate"| node_llm_codegen
node_router -->|"render"| node_parameter_render
node_llm_codegen -->|"calls"| node_gemini
node_llm_codegen -->|"checks"| node_validate_script
node_parameter_render -->|"writes"| node_outputs
node_outputs -->|"loads"| node_cad_viewport
node_outputs -->|"returns urls"| node_render_api
node_prisma -->|"stores"| node_postgres
node_generate_api -.->|"stream sse"| node_router

click node_workspace "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/HitlWorkspace.tsx"
click node_chat_panel "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/ChatPanel.tsx"
click node_parameter_input "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/ParameterInput.tsx"
click node_editor_drawer "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/EditorDrawer.tsx"
click node_history_drawer "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/HistoryDrawer.tsx"
click node_cad_viewport "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/CadViewport.tsx"
click node_stl_mesh "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/StlMesh.tsx"
click node_generate_api "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/generate/route.ts"
click node_render_api "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/render/route.ts"
click node_sessions_api "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/sessions/route.ts"
click node_prisma "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/lib/prisma.ts"
click node_schema "https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/prisma/schema.prisma"
click node_router "https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/api/v1/router.py"
click node_schemas "https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/models/schemas.py"
click node_llm_codegen "https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/services/llm_codegen.py"
click node_parameter_render "https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/services/parameter_render.py"
click node_validate_script "https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/scripts/validate.py"
click node_postgres "https://github.com/ajithgoveas/cad_copilot/blob/master/docker-compose.yml"

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_workspace,node_chat_panel,node_parameter_input,node_editor_drawer,node_history_drawer,node_cad_viewport,node_stl_mesh,node_generate_api,node_render_api,node_sessions_api,node_prisma,node_schema toneBlue
class node_router,node_schemas,node_llm_codegen,node_parameter_render,node_outputs,node_validate_script toneAmber
class node_postgres toneMint
class node_gemini toneNeutral
```

## Components

### web-ui

Next.js workspace for user interaction, BFF routing, persistence access, and preview orchestration.

- [Hitl Workspace](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/HitlWorkspace.tsx): workspace shell · Main human-in-the-loop surface composing chat, parameters, code editing, history, and preview. · `web-ui/components/HitlWorkspace.tsx`
- [Chat Panel](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/ChatPanel.tsx): interaction ui · Prompt entry and chat-style conversation surface. · `web-ui/components/ChatPanel.tsx`
- [Parameters](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/ParameterInput.tsx): form ui · Parameter editing for generated CAD code. · `web-ui/components/ParameterInput.tsx`
- [Code Editor](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/EditorDrawer.tsx): editor ui · Editable generated script and manual sync workflow. · `web-ui/components/EditorDrawer.tsx`
- [History](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/HistoryDrawer.tsx): session ui · Session browsing and prior artifact navigation. · `web-ui/components/HistoryDrawer.tsx`
- [CAD Viewport](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/CadViewport.tsx): 3d preview · Browser-side 3D preview surface for rendered geometry. · `web-ui/components/CadViewport.tsx`
- [STL Mesh](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/components/StlMesh.tsx): mesh viewer · Loads STL artifacts into the viewport. · `web-ui/components/StlMesh.tsx`
- [Generate API](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/generate/route.ts): next bff · Proxies generation requests to the AI engine and manages session creation. · `web-ui/app/api/generate/route.ts`
- [Render API](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/render/route.ts): next bff · Proxies render requests and persists returned artifact references. · `web-ui/app/api/render/route.ts`
- [Sessions API](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/app/api/sessions/route.ts): next bff · Session listing and history endpoint backed by Prisma. · `web-ui/app/api/sessions/route.ts`
- [Prisma](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/lib/prisma.ts): orm boundary · Database access layer for session persistence. · `web-ui/lib/prisma.ts`
- [Schema](https://github.com/ajithgoveas/cad_copilot/blob/master/web-ui/prisma/schema.prisma): prisma schema · Session and artifact persistence model. · `web-ui/prisma/schema.prisma`

### ai-engine

FastAPI service for LLM code generation, parameterized rendering, and artifact serving.

- [API Router](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/api/v1/router.py): fastapi router · Versioned REST contract for generation and render endpoints. · `ai-engine/app/api/v1/router.py`
- [Schemas](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/models/schemas.py): pydantic models · Request and response models for engine API contracts. · `ai-engine/app/models/schemas.py`
- [LLM Codegen](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/services/llm_codegen.py): generation service · Gemini-backed Python CAD script generation with streaming SSE output. · `ai-engine/app/services/llm_codegen.py`
- [Parameter Render](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/app/services/parameter_render.py): render service · Executes generated Python, applies parameters, and exports geometry artifacts. · `ai-engine/app/services/parameter_render.py`
- **Outputs**: artifact store · Generated geometry files served by the engine.
- [Validate](https://github.com/ajithgoveas/cad_copilot/blob/master/ai-engine/scripts/validate.py): validation script · Checks generated scripts or payloads during the engine workflow. · `ai-engine/scripts/validate.py`

### persistence

Durable session storage and local database infrastructure.

- [PostgreSQL](https://github.com/ajithgoveas/cad_copilot/blob/master/docker-compose.yml): session db · Durable storage for sessions, generated state, and artifact references. · `docker-compose.yml`

### Other components

- **Gemini**: external llm · External model dependency used for code synthesis.

## Connections

- Hitl Workspace → Chat Panel: compose · Workspace includes the chat surface.
- Hitl Workspace → Parameters: compose · Workspace includes parameter editing.
- Hitl Workspace → Code Editor: compose · Workspace includes the code editor.
- Hitl Workspace → History: compose · Workspace includes session history.
- Hitl Workspace → CAD Viewport: compose · Workspace includes 3D preview.
- CAD Viewport → STL Mesh: renders · Viewport loads STL meshes for preview.
- Chat Panel → Generate API: submit prompt · Prompt and uploads initiate generation through the BFF.
- Generate API → API Router: proxy · Next.js forwards generation requests to the engine API.
- Render API → API Router: proxy · Next.js forwards render requests to the engine API.
- Sessions API → Prisma: query · Session listing is backed by Prisma.
- Prisma → Schema: maps · ORM layer uses the Prisma schema.
- Generate API → Prisma: persist session · Generation flow creates or updates session records.
- Render API → Prisma: persist artifacts · Render flow stores returned artifact references.
- API Router → Schemas: validates · API contract is defined by request and response schemas.
- API Router → LLM Codegen: generate · Generation endpoint delegates to the code synthesis service.
- API Router → Parameter Render: render · Render endpoint delegates to the execution service.
- LLM Codegen → Gemini: calls · Code generation depends on Google Gemini.
- LLM Codegen → Validate: checks · Generated code is validated before use.
- Parameter Render → Outputs: writes · Rendering exports geometry artifacts to the output store.
- Outputs → CAD Viewport: loads · UI previews the latest exported STL.
- Outputs → Render API: returns urls · Render responses surface artifact links to the UI.
- Prisma → PostgreSQL: stores · Session state is persisted in PostgreSQL.
- Generate API → API Router: stream sse · Generation responses are streamed back to the UI.