Skip to main content

Architecture

CadFlow narrows the boundary between application code and OpenCascade. Python expresses modeling intent and structured workflows; a stable C ABI crosses into a C++17 session that owns exact geometry.

Python apps / CAD agents
Model · Shape · Graph
Stable C ABI
C++ Session / ShapeHandle
Kernel · IO · Runtime · Physics
OpenCascade geometry + topology
Domain workflowsSketch · Assembly · Inspection · Scene · Serialization · SemanticsSTEP · STL · GLB · reports · Scene archives
Applications depend only on the public Python surface; exact geometry ownership stays inside the native session.

Dependency direction​

Python frontend → stable C ABI → C++ Session / ShapeHandle → OpenCascade

The modern frontend contains no direct OCC imports. It sees an opaque session token and shape ID, not a TopoDS_Shape. This keeps OpenCascade types and ownership rules out of application code.

Native ownership​

Each Model owns one Session, and the session owns every shape created through that model.

Model
Session token
Shape ID 1
TopoDS_Shape
Shape ID 2
TopoDS_Shape
Shape ID 3
TopoDS_Shape
A handle can reference only geometry owned by the session that created it.

A handle cannot cross sessions. Closing the model invalidates its handles. Expensive construction, boolean, topology, tessellation, measurement, and exchange calls remain close to OpenCascade instead of moving geometry across Python one object at a time.

Python frontend​

The frontend has two responsibilities:

  1. Model, Shape, and Graph provide the small handle-based native API.
  2. Public domain facades provide sketches, assemblies, semantics, serialization, inspection, Scene archives, standard parts, and solver-neutral handoff structures.

Domain modules are intentionally thin public facades over the bundled complete feature layer. The import layout can remain stable while geometry-heavy paths migrate behind it.

Native runtime​

The native source tree follows this dependency direction:

c_api.cpp → runtime / io / kernel / physics → core
  • core owns shape storage and shared types, not modeling algorithms.
  • kernel owns exact geometry construction and inspection.
  • io owns geometry exchange and serialization formats.
  • runtime parses and executes native graph batches.
  • physics measures exact face evidence and reduced connector response.
  • c_api.cpp is the only installed ABI boundary.

Internal OCCT types and module headers are not public API.

Why some work stays in Python​

Expressions, units, constraint systems, assemblies, semantic tags, Model JSON, Scene schemas, and translator policies are primarily structured-data orchestration. Moving them across the ABI would increase complexity without removing a geometry bottleneck.

The architecture is not "everything in C++." It is "geometry-intensive work in C++; policy and structured workflows in Python."

Delivery path​

Exact BREP remains the source of truth. Meshes and GLB previews are derived views:

Python program
Exact BREP
One source of truth, multiple delivery views
Measurements + validation
JSON evidence
STEP
STL
Tessellation
GLB preview
Checks, engineering formats, and browser previews all trace back to the same exact geometry.

This lets delivery checks compare engineering formats and previews against the same underlying geometry.