create/docs/src/architecture/overview.md

Architecture Overview

Kindred Create is structured as a thin integration layer on top of FreeCAD. The design follows three principles:

1. Minimal core modifications — prefer submodule addons over patching FreeCAD internals
2. Graceful degradation — Create runs without ztools or Silo if submodules are missing
3. Pure Python addons — workbenches follow FreeCAD's standard addon pattern

Three-layer model

┌─────────────────────────────────┐
│  FreeCAD Documents (.FCStd)     │  Python source of truth
│  Workbench logic (Python)       │
├─────────────────────────────────┤
│  PostgreSQL                     │  Silo metadata, revisions, BOM
├─────────────────────────────────┤
│  MinIO (S3-compatible)          │  Binary file storage cache
└─────────────────────────────────┘

FreeCAD documents are the authoritative representation of CAD data. Silo's PostgreSQL database stores metadata (part numbers, revisions, BOM relationships) and MinIO stores the binary .FCStd files. The FreeCAD workbench synchronizes between local files and the server.

Source layout

create/
├── src/App/                # Core application (C++)
├── src/Base/               # Foundation classes (C++)
├── src/Gui/                # GUI framework (C++ + Qt6 + QSS)
│   ├── Stylesheets/        # KindredCreate.qss theme
│   ├── PreferencePacks/    # Theme preference pack
│   ├── Icons/              # silo-*.svg origin icons
│   ├── FileOrigin.*        # Abstract file origin interface
│   └── OriginManager.*     # Origin lifecycle management
├── src/Mod/                # ~37 FreeCAD modules
│   ├── Create/             # Kindred bootstrap module
│   ├── Assembly/           # Assembly workbench (Kindred patches)
│   ├── PartDesign/         # Part Design (stock + ztools injection)
│   └── ...                 # Other stock FreeCAD modules
├── mods/
│   ├── ztools/             # Datum/pattern/pocket workbench (submodule)
│   └── silo/               # Parts database workbench (submodule)
└── src/3rdParty/
    ├── OndselSolver/       # Assembly solver (submodule)
    └── GSL/                # Guidelines Support Library (submodule)

Bootstrap sequence

1. FreeCAD core initializes, discovers src/Mod/Create/
2. Init.py runs setup_kindred_addons() — adds mods/ztools/ztools and mods/silo/freecad to sys.path, executes their Init.py
3. GUI phase: InitGui.py runs setup_kindred_workbenches() — executes addon InitGui.py files to register workbenches
4. Deferred QTimer cascade:
   • 1500ms — Register Silo as a file origin
   • 2000ms — Dock the Silo auth panel
   • 3000ms — Check for Silo first-start configuration
   • 4000ms — Dock the Silo activity panel
   • 10000ms — Check for application updates

The QTimer cascade exists because FreeCAD's startup is not fully synchronous — Silo registration must wait for the GUI framework to be ready.

Origin system

The origin system is Kindred's primary addition to FreeCAD's GUI layer:

• FileOrigin — abstract C++ interface for file backends
• LocalFileOrigin — default implementation (local filesystem)
• SiloOrigin — Silo database backend (registered by the Python addon)
• OriginManager — manages origin lifecycle, switching, capability queries
• OriginSelectorWidget — dropdown in the File toolbar
• CommandOrigin.cpp — Commit / Pull / Push / Info / BOM commands that delegate to the active origin

Module interaction

• ztools injects commands into PartDesign via _ZToolsPartDesignManipulator
• Silo registers as a FileOrigin backend via silo_origin.register_silo_origin()
• Create module is glue only — no feature code, just bootstrap and version management