No-FreeCAD Architecture Notes

Operational source: derived from the current mixed-runtime audit in D:\02_Code\45_merged_macos_colabui_dfmanim\docs\contracts\occt-freecad-runtime-architecture-audit.md

Scope: target-state notes for a future no-FreeCAD branch. This page is a summary, not the implementation branch itself.

Summary

RapidDraft can move to a no-FreeCAD architecture without giving up the web collaboration shell. The right target is not "replace the browser viewer with OCCT's native viewer." The right target is "use OCCT for geometry import, meshing, topology, canonical scene generation, and DFM facts, while keeping the existing browser viewer, comments, and review UI."

That means the product can still render, run DFM light and deep, and support collaboration after FreeCAD is removed, but only if we replace the current FreeCAD-backed preview and preserve the contracts that the web shell depends on.

Target Architecture

Layer	Target runtime	Why
CAD import and shape loading	OCCT/pythonOCC	One geometry kernel for preview, canonical scene, and DFM reduces drift across pipelines.
Browser preview mesh export	OCCT/pythonOCC	Replaces the current FreeCAD Part.read plus shape.tessellate path with an OCCT-backed preview generator.
Canonical/selectable scene	OCCT/pythonOCC	This path is already largely OCCT-based and should stay that way.
Part Facts and DFM light/deep	OCCT/pythonOCC	These scanners already rely on OCCT topology and feature analysis.
Collaboration UI	Browser + React/Three.js + backend stores	This should remain in the web shell; it is not tied to FreeCAD.
Candidate geometry mutation	OCCT/pythonOCC, later	This is the hardest FreeCAD-specific path and should migrate after preview parity is proven.

What Must Stay Stable

The no-FreeCAD branch should preserve these product contracts:

1. preview.glb or an equivalent browser-renderable preview artifact must still arrive quickly after upload.
2. Component node names must stay stable across preview, canonical scene, Part Facts, DFM, and saved comments.
3. Viewer coordinates and units must match canonical geometry and Part Facts anchors.
4. Preview-first behavior must remain intact: upload success should not wait for exact semantic extraction.
5. Collaboration pin payloads must continue to resolve against the same component and geometry identity model.

If those contracts hold, the collaboration shell does not need to be redesigned.

What Already Favors This Move

The repo already leans OCCT on the exact-analysis side:

• Canonical scene generation loads STEP with OCCT and builds face and edge detail with OCCT meshing: server/canonical_scene_service.py:247-300, server/canonical_scene_service.py:746-781
• Part Facts and DFM geometry extraction already use OCCT topology, surfaces, and STEP loading: server/part_facts.py:1473-1603, server/part_facts.py:1847-2026, server/cnc_geometry_occ.py:4018-4103
• Collaboration is a browser and backend concern, not a FreeCAD concern: web/src/components/ModelViewer.tsx:566-609, web/src/components/ModelViewer.tsx:1953-1985, web/src/components/CollaborationWorkspace.tsx:1262-1299, server/review_store.py:69-95

This means the main migration pressure is on preview generation, runtime packaging, and candidate geometry, not on the DFM rules engine itself.

What Breaks If FreeCAD Is Removed Too Early

Three things break first:

1. Preview rendering. The current upload path builds preview.glb through FreeCAD and trimesh in server/cad_service.py:93-137 and server/cad_service.py:287-369.
2. FreeCAD-only view endpoints such as Shape2D and isometric variants in server/cad_service.py:413-550.
3. Candidate geometry mutation, which currently uses FreeCAD booleans, fillets, and STEP export in server/dfm_candidate_geometry_worker.py:62-100 and server/dfm_candidate_geometry_worker.py:176-339.

There is also a quieter runtime issue: worker discovery is still FreeCAD-oriented. The current setup finds a Python runtime that supports FreeCAD, and optionally probes OCC inside that runtime: server/freecad_setup.py:119-136, server/freecad_setup.py:173-239.

Recommended Migration Order

1. Replace the FreeCAD preview path with an OCCT preview exporter behind a feature flag.
2. Verify preview parity on real models: nonblank GLB, component count, component order, units, and pin alignment.
3. Replace FreeCAD-oriented worker/runtime discovery with an OCC-first runtime setup.
4. Keep canonical scene and Part Facts on OCCT, but improve their staging and timeout behavior in parallel.
5. Port candidate geometry mutation only after the preview and collaboration contracts are stable.

This sequence keeps the user-facing collaboration shell intact while shrinking the highest-risk kernel split first.

Main Risks

Risk	Why it matters
Component identity drift	If component ordering changes, canonical overlays, DFM selection, and saved pins can point at the wrong part.
Preview/anchor coordinate drift	Comments and review pins depend on stable geometry coordinates across preview and canonical layers.
Meshing differences	OCCT preview tessellation may change triangle density, visual appearance, or performance characteristics.
Runtime packaging	The repo currently assumes a FreeCAD-friendly Python environment for some workers.
Migration scope creep	Preview replacement is tractable; candidate mutation and every FreeCAD-only utility should not block the first no-FreeCAD milestone.

Recommended Boundary

The no-FreeCAD branch should aim for this architecture:

• OCCT for geometry import
• OCCT for preview meshing/export
• OCCT for canonical scene generation
• OCCT for Part Facts and DFM extraction
• React/Three.js for browser rendering and collaboration
• existing ticket/review storage for comments and pins

It should explicitly avoid this larger scope change:

• replacing the current browser collaboration shell with OCCT's native desktop visualization stack

That second change is possible, but it is a different product architecture problem.

Sources

• OCCT + FreeCAD Runtime Architecture Audit
• Repo-local audit: D:\02_Code\45_merged_macos_colabui_dfmanim\docs\contracts\occt-freecad-runtime-architecture-audit.md
• Active runtime repo: D:\02_Code\45_merged_macos_colabui_dfmanim