create/docs/REPOSITORY_STATE.md

# Repository State

**Last updated:** 2026-02-03
**Branch:** main @ `0ef9ffcf51`
**Kindred Create:** v0.1.0
**FreeCAD base:** v1.0.0

## Submodules

| Submodule | Path | Source | Pinned commit |
|-----------|------|--------|---------------|
| ztools | `mods/ztools` | `gitea.kindred.internal/kindred/ztools-0065` | `d2f94c3` |
| silo | `mods/silo` | `gitea.kindred.internal/kindred/silo-0062` | `17a10ab` |
| OndselSolver | `src/3rdParty/OndselSolver` | `gitea.kindred.internal/kindred/ondsel` | `e32c9cd` |
| GSL | `src/3rdParty/GSL` | `github.com/microsoft/GSL` | `756c91a` |
| AddonManager | `src/Mod/AddonManager` | `github.com/FreeCAD/AddonManager` | `01e242e` |
| googletest | `tests/lib` | `github.com/google/googletest` | `56efe39` |

---

## Architecture

### Bootstrap flow

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

  └─ src/Mod/Create/InitGui.py
       ├─ setup_kindred_workbenches()
       │    ├─ exec(mods/ztools/ztools/InitGui.py)
       │    │    ├─ registers ZToolsWorkbench
       │    │    └─ installs _ZToolsPartDesignManipulator (global)
       │    └─ exec(mods/silo/pkg/freecad/InitGui.py)
       │         └─ registers SiloWorkbench
       └─ Deferred setup (QTimer):
            ├─ 1500ms: _setup_silo_auth_panel()    → "Database Auth" dock
            ├─ 2000ms: _setup_silo_menu()           → SiloMenuManipulator
            ├─ 3000ms: _check_silo_first_start()    → settings prompt
            └─ 4000ms: _setup_silo_activity_panel() → "Database Activity" dock
```

### 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

mods/ztools/                 [submodule] ztools workbench
  ├── ztools/InitGui.py      ZToolsWorkbench + PartDesign manipulator
  ├── 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 parts database
  ├── cmd/                   Go server entry points
  ├── internal/              Go API, database, storage packages
  ├── pkg/freecad/           FreeCAD workbench (Python)
  │   ├── InitGui.py         SiloWorkbench
  │   └── silo_commands.py   Commands + SiloClient API
  ├── deployments/           Docker compose configuration
  └── migrations/            PostgreSQL schema migrations

src/Gui/Stylesheets/         QSS themes and SVG assets
resources/preferences/       Canonical preference pack (KindredCreate)
```

---

## Component status

### ztools workbench

**Registered commands (9):**

| Command | Function |
|---------|----------|
| `ZTools_DatumCreator` | Create datum planes, axes, points (16 modes) |
| `ZTools_DatumManager` | Manage existing datum objects |
| `ZTools_EnhancedPocket` | Flip-side pocket (cut outside sketch profile) |
| `ZTools_RotatedLinearPattern` | Linear pattern with incremental rotation |
| `ZTools_AssemblyLinearPattern` | Pattern assembly components linearly |
| `ZTools_AssemblyPolarPattern` | Pattern assembly components around axis |
| `ZTools_SpreadsheetStyle{Bold,Italic,Underline}` | Text style toggles |
| `ZTools_SpreadsheetAlign{Left,Center,Right}` | Cell alignment |
| `ZTools_Spreadsheet{BgColor,TextColor,QuickAlias}` | Colors and alias creation |

**PartDesign integration** via `_ZToolsPartDesignManipulator`:
- `ZTools_DatumCreator`, `ZTools_DatumManager` → "Part Design Helper Features" toolbar
- `ZTools_EnhancedPocket` → "Part Design Modeling Features" toolbar
- `ZTools_RotatedLinearPattern` → "Part Design Transformation Features" toolbar
- Same commands inserted into Part Design menu after `PartDesign_Boolean`

**Datum types (7):** offset_from_face, offset_from_plane, midplane, 3_points, normal_to_edge, angled, tangent_to_cylinder. All except tangent_to_cylinder use `Part::AttachExtension` for automatic parametric updates.

### Silo workbench

**Registered commands (13):**

| Command | Function |
|---------|----------|
| `Silo_New` | Create new Silo-tracked document |
| `Silo_Open` | Open file from Silo database |
| `Silo_Save` | Save to Silo (create revision) |
| `Silo_Commit` | Commit current revision |
| `Silo_Pull` | Pull latest revision from server |
| `Silo_Push` | Push local changes to server |
| `Silo_Info` | View item metadata and history |
| `Silo_BOM` | Bill of materials dialog (BOM + Where Used) |
| `Silo_TagProjects` | Assign project tags |
| `Silo_Rollback` | Rollback to previous revision |
| `Silo_SetStatus` | Set revision status (draft/review/released/obsolete) |
| `Silo_Settings` | Configure API URL, projects dir, SSL certificates |
| `Silo_ToggleMode` | Swap Ctrl+O/S/N between FreeCAD and Silo commands |

**Global integration** via `SiloMenuManipulator` in `src/Mod/Create/InitGui.py`:
- File menu: Silo_New, Silo_Open, Silo_Save, Silo_Commit, Silo_Pull, Silo_Push, Silo_BOM
- File toolbar: Silo_ToggleMode button

**Server architecture:** Go REST API (38 routes) + PostgreSQL + MinIO. See `mods/silo/docs/REPOSITORY_STATUS.md` for route details.

### Theme

**Canonical source:** `resources/preferences/KindredCreate/KindredCreate.qss`

Four copies must stay in sync:
1. `resources/preferences/KindredCreate/KindredCreate.qss` (canonical)
2. `src/Gui/Stylesheets/KindredCreate.qss`
3. `src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss`
4. `mods/ztools/CatppuccinMocha/CatppuccinMocha.qss`

---

## Known issues

### Critical

1. **QSS duplication.** Four copies of the stylesheet must be kept in sync manually. A build step or symlinks should eliminate this.

2. **WorkbenchManipulator timing.** The `_ZToolsPartDesignManipulator` appends commands by name. If ZToolsWorkbench hasn't been activated when the user switches to PartDesign, the commands may not be registered. The manipulator API tolerates missing commands silently, but buttons won't appear.

3. **Silo shortcut persistence.** `Silo_ToggleMode` stores original shortcuts in a module-level dict. If FreeCAD crashes with Silo mode on, original shortcuts are lost on next launch.

### High

4. **No authentication on Silo server.** All API endpoints are publicly accessible. Required before multi-user deployment.

5. **No unit tests.** Zero test coverage for ztools and Silo FreeCAD commands. Silo Go backend also lacks tests.

6. **Assembly solver datum handling is minimal.** The `findPlacement()` fix extracts placement from `obj.Shape.Faces[0]` for `PartDesign::Plane`. Does not handle empty shapes or non-planar datum objects.

### Medium

7. **`Silo_BOM` requires Silo-tracked document.** Depends on `SiloPartNumber` property. Unregistered documents show a warning with no registration path.

8. **PartDesign menu insertion fragility.** `_ZToolsPartDesignManipulator.modifyMenuBar()` inserts after `PartDesign_Boolean`. If upstream renames this command, insertions silently fail.

9. **tangent_to_cylinder falls back to manual placement.** TangentPlane MapMode requires a vertex reference not collected by the current UI.

10. **`delete_bom_entry()` bypasses error normalization.** Uses raw `urllib.request` instead of `SiloClient._request()`.

---

## Incomplete features

### Silo

| Feature | Status | Notes |
|---------|--------|-------|
| Authentication/authorization | Not implemented | Required for multi-user |
| File locking | Not implemented | Needed to prevent concurrent edits |
| Odoo ERP integration | Stub only | Returns "not yet implemented" |
| Part number date segments | Broken | `formatDate()` returns error |
| Location/inventory APIs | Tables exist, no handlers | |
| CSRF protection | Not implemented | Web UI only |
| CSV import rollback | Not implemented | `bom_handlers.go` |

### ztools

| Feature | Status | Notes |
|---------|--------|-------|
| Tangent-to-cylinder attachment | Manual fallback | No vertex ref in UI |
| Angled datum live editing | Incomplete | AttachmentOffset not updated in panel |
| Assembly pattern undo | Not implemented | |

### Integration plan

| Phase | Feature | Status |
|-------|---------|--------|
| 1 | Addon auto-loading | Done |
| 2 | Enhanced Pocket as C++ feature | Not started |
| 3 | Datum C++ helpers | Not started (Python approach used) |
| 4 | Theme moved to Create module | Partial (QSS synced, not relocated) |
| 5 | Silo deep integration | Done |
| 6 | Build system install rules for mods/ | Partial (CI/CD done, CMake install rules pending) |

---

## Next steps

1. **Authentication** -- LDAP/FreeIPA integration for Silo multi-user deployment. Server needs auth middleware; FreeCAD client needs credential storage.

2. **BOM-Assembly bridge** -- Auto-populate Silo BOM from Assembly component links on save.

3. **File locking** -- Pessimistic locks on `Silo_Open` to prevent concurrent edits. Requires server-side lock table and client-side lock display.

4. **Build system** -- CMake install rules for `mods/` submodules so packages include ztools and Silo without manual steps.

5. **Test coverage** -- Unit tests for ztools datum creation, Silo FreeCAD commands, and Go API endpoints.