# Architecture ## Bootstrap flow ``` FreeCAD startup └─ src/Mod/Create/Init.py └─ addon_loader.load_addons(gui=False) ├─ scan_addons("mods/") — find package.xml manifests ├─ parse_manifest() — extract extensions ├─ validate_manifest() — check min/max_create_version ├─ resolve_load_order() — topological sort by └─ for each addon in order: ├─ add addon dir to sys.path ├─ exec(Init.py) └─ register in AddonRegistry (FreeCAD.KindredAddons) └─ src/Mod/Create/InitGui.py ├─ addon_loader.load_addons(gui=True) │ └─ for each addon in order: │ └─ exec(InitGui.py) │ ├─ sdk (priority 0): logs "SDK loaded" │ ├─ solver (priority 10): registers KindredSolverBackend │ ├─ gears (priority 40): registers GearsWorkbench │ ├─ datums (priority 45): registers Create_DatumCreator │ └─ silo (priority 60): registers SiloWorkbench │ └─ schedules deferred Silo setup (overlay, panels, observer) ├─ EditingContextResolver singleton created (MainWindow constructor) │ ├─ registers built-in contexts (PartDesign, Sketcher, Assembly, Spreadsheet) │ ├─ connects to signalInEdit/signalResetEdit/signalActiveDocument/signalActivateView │ └─ BreadcrumbToolBar connected to contextChanged signal └─ Deferred setup (QTimer): Create core (src/Mod/Create/InitGui.py): ├─ 500ms: _register_kc_format() → .kc file format └─ 10000ms: _check_for_updates() → update checker (Gitea API) Silo addon (mods/silo/InitGui.py): ├─ 500ms: kindred:// URL handler ├─ 600ms: document observer (.kc tree building) ├─ 2000ms: auth dock panel (via kindred_sdk.register_dock_panel) ├─ 2500ms: Silo overlay registration → "Silo Origin" toolbar overlay ├─ 3000ms: first-start settings check └─ 4000ms: activity dock panel (via kindred_sdk.register_dock_panel) ``` ### Addon lifecycle Each addon in `mods/` provides a `package.xml` manifest with a `` extension block: ```xml 0.1.0 50 true sdk ``` The loader (`addon_loader.py`) processes addons in this order: 1. **Scan** — find all `mods/*/package.xml` files 2. **Parse** — extract `` metadata (version bounds, priority, dependencies) 3. **Validate** — reject addons incompatible with the current Create version 4. **Resolve** — topological sort by `` declarations, breaking ties by `` 5. **Load** — execute `Init.py` (console) then `InitGui.py` (GUI) for each addon 6. **Register** — populate `FreeCAD.KindredAddons` registry with addon state Current load order: **sdk** (0) → **solver** (10) → **gears** (40) → **datums** (45) → **silo** (60) ## Key source layout ``` src/Mod/Create/ Kindred Create module ├── Init.py Console bootstrap — loads addons via manifest-driven loader ├── InitGui.py GUI bootstrap — loads addons, Silo integration, update checker ├── addon_loader.py Manifest-driven addon loader with dependency resolution ├── kc_format.py .kc file format round-trip preservation ├── version.py.in CMake template → version.py (build-time) ├── update_checker.py Checks Gitea releases API for updates ├── CreateGlobal.h C++ export macros (CreateExport, CreateGuiExport) ├── App/ C++ App library (CreateApp.so) │ ├── AppCreate.cpp Module entry point — PyMOD_INIT_FUNC(CreateApp) │ └── AppCreatePy.cpp Python module object (Py::ExtensionModule) └── Gui/ C++ Gui library (CreateGui.so) ├── AppCreateGui.cpp Module entry point — PyMOD_INIT_FUNC(CreateGui) └── AppCreateGuiPy.cpp Python module object (Py::ExtensionModule) mods/sdk/ [dir] Kindred addon SDK — stable API contract ├── package.xml Manifest (priority 0, no dependencies) ├── kindred_sdk/ │ ├── __init__.py Public API re-exports │ ├── context.py Editing context wrappers (register_context, register_overlay, ...) │ ├── theme.py YAML-driven palette system (get_theme_tokens, load_palette, Palette) │ ├── origin.py FileOrigin registration (register_origin, unregister_origin) │ ├── dock.py Deferred dock panel helper (register_dock_panel) │ ├── compat.py Version detection (create_version, freecad_version) │ └── palettes/ │ └── catppuccin-mocha.yaml 26 colors + 14 semantic roles └── Init.py / InitGui.py Minimal log messages mods/gears/ [submodule → gears.git] Gears workbench ├── package.xml Manifest (priority 40, depends on sdk) └── ... Parametric gear generation mods/solver/ [submodule → solver.git] Solver addon └── ... Solver plugin support mods/datums/ [submodule → datums.git] Unified datum creator ├── package.xml Manifest (priority 45, depends on sdk) ├── Init.py / InitGui.py Bootstrap └── datums/ Python package (command, core, panel, detection, edit_panel) mods/silo/ [submodule → silo-mod.git] PLM workbench ├── package.xml Manifest (priority 60, depends on sdk) ├── Init.py sys.path setup for silo-client ├── InitGui.py Consolidated GUI bootstrap (workbench, panels, observer, overlay) ├── silo-client/ [submodule → silo-client.git] shared API client │ └── silo_client/ SiloClient, SiloSettings, CATEGORY_NAMES └── freecad/ FreeCAD workbench (Python) ├── silo_commands.py Commands + FreeCADSiloSettings adapter └── silo_origin.py FileOrigin backend for Silo (via SDK) src/Gui/SDK/ KCSDK C++ shared library (libKCSDK.so) ├── KCSDKGlobal.h DLL export macros ├── Types.h Plain C++ types (ContextDef, DockArea, PanelPersistence) ├── IPanelProvider.h Abstract dock panel interface ├── WidgetBridge.h/.cpp PySide QWidget <-> C++ QWidget* (via Gui::PythonWrapper) ├── SDKRegistry.h/.cpp Singleton registry — contexts, panels, providers └── bindings/ pybind11 module (kcsdk.so) ├── kcsdk_py.cpp Module definition — enums, functions, classes ├── PyIPanelProvider.h Trampoline for Python subclassing └── PyProviderHolder.h GIL-safe forwarding wrapper src/Gui/EditingContext.h/.cpp EditingContextResolver singleton + context registry src/Gui/BreadcrumbToolBar.h/.cpp Color-coded breadcrumb toolbar (Catppuccin Mocha) src/Gui/FileOrigin.h/.cpp FileOrigin base class + LocalFileOrigin src/Gui/CommandOrigin.cpp Origin_Commit/Pull/Push/Info/BOM commands src/Gui/OriginManager.h/.cpp Origin lifecycle management src/Gui/OriginSelectorWidget.h/.cpp UI for origin selection src/Gui/Stylesheets/ QSS themes and SVG assets src/Gui/PreferencePacks/ KindredCreate preference pack (cfg + build-time QSS) ``` See [INTEGRATION_PLAN.md](INTEGRATION_PLAN.md) for architecture layers and phase status.