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.