kindred/create
1
1
Fork 0
Code Issues 53 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

docs: write ARCHITECTURE.md — three-layer model and bootstrap flow #89

New Issue
Closed
opened 2026-02-09 13:45:22 +00:00 by forbes · 1 comment
forbes commented 2026-02-09 13:45:22 +00:00
Owner
Copy Link

Tier 1 — Entry Point

File: docs/ARCHITECTURE.md
Priority: Read third — mental model for how everything fits together

What this document should cover

  1. Three-layer architecture:
    • Python source of truth — FreeCAD documents (.FCStd), workbench logic in Python addons
    • PostgreSQL params — Silo server stores metadata, revisions, BOM data
    • MinIO cache — S3-compatible object storage for binary file content
  2. Source layout diagram: 
    create/
├── src/App/          # Core application (C++)
├── src/Base/         # Foundation classes (C++)
├── src/Gui/          # GUI framework (C++ + Qt6 + QSS)
│   ├── Stylesheets/  # KindredCreate.qss theme
│   ├── PreferencePacks/
│   ├── Icons/        # silo-*.svg origin icons
│   ├── FileOrigin.*  # Abstract file origin interface
│   └── OriginManager.*
├── 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)
  3. Bootstrap sequence:
    • FreeCAD core init → loads src/Mod/Create/Init.py
    • setup_kindred_addons() adds ztools + silo to sys.path, runs their Init.py
    • GUI phase: InitGui.py → setup_kindred_workbenches() registers workbenches
    • Deferred QTimer cascade: Silo origin (1.5s) → auth panel (2s) → first-start check (3s) → activity panel (4s) → update check (10s)
  4. Origin system architecture:
    • FileOrigin (abstract C++ interface) → LocalFileOrigin + SiloOrigin
    • OriginManager — lifecycle, switching, capability queries
    • OriginSelectorWidget — File toolbar dropdown
    • Commands: Commit / Pull / Push / Info / BOM — delegate to active origin
  5. Module interaction model:
    • ztools injects into PartDesign via _ZToolsPartDesignManipulator
    • Silo registers as a FileOrigin backend
    • Create module is the glue — no feature code, just bootstrap and version
  6. Key design principles:
    • Minimal core modifications — prefer submodule addons
    • Graceful degradation — Create runs without ztools/Silo if submodules are missing
    • Pure Python addons following FreeCAD's standard addon pattern
    • No changes to FreeCAD's container models (Part, Body, Assembly)

Replaces

The existing docs/ARCHITECTURE.md is a brief auto-generated summary. This issue calls for a proper architectural document with diagrams.

Key source files to reference

  • src/Mod/Create/Init.py, src/Mod/Create/InitGui.py — bootstrap
  • src/Gui/FileOrigin.h, src/Gui/OriginManager.h — origin system
  • src/Gui/CommandOrigin.cpp — origin commands
  • src/Gui/OriginSelectorWidget.h — UI integration
  • mods/ztools/ztools/ztools/InitGui.py — workbench + manipulator registration
  • mods/silo/freecad/InitGui.py — Silo workbench registration

Acceptance criteria

  • Three-layer model is clearly explained with a diagram
  • Bootstrap sequence is documented step-by-step with timings
  • Origin system architecture is explained with class relationships
  • A reader understands how ztools, Silo, and Create module interact
## Tier 1 — Entry Point **File:** `docs/ARCHITECTURE.md` **Priority:** Read third — mental model for how everything fits together ### What this document should cover 1. **Three-layer architecture:** - **Python source of truth** — FreeCAD documents (`.FCStd`), workbench logic in Python addons - **PostgreSQL params** — Silo server stores metadata, revisions, BOM data - **MinIO cache** — S3-compatible object storage for binary file content 2. **Source layout diagram:** ``` create/ ├── src/App/ # Core application (C++) ├── src/Base/ # Foundation classes (C++) ├── src/Gui/ # GUI framework (C++ + Qt6 + QSS) │ ├── Stylesheets/ # KindredCreate.qss theme │ ├── PreferencePacks/ │ ├── Icons/ # silo-*.svg origin icons │ ├── FileOrigin.* # Abstract file origin interface │ └── OriginManager.* ├── 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) ``` 3. **Bootstrap sequence:** - FreeCAD core init → loads `src/Mod/Create/Init.py` - `setup_kindred_addons()` adds ztools + silo to `sys.path`, runs their `Init.py` - GUI phase: `InitGui.py` → `setup_kindred_workbenches()` registers workbenches - Deferred QTimer cascade: Silo origin (1.5s) → auth panel (2s) → first-start check (3s) → activity panel (4s) → update check (10s) 4. **Origin system architecture:** - `FileOrigin` (abstract C++ interface) → `LocalFileOrigin` + `SiloOrigin` - `OriginManager` — lifecycle, switching, capability queries - `OriginSelectorWidget` — File toolbar dropdown - Commands: Commit / Pull / Push / Info / BOM — delegate to active origin 5. **Module interaction model:** - ztools injects into PartDesign via `_ZToolsPartDesignManipulator` - Silo registers as a `FileOrigin` backend - Create module is the glue — no feature code, just bootstrap and version 6. **Key design principles:** - Minimal core modifications — prefer submodule addons - Graceful degradation — Create runs without ztools/Silo if submodules are missing - Pure Python addons following FreeCAD's standard addon pattern - No changes to FreeCAD's container models (Part, Body, Assembly) ### Replaces The existing `docs/ARCHITECTURE.md` is a brief auto-generated summary. This issue calls for a proper architectural document with diagrams. ### Key source files to reference - `src/Mod/Create/Init.py`, `src/Mod/Create/InitGui.py` — bootstrap - `src/Gui/FileOrigin.h`, `src/Gui/OriginManager.h` — origin system - `src/Gui/CommandOrigin.cpp` — origin commands - `src/Gui/OriginSelectorWidget.h` — UI integration - `mods/ztools/ztools/ztools/InitGui.py` — workbench + manipulator registration - `mods/silo/freecad/InitGui.py` — Silo workbench registration ### Acceptance criteria - [ ] Three-layer model is clearly explained with a diagram - [ ] Bootstrap sequence is documented step-by-step with timings - [ ] Origin system architecture is explained with class relationships - [ ] A reader understands how ztools, Silo, and Create module interact
forbes added the documentation label 2026-02-09 13:45:22 +00:00
forbes commented 2026-02-09 14:13:46 +00:00
Author
Owner
Copy Link

Superseded by the mdBook documentation structure set up in PR #105. The content scope of this issue is now covered by the pages in docs/src/. Remaining content work is tracked in #104.

Superseded by the mdBook documentation structure set up in PR #105. The content scope of this issue is now covered by the pages in `docs/src/`. Remaining content work is tracked in #104.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
UX
branding
bug
ci/cd
CI/CD workflows and deployment
 defaults
documentation
Developer documentation
 enhancement
high-priority
low-priority
theme
No Label documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
forbes
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: kindred/create#89
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?