ajithgoveas/cad_copilot

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.