docs: update architecture docs for addon-first model (#255)
Some checks failed
Build and Test / build (pull_request) Failing after 2m1s

ARCHITECTURE.md:
- Replace exec()-based bootstrap flow with manifest-driven loader diagram
- Add addon lifecycle section (scan → parse → validate → resolve → load → register)
- Add SDK and C++ scaffold to source layout
- Document load order: sdk (0) → ztools (50) → silo (60)

INTEGRATION_PLAN.md:
- Add Layer 4 (Addon SDK) between bootstrap and addons (now 5 layers)
- Update Layer 3: now hosts both Python loader AND C++ scaffold
- Add Phase 1.5 (SDK) and Phase 1.75 (C++ scaffold) as DONE
- Update Phase 4 (theme): colors centralized in SDK YAML palette
- Update Phase 6 (build): now DONE with CMake install rules for all addons
- Add design decisions #7 (SDK as adaptation layer) and #8 (manifest-driven loading)

README.md:
- Update addon integration section: manifest-driven loading, SDK wrappers
- Add mods/sdk/ to project structure tree
- Update Create module description to mention C++ scaffold

Closes #255.
This commit is contained in:
2026-02-17 12:38:18 -06:00
parent 68380357fb
commit 252e2c3b3e
3 changed files with 169 additions and 77 deletions

View File

@@ -112,7 +112,9 @@ Addons extend this through the Python API:
### Addon integration
Both ztools and Silo are loaded by the `src/Mod/Create/` bootstrap module, which executes their `Init.py` and `InitGui.py` files at startup. Neither requires the user to switch workbenches. Instead, they register commands and use the editing context system to make those commands visible in the appropriate situations.
Addons in `mods/` are loaded by a manifest-driven loader (`src/Mod/Create/addon_loader.py`). Each addon provides a `package.xml` with `<kindred>` extensions declaring version bounds, load priority, and dependencies. The loader resolves dependencies via topological sort and loads addons in order: **sdk** (0) → **ztools** (50) → **silo** (60).
Addons call platform APIs through the **kindred-addon-sdk** (`mods/sdk/kindred_sdk/`) rather than `FreeCADGui.*` internals directly. The SDK provides stable wrappers for editing contexts, theme tokens, FileOrigin registration, and dock panels.
ztools uses a `WorkbenchManipulator` plus `injectEditingCommands()` to add its tools to PartDesign, Assembly, and Spreadsheet contexts. Silo registers an overlay that adds the "Silo Origin" toolbar whenever the active document contains Silo tracking properties (`SiloItemId`, `SiloPartNumber`).
@@ -179,13 +181,14 @@ create/
│ │ ├── Stylesheets/ # QSS theme files
│ │ └── PreferencePacks/ # Theme and preference configurations
│ ├── Mod/ # FreeCAD modules (PartDesign, Assembly, Sketcher, ...)
│ │ └── Create/ # Kindred bootstrap module -- loads ztools and Silo
│ │ └── Create/ # Kindred Create module (Python loader + C++ scaffold)
│ └── 3rdParty/ # Vendored dependencies
│ ├── OndselSolver/ # Assembly constraint solver (forked)
│ └── GSL/ # Microsoft Guidelines Support Library
├── mods/ # Kindred addon modules (git submodules)
│ ├── ztools/ # ztools command provider
── silo/ # Silo PLM workbench
├── mods/ # Kindred addon modules
│ ├── sdk/ # Addon SDK — stable API contract (priority 0)
── ztools/ # ztools command provider (submodule, priority 50)
│ └── silo/ # Silo PLM workbench (submodule, priority 60)
├── resources/ # Branding, icons, desktop integration, MIME types
├── package/ # Packaging scripts
│ ├── debian/ # .deb build script