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

docs: write SILO.md — Go server, workbench commands, migrations, and deployment #92

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

Tier 2 — Component Guide

File: docs/SILO.md

What this document should cover

  1. Overview — Silo is a parts database system with revision control, BOM management, and team collaboration

    • Submodule: mods/silo/ → git.kindred-systems.com/kindred/silo-mod
    • Pinned commit: f9924d3
    • Three-repo split: silo-client (shared API client), silo-mod (FreeCAD workbench), silo-calc (LibreOffice Calc extension)

  2. Architecture:

    • Go REST API server (38+ routes) — cmd/, internal/, pkg/
    • PostgreSQL database for metadata, revisions, BOM
    • MinIO S3-compatible object storage for binary .FCStd files
    • LDAP/OIDC authentication
    • SSE (Server-Sent Events) for real-time activity feed

  3. FreeCAD workbench (freecad/):

    • InitGui.py — SiloWorkbench registration
    • silo_commands.py — 14 commands + dock widgets
    • silo_origin.py — FileOrigin backend implementation
    • Document all 14 commands:
      • File ops: New, Open, Save, Commit, Pull, Push
      • Info: Info, BOM (Bill of Materials)
      • Admin: TagProjects, Rollback, SetStatus, Settings, Auth
    • Icons: 10 silo-*.svg in resources/icons/

  4. Silo client library (silo-client/ nested submodule):

    • SiloClient — API wrapper
    • SiloSettings — configuration management
    • Authentication flow

  5. Server internals:

    • Route structure (38+ routes)
    • Handler organization in internal/
    • Database schema overview
    • MinIO integration

  6. Migration authoring guide (migrations/):

    • How migrations are structured
    • How to add a new migration
    • Running migrations against dev database
    • Rollback procedures

  7. Deployment:

    • deployments/ directory structure
    • Server configuration
    • Database setup
    • MinIO setup
    • LDAP/OIDC configuration

  8. Origin integration:

    • How SiloOrigin implements the FileOrigin interface
    • Registration flow via QTimer in src/Mod/Create/InitGui.py
    • Capability advertisement (which commands Silo supports)

Key source files

  • mods/silo/freecad/InitGui.py — workbench registration
  • mods/silo/freecad/silo_commands.py — all 14 commands
  • mods/silo/freecad/silo_origin.py — FileOrigin backend
  • mods/silo/silo-client/silo_client/ — API client
  • mods/silo/cmd/ — Go server entry point
  • mods/silo/internal/ — server handlers
  • mods/silo/migrations/ — database migrations
  • mods/silo/deployments/ — deployment configs
  • mods/silo/README.md, mods/silo/ROADMAP.md — existing docs

Acceptance criteria

  • All 14 workbench commands are documented
  • Server architecture is explained with component diagram
  • Migration authoring guide is actionable
  • Deployment steps are documented
  • Origin integration flow is clear
## Tier 2 — Component Guide **File:** `docs/SILO.md` ### What this document should cover 1. **Overview** — Silo is a parts database system with revision control, BOM management, and team collaboration - Submodule: `mods/silo/` → `git.kindred-systems.com/kindred/silo-mod` - Pinned commit: `f9924d3` - Three-repo split: `silo-client` (shared API client), `silo-mod` (FreeCAD workbench), `silo-calc` (LibreOffice Calc extension) 2. **Architecture:** - Go REST API server (38+ routes) — `cmd/`, `internal/`, `pkg/` - PostgreSQL database for metadata, revisions, BOM - MinIO S3-compatible object storage for binary `.FCStd` files - LDAP/OIDC authentication - SSE (Server-Sent Events) for real-time activity feed 3. **FreeCAD workbench** (`freecad/`): - `InitGui.py` — SiloWorkbench registration - `silo_commands.py` — 14 commands + dock widgets - `silo_origin.py` — FileOrigin backend implementation - Document all 14 commands: - File ops: New, Open, Save, Commit, Pull, Push - Info: Info, BOM (Bill of Materials) - Admin: TagProjects, Rollback, SetStatus, Settings, Auth - Icons: 10 silo-*.svg in `resources/icons/` 4. **Silo client library** (`silo-client/` nested submodule): - `SiloClient` — API wrapper - `SiloSettings` — configuration management - Authentication flow 5. **Server internals:** - Route structure (38+ routes) - Handler organization in `internal/` - Database schema overview - MinIO integration 6. **Migration authoring guide** (`migrations/`): - How migrations are structured - How to add a new migration - Running migrations against dev database - Rollback procedures 7. **Deployment:** - `deployments/` directory structure - Server configuration - Database setup - MinIO setup - LDAP/OIDC configuration 8. **Origin integration:** - How `SiloOrigin` implements the `FileOrigin` interface - Registration flow via QTimer in `src/Mod/Create/InitGui.py` - Capability advertisement (which commands Silo supports) ### Key source files - `mods/silo/freecad/InitGui.py` — workbench registration - `mods/silo/freecad/silo_commands.py` — all 14 commands - `mods/silo/freecad/silo_origin.py` — FileOrigin backend - `mods/silo/silo-client/silo_client/` — API client - `mods/silo/cmd/` — Go server entry point - `mods/silo/internal/` — server handlers - `mods/silo/migrations/` — database migrations - `mods/silo/deployments/` — deployment configs - `mods/silo/README.md`, `mods/silo/ROADMAP.md` — existing docs ### Acceptance criteria - [ ] All 14 workbench commands are documented - [ ] Server architecture is explained with component diagram - [ ] Migration authoring guide is actionable - [ ] Deployment steps are documented - [ ] Origin integration flow is clear
forbes added the documentation label 2026-02-09 13:45:23 +00:00
forbes commented 2026-02-09 14:13:48 +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#92
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?