FreeCAD Source Code Architecture Layers Explained

FreeCAD relies on a modular, multi-tier software architecture designed to strictly separate core application logic, data modeling, graphical rendering, and end-user extensions. By isolating business logic from user interfaces, the software can run both interactively on a desktop and headlessly on a server or automated pipeline. The source code is organized into distinct structural tiers: the Base layer, the App (document and data) layer, the Gui (presentation) layer, domain-specific Workbenches, and an extensive Python binding layer that spans the entire system.

1. The Base Layer

The Base layer acts as the foundation of FreeCAD's C++ framework, independent of any 3D graphics or high-level CAD functionality. It implements core utilities, fundamental mathematical primitives (such as vectors, matrices, and coordinate transformations), basic data structures, exception handling, and custom runtime type information (RTTI) through the Base::BaseClass.

This layer also hosts the application's configuration infrastructure, logging frameworks, unit testing mechanics, and the parameter manager, which stores persistent application settings in an XML-based schema.

2. The App Layer (Data Engine)

The App layer contains the non-graphical document object model, responsible for the structural representation and parametric history of a project. It handles data persistence, dependency graph resolution, transactions, and undo/redo stacks.

Key components of the App layer include:

  • App::Document: Manages a single active project file and coordinates its contents.
  • App::DocumentObject: The fundamental base class for all geometric, parametric, or auxiliary objects created in FreeCAD.
  • App::Property system: Dynamic variables attached to document objects (e.g., dimensions, constraints, vectors, placements) that trigger recalculations when modified and handle automated XML/binary serialization.

Crucially, the App layer has no dependency on graphical rendering libraries like Qt or Coin3D, allowing it to execute simulations, batch exports, and conversions purely via the command line or background services.

3. The Gui Layer (Presentation and Interaction)

The Gui layer builds on top of the App layer to provide graphical rendering, user input processing, and interface management. It depends heavily on Qt for interface elements (toolbars, dock widgets, menus) and Coin3D (an Open Inventor 2.1 implementation) for the 3D scenegraph rendering engine.

Rather than altering App data directly, the GUI decouples visual state via the ViewProvider pattern (Gui::ViewProvider). Every App::DocumentObject that requires a 3D representation has a corresponding ViewProvider in the GUI layer. This object defines visual properties such as color, transparency, render mode, and selection handling without contaminating the core CAD data model with visual configurations.

The GUI layer also manages the command framework (Gui::Command), which encapsulates user actions, records them for Python scripting, and executes them against the document.

4. Workbenches (Domain-Specific Modules)

FreeCAD's toolsets are divided into separate, modular components known as Workbenches (e.g., Part, PartDesign, Sketcher, TechDraw, Draft, and BIM). Workbenches can be implemented in C++, pure Python, or a hybrid of both.

Within each C++ workbench, the architectural split between App and GUI is maintained:

  • Workbench App logic: Integrates third-party computational kernels (most notably the OpenCASCADE Technology (OCCT) geometric kernel for B-Rep modeling) to compute geometry, topology, and features.
  • Workbench Gui logic: Supplies custom 3D manipulators, specialized Qt dialogs, toolbars, and ViewProviders specific to that toolset.

5. The Python API Layer

Python is embedded deeply throughout the entire architecture, serving both as an external automation interface and an internal gluing mechanism. FreeCAD uses custom C++ bindings to expose almost every Base, App, and Gui class to the embedded Python interpreter.

Through this layer, users and developers can manipulate document properties, construct geometric entities, customize the interface, and write completely functional workbenches in Python with performance matching native C++ logic for high-level operations.