# 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