ananthu0003/cadvex

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.