# ananthu0003/cadvex architecture

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

- Interactive diagram: https://gitdiagram.com/ananthu0003/cadvex
- Repository: https://github.com/ananthu0003/cadvex

## Overview

1. **System boundary**
   - This repo is a two-service monorepo: a **Next.js web-ui** and a **FastAPI ai-engine**, plus **PostgreSQL** for persistence.
   - The UI owns the user experience, auth, session state, and database access; the AI engine owns code generation, rendering, and artifact production.

2. **Web UI as the frontend + BFF**
   - `web-ui/app` is a Next.js App Router application with workspace, login/register, share, and landing pages.
   - Its `app/api/*` routes act as a **backend-for-frontend** layer: they validate inputs, proxy requests to the AI engine, and persist session metadata back into PostgreSQL.
   - `proxy.ts` and the auth route handlers indicate route-level access control around workspace/session pages.

3. **Interactive workspace as the primary client surface**
   - The main user flow lives in `components/HitlWorkspace.tsx` and related UI pieces: chat, parameter editor, code editor, history, settings, and STL/CAD viewport.
   - The UI is designed around a human-in-the-loop loop: generate script, edit parameters/code, sync back to engine, re-render, and preview artifacts.

4. **Persistence boundary**
   - PostgreSQL is only used from the web-ui side through **Prisma** (`web-ui/prisma/schema.prisma`, `lib/prisma.ts`).
   - The database appears to store users, profiles, sessions, sharing state, and artifact references; it is not the source of CAD artifacts themselves.
   - `seed.ts` suggests local/dev bootstrap data, reinforcing that persistence is session-centric rather than CAD-model-centric.

5. **AI engine API surface**
   - `ai-engine/app/main.py` and `app/api/v1/router.py` expose the versioned engine API.
   - The key contract is:
     - `POST /api/v1/generate` for streamed CAD-script generation
     - `POST /api/v1/render` for deterministic re-rendering from script + parameters
     - `GET /outputs/{file}` for serving generated artifacts
   - The engine is therefore both a compute service and a local artifact server.

6. **Generation pipeline**
   - `app/services/llm_codegen.py` is the LLM-driven generation path, backed by Gemini via `GOOGLE_API_KEY`.
   - The request is multipart and can include prompt plus image/PDF-like inputs; the engine streams back SSE events (`status`, `token`, `done`, `error`) while assembling the Python CAD script.
   - The output is not just raw code; it also includes parsed parameter structure for the UI to render editable controls.

7. **Render and export pipeline**
   - `app/services/parameter_render.py`, `gcode_generator.py`, `export_utils.py`, and `outputs_cleanup.py` form the execution/export side.
   - The render endpoint consumes edited Python script plus parameter values, regenerates geometry, and writes STL/STEP artifacts into `ai-engine/outputs`.
   - This is a file-based artifact boundary: the engine returns URLs, and the UI fetches fresh artifacts with cache-busting behavior.

8. **Geometry/CAD model processing**
   - `csg_parser.py` and `models/schemas.py` suggest the engine also normalizes or inspects generated CAD structures before rendering/export.
   - The generated code is centered on **build123d** Python scripts, which are the editable intermediate representation shared between generation and render.
   - `parameters` is treated as a top-level contract between generated code and the UI parameter panel.

9. **CAM/post-processing subsystem**
   - `ai-engine/app/cam/posts/*` contains a postprocessor abstraction plus machine-specific posts for **Fanuc, Haas, Heidenhain, ISO, and Siemens**.
   - This indicates a separate CAM output layer that adapts generic toolpaths/G-code to controller-specific formats.
   - On the UI side, `app/api/cam/*` and `components/cam/*` expose CAM-oriented workflows such as tool libraries, setup, cutting parameters, and G-code viewing.

10. **Artifact visualization and download**
   - The UI renders STL output in a 3D viewport using a Three.js-style component stack (`CadViewport`, `StlMesh`, simulation controls).
   - Download/share behavior is session-based: the engine produces files, the UI stores links in session records, and share pages can reopen those artifacts later.
   - This means preview state is decoupled from generation state but linked by session IDs and artifact URLs.

11. **Infrastructure and local runtime**
   - `docker-compose.yml` brings up PostgreSQL for local development; the two app services are run separately.
   - `ai-engine` is Python-based, FastAPI/Uvicorn-driven; `web-ui` is Node/Next.js-based.
   - The main external dependency that materially affects architecture is Gemini for code generation; everything else is local service-to-service traffic and database I/O.

12. **Architectural shape to diagram**
   - A good diagram would show: **Browser → Next.js UI/BFF → FastAPI AI engine → local outputs folder**, with **PostgreSQL** attached to the UI/BFF.
   - Also show the feedback loop: generation streams tokens back to the browser, then render requests send edited scripts/parameters back to the engine, and the resulting artifacts return to the viewer.
   - CAM post-processing can be drawn as a separate branch inside the AI engine because it is conceptually distinct from LLM generation and render/export.

Main entry points: [`web-ui/app`](https://github.com/ananthu0003/cadvex/tree/master/web-ui/app) (App Router), [`web-ui/app/api`](https://github.com/ananthu0003/cadvex/tree/master/web-ui/app/api) (BFF API), [`ai-engine/app/api/v1/router.py`](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/api/v1/router.py) (V1 Router), [`ai-engine/app/services/parameter_render.py`](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/parameter_render.py) (Render)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Client"]
  node_browser(("Browser<br/>client"))
end

subgraph group_webui["Web UI"]
  node_webui_app["App Router<br/>nextjs app"]
  node_webui_api["BFF API<br/>route handlers"]
  node_hitl_workspace["Workspace<br/>hitl client<br/>[HitlWorkspace.tsx]"]
  node_cad_viewport["3D Preview<br/>viewer<br/>[CadViewport.tsx]"]
  node_cam_ui["CAM UI<br/>cam client"]
  node_auth_logic["Auth Layer<br/>session auth<br/>[auth.ts]"]
  node_prisma_client["Prisma<br/>db client<br/>[prisma.ts]"]
end

subgraph group_engine["AI Engine"]
  node_engine_main["Engine API<br/>fastapi app<br/>[main.py]"]
  node_engine_router["V1 Router<br/>api router<br/>[router.py]"]
  node_llm_codegen["Codegen<br/>llm pipeline<br/>[llm_codegen.py]"]
  node_parameter_render["Render<br/>geometry pipeline"]
  node_export_utils["Export<br/>artifact writer<br/>[export_utils.py]"]
  node_cam_posts["CAM Posts<br/>postprocessor set"]
  node_csg_parser["CSG Parser<br/>cad inspection<br/>[csg_parser.py]"]
  node_schemas["Engine Schemas<br/>contracts<br/>[schemas.py]"]
end

subgraph group_data["Data"]
  node_schema["DB Schema<br/>persistence model<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_outputs_cleanup["Outputs<br/>artifact store<br/>[outputs_cleanup.py]"]
end

node_browser -->|"open pages"| node_webui_app
node_webui_app -->|"mount workspace"| node_hitl_workspace
node_webui_app -->|"preview artifacts"| node_cad_viewport
node_webui_app -->|"CAM flows"| node_cam_ui
node_webui_app -->|"protect routes"| node_auth_logic
node_webui_api -->|"persist state"| node_prisma_client
node_prisma_client -->|"read/write"| node_postgres
node_webui_api -->|"proxy requests"| node_engine_main
node_engine_main -->|"serve v1"| node_engine_router
node_engine_router -->|"POST /generate"| node_llm_codegen
node_engine_router -->|"POST /render"| node_parameter_render
node_engine_router -->|"serve files"| node_outputs_cleanup
node_parameter_render -->|"inspect model"| node_csg_parser
node_parameter_render -->|"write artifacts"| node_export_utils
node_export_utils -->|"store outputs"| node_outputs_cleanup
node_webui_api -->|"use contracts"| node_schema
node_webui_api -->|"validate payloads"| node_schemas
node_cam_ui -->|"configure post"| node_cam_posts
node_llm_codegen -->|"return params"| node_schemas
node_outputs_cleanup -->|"artifact fetch"| node_browser

click node_webui_app "https://github.com/ananthu0003/cadvex/tree/master/web-ui/app"
click node_webui_api "https://github.com/ananthu0003/cadvex/tree/master/web-ui/app/api"
click node_hitl_workspace "https://github.com/ananthu0003/cadvex/blob/master/web-ui/components/HitlWorkspace.tsx"
click node_cad_viewport "https://github.com/ananthu0003/cadvex/blob/master/web-ui/components/CadViewport.tsx"
click node_cam_ui "https://github.com/ananthu0003/cadvex/tree/master/web-ui/components/cam"
click node_auth_logic "https://github.com/ananthu0003/cadvex/blob/master/web-ui/lib/auth.ts"
click node_prisma_client "https://github.com/ananthu0003/cadvex/blob/master/web-ui/lib/prisma.ts"
click node_schema "https://github.com/ananthu0003/cadvex/blob/master/web-ui/prisma/schema.prisma"
click node_engine_main "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/main.py"
click node_engine_router "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/api/v1/router.py"
click node_llm_codegen "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/llm_codegen.py"
click node_parameter_render "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/parameter_render.py"
click node_export_utils "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/export_utils.py"
click node_outputs_cleanup "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/outputs_cleanup.py"
click node_cam_posts "https://github.com/ananthu0003/cadvex/tree/master/ai-engine/app/cam/posts"
click node_csg_parser "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/csg_parser.py"
click node_schemas "https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/models/schemas.py"

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_browser toneBlue
class node_webui_app,node_webui_api,node_hitl_workspace,node_cad_viewport,node_cam_ui,node_auth_logic,node_prisma_client toneAmber
class node_engine_main,node_engine_router,node_llm_codegen,node_parameter_render,node_export_utils,node_cam_posts,node_csg_parser,node_schemas toneMint
class node_schema,node_postgres,node_outputs_cleanup toneRose
```

## Components

### Client

User-facing browser entrypoints and interactive workspace

- **Browser**: client · User interacts with pages, workspace, and preview surfaces

### Web UI

Next.js frontend plus backend-for-frontend routes

- [App Router](https://github.com/ananthu0003/cadvex/tree/master/web-ui/app): nextjs app · Top-level pages for landing, auth, workspace, and sharing · `web-ui/app`
- [BFF API](https://github.com/ananthu0003/cadvex/tree/master/web-ui/app/api): route handlers · Validates requests, proxies to engine, and manages session APIs · `web-ui/app/api`
- [Workspace](https://github.com/ananthu0003/cadvex/blob/master/web-ui/components/HitlWorkspace.tsx): hitl client · Main human-in-the-loop editor, chat, parameter, and preview flow · `web-ui/components/HitlWorkspace.tsx`
- [3D Preview](https://github.com/ananthu0003/cadvex/blob/master/web-ui/components/CadViewport.tsx): viewer · STL/CAD visualization and simulation controls · `web-ui/components/CadViewport.tsx`
- [CAM UI](https://github.com/ananthu0003/cadvex/tree/master/web-ui/components/cam): cam client · Tooling for CAM setup, parameters, simulation, and G-code viewing · `web-ui/components/cam`
- [Auth Layer](https://github.com/ananthu0003/cadvex/blob/master/web-ui/lib/auth.ts): session auth · Login, logout, profile, and route protection helpers · `web-ui/lib/auth.ts`
- [Prisma](https://github.com/ananthu0003/cadvex/blob/master/web-ui/lib/prisma.ts): db client · Database access layer used by the web UI · `web-ui/lib/prisma.ts`

### AI Engine

FastAPI service for generation, render, and exports

- [Engine API](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/main.py): fastapi app · FastAPI entrypoint for the AI engine · `ai-engine/app/main.py`
- [V1 Router](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/api/v1/router.py): api router · Versioned endpoints for generate, render, and outputs · `ai-engine/app/api/v1/router.py`
- [Codegen](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/llm_codegen.py): llm pipeline · Gemini-backed streamed CAD-script generation with parameters · `ai-engine/app/services/llm_codegen.py`
- [Render](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/parameter_render.py): geometry pipeline · Rebuilds geometry from script plus parameters and emits artifacts · `ai-engine/app/services/parameter_render.py`
- [Export](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/export_utils.py): artifact writer · Writes STL/STEP and other generated outputs · `ai-engine/app/services/export_utils.py`
- [CAM Posts](https://github.com/ananthu0003/cadvex/tree/master/ai-engine/app/cam/posts): postprocessor set · Machine-specific G-code postprocessors for common controllers · `ai-engine/app/cam/posts`
- [CSG Parser](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/csg_parser.py): cad inspection · Normalizes and inspects generated CAD structures · `ai-engine/app/services/csg_parser.py`
- [Engine Schemas](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/models/schemas.py): contracts · Request and response models shared inside the engine · `ai-engine/app/models/schemas.py`

### Data

Persistent and file-based state boundaries

- [DB Schema](https://github.com/ananthu0003/cadvex/blob/master/web-ui/prisma/schema.prisma): persistence model · Users, profiles, sessions, sharing, and artifact metadata · `web-ui/prisma/schema.prisma`
- **PostgreSQL**: database · Session-centric persistence for the UI and BFF
- [Outputs](https://github.com/ananthu0003/cadvex/blob/master/ai-engine/app/services/outputs_cleanup.py): artifact store · Local outputs directory lifecycle and cleanup · `ai-engine/app/services/outputs_cleanup.py`

## Connections

- Browser → App Router: open pages · Users navigate landing, login, register, workspace, and share pages
- App Router → Workspace: mount workspace · Workspace page renders the main human-in-the-loop editor
- App Router → 3D Preview: preview artifacts · Pages embed the 3D viewport for STL/CAD visualization
- App Router → CAM UI: CAM flows · Workspace exposes CAM setup and G-code viewing surfaces
- App Router → Auth Layer: protect routes · Auth helpers gate login-required pages and session access
- BFF API → Prisma: persist state · Route handlers store sessions, shares, and metadata
- Prisma → PostgreSQL: read/write · Prisma is the sole persistence access path
- BFF API → Engine API: proxy requests · Generate, render, import, and CAM routes forward work to the engine
- Engine API → V1 Router: serve v1 · FastAPI mounts the versioned API router
- V1 Router → Codegen: POST /generate · Streams CAD-script generation events back to the UI
- V1 Router → Render: POST /render · Recomputes geometry from edited script and parameters
- V1 Router → Outputs: serve files · Exposes and manages generated artifacts under outputs
- Render → CSG Parser: inspect model · Render pipeline can normalize or analyze CAD structure before export
- Render → Export: write artifacts · Rendered geometry is exported to STL/STEP and related files
- Export → Outputs: store outputs · Artifacts are written into the engine's local outputs boundary
- BFF API → DB Schema: use contracts · API routes rely on persisted session and sharing structures
- BFF API → Engine Schemas: validate payloads · UI-side handlers shape requests and responses around engine contracts
- CAM UI → CAM Posts: configure post · CAM UI feeds machine/controller-specific output selection
- Codegen → Engine Schemas: return params · Generated scripts include editable parameter structure for the UI
- Outputs → Browser: artifact fetch · Browsers download or refresh generated files via returned URLs