Architecture

  You, in the desktop app             Agents: Claude Code · Codex · Gemini CLI · Cursor · model APIs · local models
  (Qt Quick, form/app)                (chat inside the app, or MCP over stdio from their own window)
          |                                      |                          |
          +------------- local HTTP -------------+------- MCP (form-mcp) ---+---- JSON CLI (form)
                                                 |
                              Studio (form/studio.py): one project state, cross-process locks,
                              parameters and provenance, hashed artifact graph, revisions, release
                    |                  |                    |                     |
           kernel worker         slicer adapters        renderers            bridges
           build123d / OCCT      form/adapters/          form/render.py       FreeCAD, OpenSCAD,
           form/worker.py        Bambu · Orca · Prusa ·  (numpy, headless)    Blender
                                 SuperSlicer · QIDI ·    Blender (photo)
                                 Elegoo · Snapmaker

Form Studio is a layer, not a CAD program or a slicer. Agents supply the intelligence; established software supplies the geometry kernel and the slicing. Form Studio owns what neither does: parameters with provenance, hashed staleness, computed change impact, checks with evidence classes, the fit model, printer calibration and the release record.

Components

Component Module Role
Desktop app form/app/ Qt Quick interface and Qt Quick 3D viewport; talks to the engine in-process through a local HTTP bridge
Engine form/studio.py Projects, revisions, keys, pipeline jobs, release gate
Kernel worker form/worker.py, form/kernel.py build123d on OpenCascade in a separate process; a crash or timeout restarts it without touching project state
Starting a design form/start.py, form/sketch.py, form/photo.py, form/concepts.py Home's composer as one message (words, photos, files, a sketch as structured geometry, links), blank designs, concept groups and the pick
Recipes form/recipes/, form/recipe_lib.py, form/recipe_share.py Parametric families and designs written as code (Python or OpenSCAD); installed and community recipes, verified by SHA-256; .formrecipe packages and submissions
Purpose form/purpose.py For 3D printing or just a 3D model, the process a model is made with, and which checks apply
Checks and analysis form/checks.py, form/analysis.py, form/fit.py, form/selection.py Checks on the solid, analysis maps, the fit model, statics, selections and annotations
Appearance form/materials.py Colours and materials per design or part, the 3MF with colours, material-aware checks
Assemblies form/recipes/assembly.py, form/assembly.py, form/collide.py Parts, kinematic chains and fits as data; interference, fit and joint-sweep checks on meshes with B-rep refinement, in their own time budget
Slicer adapters form/adapters/, form/printers.py, form/plates.py Find the slicer and every printer set up in it, resolve presets, lay parts out on one or more plates, slice, parse the G-code
Print simulation form/toolpath.py, form/simulate.py Per-layer toolpaths by line type, timed by the slicer's estimate
Agents form/agents/, form/chat.py, form/ask.py Run an agent CLI, or talk to a model API, a local model or a provider added by URL with Form Studio's tools (form/agents/mcp_client.py); questions and measurements the agent asks wait for the person's answer
MCP server form/mcp_server.py 74 tools over stdio
CLI form/__main__.py Every capability as a JSON-printing command
Archives form/bundle.py .formstudio files: a project, its conversations and the code it was built from, checked before anything is written
Installer form/installer.py, form/setup.py Finds and installs slicers, agents and libraries, with consent; hands-free on first start

Principles

Agents propose, a person releases. Every engine action is an MCP tool except approval, which exists only in the app. commit_change takes expect_head; a stale head is refused with the current one, so an agent never overwrites a newer human edit. Revisions record their origin (agent:<client>, cli, user).

Agents can see. render rasterises the kernel's tessellation in the server process (z-buffer, flat shading, visible edges, colour by feature, scale bar) and returns a PNG, with no GPU or browser.

Concurrency. The app, any number of MCP servers and the CLI can share one project folder. Studio.lock(pid) is an in-process lock plus a file lock on <data>/.locks/<pid>.lock, and every mutation reloads the project under the lock. The app watches a cheap stamp and follows changes made elsewhere.

Decisions

build123d is the only geometry authority. A recipe builds a B-rep solid as an ordered list of feature stages. STEP is the exchange format for other CAD programs; STL is derived for slicing. Other programs receive STEP; none of them is a second editable source.

Staleness is derived, never flagged. Studio.keys() hashes each artifact's inputs:

Artifact Key covers
Solid recipe source hash, kernel version, parameter values
STEP, STL, OBJ and GLB solid key, print orientation, mesh tolerance
Checks export key, build volume, nozzle, checks version, fit window, calibration fingerprint, provenance of the mating dimension
Slice export key, content hash of each flattened preset, slicer version, the plate plan

An artifact is current when a file exists under its expected key. A clearance change stales all four; an orientation change keeps the solid; a new coupon measurement stales only the checks; another process preset in the slicer stales only the slice. Reverting an input makes the earlier artifact current again, with no rebuild.

Feature attribution is geometric. After each stage the kernel keeps the solid's faces. A final face belongs to the last stage that created the surface under it. This is what makes click-to-select, colour by feature and "features touched" real rather than declared.

Purpose decides what applies. A design for 3D printing runs every check and is sliced. A design that is just a 3D model skips the print-only checks (build volume, nozzle walls, overhangs, bridges, plate contact, the fit model) and the slice; its thinnest feature is compared with the process it names. The release says what it does not cover.

Assemblies are data. A recipe's assembly() returns parts, joints and mates. Parts form a tree: fixed to a parent (attach) or moving on a joint mounted on one (parent), so a joint carries everything below it. Interference, declared fits and joint sweeps are computed on meshes first and booleaned on the B-rep only where parts meet, inside a time budget ([assembly].budget_s); a partial result names the range that was checked.

Evidence classes. computed (measured on the kernel's geometry), heuristic (a rule of thumb on computed values), model (statistics or statics with stated assumptions), simulated (from the slicer), physical (entered from a real print). Coupon measurements calibrate the printer profile; only a result from the part itself is physical evidence for a revision.

Fit model

Total gap = (nominal cavity + printer bias) − object dimension, with independent normal errors. The object's spread comes from its provenance; the printer's bias and spread from pooled coupon and part measurements for the profile (printer and filament), or an assumed ±0.15 mm prior labelled as assumed. The yield is the probability that the gap lands in your acceptance window.

Slicers

form/slicer.py dispatches to the adapter for [slicer].kind (auto uses the first one installed): Bambu Studio, OrcaSlicer, PrusaSlicer, SuperSlicer, QIDISlicer, ElegooSlicer or Snapmaker Orca. A printer chosen for a design or as the default (form/printers.py) picks the slicer and presets. An adapter reads the presets selected in the slicer or pinned in studio.toml, flattens their inheritance chain into self-contained files, and runs the slicer's command line on the oriented STL. Time, filament and supports come from the produced 3MF and G-code, and the G-code is parsed into per-layer paths by line type. When the parts do not fit one plate, form/plates.py packs them, each in its own orientation, onto as many plates as needed (one material per plate) and each plate is sliced on its own. OrcaSlicer 2.5's packed vendor profiles (.opc, format version 2) are decoded directly; any other format version is refused by name.