# Architecture

## Bootstrap flow

```
FreeCAD startup
  └─ src/Mod/Create/Init.py
       └─ setup_kindred_addons()
            ├─ exec(mods/ztools/ztools/Init.py)
            └─ exec(mods/silo/freecad/Init.py)

  └─ src/Mod/Create/InitGui.py
       ├─ setup_kindred_workbenches()
       │    ├─ exec(mods/ztools/ztools/InitGui.py)
       │    │    └─ schedules deferred _register() (2000ms)
       │    │         ├─ imports ZTools commands
       │    │         ├─ installs _ZToolsManipulator (global)
       │    │         └─ injects commands into editing contexts
       │    └─ exec(mods/silo/freecad/InitGui.py)
       │         ├─ registers SiloWorkbench
       │         └─ schedules deferred Silo overlay registration (2500ms)
       ├─ 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):
            ├─ 1500ms: _register_silo_origin()      → registers Silo FileOrigin
            ├─ 2000ms: _setup_silo_auth_panel()     → "Database Auth" dock
            ├─ 2000ms: ZTools _register()            → commands + manipulator
            ├─ 2500ms: Silo overlay registration     → "Silo Origin" toolbar overlay
            ├─ 3000ms: _check_silo_first_start()    → settings prompt
            ├─ 4000ms: _setup_silo_activity_panel() → "Database Activity" dock (SSE)
            └─ 10000ms: _check_for_updates()        → update checker (Gitea API)
```

## Key source layout

```
src/Mod/Create/              Kindred bootstrap module (Python)
  ├── Init.py                Adds mods/ addon paths, loads Init.py files
  ├── InitGui.py             Loads workbenches, installs Silo manipulators
  ├── version.py.in          CMake template → version.py (build-time)
  └── update_checker.py      Checks Gitea releases API for updates

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

mods/ztools/                 [submodule] command provider (not a workbench)
  ├── ztools/InitGui.py      Deferred command registration + _ZToolsManipulator
  ├── ztools/ztools/
  │   ├── commands/          Datum, pattern, pocket, assembly, spreadsheet
  │   ├── datums/core.py     Datum creation via Part::AttachExtension
  │   └── resources/         Icons, theme utilities
  └── CatppuccinMocha/       Theme preference pack (QSS)

mods/silo/                   [submodule -> silo-mod.git] FreeCAD workbench
  ├── silo-client/           [submodule -> silo-client.git] shared API client
  │   └── silo_client/       SiloClient, SiloSettings, CATEGORY_NAMES
  └── freecad/               FreeCAD workbench (Python)
      ├── InitGui.py         SiloWorkbench + Silo overlay context registration
      ├── silo_commands.py   Commands + FreeCADSiloSettings adapter
      └── silo_origin.py     FileOrigin backend for Silo

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.