# Silo

Silo is an item database and part management system for Kindred Create. It provides revision-controlled storage for CAD files, configurable part number generation, BOM management, and team collaboration.

- **Submodule path:** `mods/silo/`
- **Source:** `git.kindred-systems.com/kindred/silo-mod`

## Architecture

Silo has three components:

```
┌──────────────────────┐     ┌──────────────┐
│  FreeCAD Workbench   │────▶│  Go REST API  │
│  (Python commands)   │     │  (silod)      │
└──────────────────────┘     └──────┬───────┘
         │                          │
         │  silo-client             │
         │  (shared API lib)        │
         │                    ┌─────┴─────┐
         │                    │           │
         │               PostgreSQL    MinIO
         │               (metadata)  (files)
         │
    Local .FCStd files
```

- **Go REST API server** (`cmd/silod/`) — 38+ routes, backed by PostgreSQL and MinIO
- **FreeCAD workbench** (`freecad/`) — Python commands integrated into Kindred Create
- **Shared API client** (`silo-client/`) — Python library used by the workbench (nested submodule)

The silo-mod repository was split from a monorepo into three repos: `silo-client` (shared Python API client), `silo-mod` (FreeCAD workbench), and `silo-calc` (LibreOffice Calc extension).

## Workbench commands

### Document lifecycle

| Command | Shortcut | Description |
|---------|----------|-------------|
| `Silo_New` | Ctrl+N | Schema-driven item creation form — domain/subcategory picker, dynamic property fields loaded from the schema API, live part number preview, sourcing fields, and project tagging |
| `Silo_Open` | Ctrl+O | Search and open items — combined dialog querying both the database and local files |
| `Silo_Save` | Ctrl+S | Save locally to canonical path, collect document properties, upload to MinIO as auto-revision |
| `Silo_Commit` | Ctrl+Shift+S | Save as a new revision with a user-provided comment |
| `Silo_Pull` | — | Download from MinIO with revision selection, conflict detection, and progress tracking |
| `Silo_Push` | — | Batch upload — finds local files not yet synced to the server, compares timestamps |

### Information and management

| Command | Description |
|---------|-------------|
| `Silo_Info` | Show item metadata, project tags, and revision history table with status and labels |
| `Silo_BOM` | Two-tab view: BOM (children) and Where Used (parents). Add, edit, remove entries with quantity and unit tracking |
| `Silo_TagProjects` | Multi-select dialog for assigning project tags to items |
| `Silo_Rollback` | Select a previous revision and create a new revision from that point with optional comment |
| `Silo_SetStatus` | Change revision lifecycle status: draft → review → released → obsolete |

### Administration

| Command | Description |
|---------|-------------|
| `Silo_Settings` | Full settings UI — API URL, SSL verify, custom CA cert, API token management, authentication status |
| `Silo_Auth` | Session-based login: `/login` → `/api/auth/me` → `/api/auth/tokens`; stores API token in preferences |
| `Silo_ToggleMode` | Switch between Silo workbench and other workbenches (menu only) |

## Origin integration

Silo registers as a **file origin** via the `FileOrigin` interface in `src/Gui/`. The `SiloOrigin` class in `silo_origin.py` implements:

| Capability | Value |
|------------|-------|
| `id` | `"silo"` |
| `name` | `"Kindred Silo"` |
| `type` | PLM (1) |
| `tracksExternally` | true |
| `requiresAuthentication` | true |
| `supportsRevisions` | true |
| `supportsBOM` | true |
| `supportsPartNumbers` | true |
| `supportsAssemblies` | true |

The origin delegates to the workbench commands for all operations (new, open, save, commit, pull, push, info, BOM). Registration happens via a deferred QTimer (1500ms after startup) in `src/Mod/Create/InitGui.py`.

## Configuration

### FreeCAD parameters

Stored in `User parameter:BaseApp/Preferences/Mod/KindredSilo`:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ApiUrl` | String | (empty) | Silo server URL |
| `SslVerify` | Bool | true | Verify SSL certificates |
| `CaCertPath` | String | (empty) | Path to custom CA certificate |
| `ApiToken` | String | (empty) | Stored authentication token |
| `FirstStartChecked` | Bool | false | Whether first-start prompt has been shown |
| `ProjectsDir` | String | `~/projects` | Local directory for checked-out files |

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SILO_API_URL` | `http://localhost:8080/api` | Override for server API endpoint |
| `SILO_PROJECTS_DIR` | `~/projects` | Override for local projects directory |

## Server

The Silo server is documented in detail in the [Silo Server](../silo-server/overview.md) section:

- [Configuration](../silo-server/CONFIGURATION.md) — YAML config, database, MinIO, auth settings
- [Deployment](../silo-server/DEPLOYMENT.md) — Docker Compose, systemd, production setup
- [Specification](../silo-server/SPECIFICATION.md) — Full API specification with 38+ routes
- [Authentication](../silo-server/AUTH.md) — LDAP, OIDC, and local auth backends

## Directory structure

```
mods/silo/
├── cmd/
│   ├── silo/                  # CLI tool
│   └── silod/                 # API server
├── internal/
│   ├── api/                   # HTTP handlers, routes, templates
│   ├── config/                # Configuration loading
│   ├── db/                    # PostgreSQL access
│   ├── migration/             # Property migration utilities
│   ├── partnum/               # Part number generation
│   ├── schema/                # YAML schema parsing
│   └── storage/               # MinIO file storage
├── freecad/
│   ├── InitGui.py             # SiloWorkbench registration
│   ├── schema_form.py         # Schema-driven item creation dialog (SchemaFormDialog)
│   ├── silo_commands.py       # 14 commands + dock widgets
│   ├── silo_origin.py         # FileOrigin backend
│   ├── silo_start.py          # Native start panel (database items, activity feed)
│   └── resources/icons/       # 10 silo-*.svg icons
├── silo-client/               # Shared Python API client (nested submodule)
│   └── silo_client/
│       ├── client.py          # SiloClient HTTP wrapper
│       └── settings.py        # SiloSettings config management
├── migrations/                # 10 numbered SQL scripts
├── schemas/                   # Part numbering YAML schemas
└── deployments/               # Docker Compose + systemd configs
```

## Further reading

- `mods/silo/README.md` — server quickstart and CLI usage
- `mods/silo/ROADMAP.md` — strategic roadmap (6 phases, Q2 2026 → Q4 2027)