kindred/silo
1
1
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation and specs

Browse Source
This commit is contained in:
Forbes
2026-01-29 13:10:12 -06:00
parent d886a44288
commit f39aef0fc7
10 changed files with 546 additions and 1224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
docs/GAP_ANALYSIS.md
View File

@@ -17,21 +17,24 @@ This document analyzes the current state of the Silo project against its specifi
| Document | Coverage | Status |
|----------|----------|--------|
| `README.md` | Quick start, overview | Partial (50%) |
| `docs/SPECIFICATION.md` | Design specification | Comprehensive (90%) |
| `docs/STATUS.md` | Development progress | Current but incomplete |
| `silo-spec.md` | Duplicate of SPECIFICATION.md | Redundant |
| `README.md` | Quick start, overview, component map | Current |
| `docs/SPECIFICATION.md` | Design specification, API reference | Current |
| `docs/STATUS.md` | Implementation status summary | Current |
| `docs/DEPLOYMENT.md` | Production deployment guide | Current |
| `docs/GAP_ANALYSIS.md` | SOLIDWORKS PDM comparison, roadmap | Current |
| `ROADMAP.md` | Feature roadmap and phases | Current |
| `silo-spec.md` | Redirect to `docs/SPECIFICATION.md` | Consolidated |
### 1.2 Documentation Gaps (Priority Order)
#### High Priority
| Gap | Impact | Effort |
|-----|--------|--------|
| **API Reference** | Users cannot integrate programmatically | Medium |
| **Deployment Guide** | Cannot deploy to production | Medium |
| **Database Schema Guide** | Migration troubleshooting difficult | Low |
| **Configuration Reference** | config.yaml options undocumented | Low |
| Gap | Impact | Effort | Status |
|-----|--------|--------|--------|
| **API Reference** | Users cannot integrate programmatically | Medium | Addressed in SPECIFICATION.md Section 11 |
| **Deployment Guide** | Cannot deploy to production | Medium | Complete (`docs/DEPLOYMENT.md`) |
| **Database Schema Guide** | Migration troubleshooting difficult | Low | Open |
| **Configuration Reference** | config.yaml options undocumented | Low | Open |
#### Medium Priority
@@ -52,10 +55,11 @@ This document analyzes the current state of the Silo project against its specifi
### 1.3 Recommended Actions
1. **Consolidate specs**: Remove `silo-spec.md` duplicate
2. **Create `docs/API.md`**: Full REST endpoint documentation with examples
3. **Create `docs/DEPLOYMENT.md`**: Production deployment guide
4. **Expand README.md**: Add configuration reference section
1. ~~**Consolidate specs**: Remove `silo-spec.md` duplicate~~ Done
2. ~~**Create API reference**: Full REST endpoint documentation~~ Addressed in SPECIFICATION.md
3. ~~**Create `docs/DEPLOYMENT.md`**: Production deployment guide~~ Done
4. **Create configuration reference**: Document all `config.yaml` options
5. **Create database schema guide**: Document migrations and troubleshooting
---
@@ -124,21 +128,21 @@ CREATE TABLE revisions (
### 3.1 Critical Gaps
| Gap | Description | Impact |
|-----|-------------|--------|
| **No rollback** | Cannot revert to previous revision | Data recovery difficult |
| **No comparison** | Cannot diff between revisions | Change tracking manual |
| **No locking** | No concurrent edit protection | Multi-user unsafe |
| **No approval workflow** | No release/sign-off process | Quality control gap |
| Gap | Description | Impact | Status |
|-----|-------------|--------|--------|
| ~~**No rollback**~~ | ~~Cannot revert to previous revision~~ | ~~Data recovery difficult~~ | **Implemented** |
| ~~**No comparison**~~ | ~~Cannot diff between revisions~~ | ~~Change tracking manual~~ | **Implemented** |
| **No locking** | No concurrent edit protection | Multi-user unsafe | Open |
| **No approval workflow** | No release/sign-off process | Quality control gap | Open |
### 3.2 Important Gaps
| Gap | Description | Impact |
|-----|-------------|--------|
| **No branching** | Linear history only | No experimental variants |
| **No tagging** | No named milestones | Release tracking manual |
| **No audit log** | Actions not logged separately | Compliance gap |
| **Thumbnail missing** | Schema exists, not populated | No visual preview |
| Gap | Description | Impact | Status |
|-----|-------------|--------|--------|
| **No branching** | Linear history only | No experimental variants | Open |
| ~~**No tagging**~~ | ~~No named milestones~~ | ~~Release tracking manual~~ | **Implemented** (revision labels) |
| **No audit log** | Actions not logged separately | Compliance gap | Open |
| **Thumbnail missing** | Schema exists, not populated | No visual preview | Open |
### 3.3 Nice-to-Have Gaps
@@ -153,66 +157,15 @@ CREATE TABLE revisions (
## 4. Revision Control Roadmap
### Phase 1: Foundation (Recommended First)
### Phase 1: Foundation -- COMPLETE
**Goal:** Enable safe single-user revision management
#### 1.1 Rollback Support
```
Effort: Medium | Priority: High | Risk: Low
```
All Phase 1 items have been implemented:
**Changes Required:**
- Add `POST /api/items/{pn}/rollback/{rev}` endpoint
- Create new revision copying properties/file from target revision
- FreeCAD: Add `Silo_Rollback` command
**Database:** No schema changes needed (creates new revision from old)
#### 1.2 Revision Comparison API
```
Effort: Medium | Priority: High | Risk: Low
```
**Changes Required:**
- Add `GET /api/items/{pn}/revisions/compare?from={rev1}&to={rev2}` endpoint
- Return property diff (added/removed/changed keys)
- Return file metadata diff (size, checksum changes)
**Implementation:**
```go
type RevisionDiff struct {
FromRevision int `json:"from_revision"`
ToRevision int `json:"to_revision"`
Properties PropertyDiff `json:"properties"`
FileChanged bool `json:"file_changed"`
FileSizeDiff int64 `json:"file_size_diff,omitempty"`
}
type PropertyDiff struct {
Added map[string]any `json:"added,omitempty"`
Removed map[string]any `json:"removed,omitempty"`
Changed map[string]PropertyChange `json:"changed,omitempty"`
}
```
#### 1.3 Revision Labels/Status
```
Effort: Low | Priority: Medium | Risk: Low
```
**Database Migration:**
```sql
ALTER TABLE revisions ADD COLUMN status TEXT DEFAULT 'draft';
-- Values: 'draft', 'review', 'released', 'obsolete'
ALTER TABLE revisions ADD COLUMN labels TEXT[] DEFAULT '{}';
-- Arbitrary tags: ['prototype', 'v1.0', 'customer-approved']
```
**API Changes:**
- Add `PATCH /api/items/{pn}/revisions/{rev}` for status/label updates
- Add filtering by status in list endpoint
- **Rollback**: `POST /api/items/{pn}/revisions/{rev}/rollback` - creates new revision from old
- **Revision Comparison**: `GET /api/items/{pn}/revisions/compare?from={rev1}&to={rev2}` - property and file diffs
- **Revision Labels/Status**: `PATCH /api/items/{pn}/revisions/{rev}` - status (draft/review/released/obsolete) and arbitrary labels via migration 007
---
@@ -375,13 +328,13 @@ Effort: Medium | Priority: Low | Risk: Low
## 5. Recommended Implementation Order
### Immediate (Next Sprint)
### Completed
1. **Revision Comparison API** - High value, low risk
2. **Rollback Support** - Critical for data safety
3. **Revision Labels** - Quick win for workflow
1. ~~**Revision Comparison API**~~ - Implemented
2. ~~**Rollback Support**~~ - Implemented
3. ~~**Revision Labels/Status**~~ - Implemented (migration 007)
### Short-term (1-2 Months)
### Next (Short-term)
4. **Pessimistic Locking** - Required before multi-user
5. **Authentication** - Required before production deployment
@@ -438,10 +391,11 @@ These design decisions remain unresolved:
## Appendix A: File Structure for New Features
Revision endpoints, status, and labels are already implemented in the existing handler files. Future features would add:
```
internal/
api/
handlers_revision.go # New revision endpoints
handlers_lock.go # Locking endpoints
handlers_audit.go # Audit log endpoints
auth/
@@ -452,7 +406,6 @@ internal/
audit.go # Audit repository
releases.go # Release repository
migrations/
007_revision_status.sql # Labels and status
008_item_locks.sql # Locking table
009_audit_log.sql # Audit logging
010_releases.sql # Release management
@@ -462,11 +415,11 @@ migrations/
## Appendix B: API Additions Summary
### Phase 1 Endpoints
### Phase 1 Endpoints (Implemented)
```
GET /api/items/{pn}/revisions/compare # Diff two revisions
POST /api/items/{pn}/rollback/{rev} # Create revision from old
PATCH /api/items/{pn}/revisions/{rev} # Update status/labels
GET /api/items/{pn}/revisions/compare # Diff two revisions
POST /api/items/{pn}/revisions/{rev}/rollback # Create revision from old
PATCH /api/items/{pn}/revisions/{rev} # Update status/labels
```
### Phase 2 Endpoints

283
docs/SPECIFICATION.md
View File

@@ -75,8 +75,8 @@ Silo treats **part numbering schemas as configuration, not code**. Multiple numb
| Database | PostgreSQL | Existing instance at psql.kindred.internal |
| File Storage | MinIO | S3-compatible, versioning enabled |
| FreeCAD Integration | Python workbench | Macro-style commands |
| CLI | Go or Python | TBD based on complexity |
| Web UI | Go + htmx | Lightweight, minimal JS |
| CLI & API Server | Go (1.23) | chi/v5 router, pgx/v5 driver, zerolog |
| Web UI | Go html/template + htmx | Lightweight, minimal JS |
---
@@ -186,7 +186,7 @@ Schemas define how part numbers are generated. Each schema consists of **segment
# /etc/silo/schemas/kindred-rd.yaml
schema:
name: kindred-rd
version: 1
version: 3
description: "Kindred Systems R&D part numbering"
# Separator between segments (default: "-")
@@ -194,45 +194,47 @@ schema:
# Uniqueness enforcement
uniqueness:
scope: global # or "per-project", "per-type", "per-schema"
scope: global
case_sensitive: false
segments:
- name: project
type: string
length: 5
description: "Project identifier"
validation:
pattern: "^[A-Z0-9]{5}$"
required: true
- name: part_type
- name: category
type: enum
description: "Type of item"
values:
AS: "Assembly"
PT: "Part"
DW: "Drawing"
DC: "Document"
TB: "Tooling/Fixture"
PC: "Purchased Component"
description: "Category code (2-3 characters)"
required: true
values:
F01: "Hex Cap Screw"
F02: "Socket Head Cap Screw"
# ... 70+ categories across:
# F01-F18: Fasteners
# C01-C17: Fluid Fittings
# R01-R44: Motion Components
# S01-S17: Structural Materials
# E01-E27: Electrical Components
# M01-M18: Mechanical Components
# T01-T08: Tooling and Fixtures
# A01-A07: Assemblies
# P01-P05: Purchased/Off-the-Shelf
# X01-X08: Custom Fabricated Parts
- name: sequence
type: serial
length: 4
padding: "0" # left-pad with zeros
description: "Sequential number"
scope: "{project}-{part_type}" # counter scope (template)
padding: "0"
start: 1
description: "Sequential number within category"
scope: "{category}"
# Format template (optional, defaults to joining segments with separator)
format: "{project}-{part_type}-{sequence}"
format: "{category}-{sequence}"
# Example outputs:
# PROTO-AS-0001 (first assembly in PROTO project)
# PROTO-PT-0001 (first part in PROTO project)
# ALPHA-AS-0001 (first assembly in ALPHA project)
# F01-0001 (first hex cap screw)
# R27-0001 (first linear rail)
# A01-0001 (first assembly)
```
> **Note:** The schema was migrated from a `{project}-{type}-{sequence}` format (v1) to `{category}-{sequence}` (v3). Projects are now managed as many-to-many tags on items rather than embedded in the part number. See `migrations/006_project_tags.sql`.
### 4.2 Segment Types
| Type | Description | Options |
@@ -248,11 +250,8 @@ schema:
The `scope` field in serial segments supports template variables referencing other segments:
```yaml
# Sequence per project
scope: "{project}"
# Sequence per project AND type (recommended for R&D)
scope: "{project}-{part_type}"
# Sequence per category (current kindred-rd schema)
scope: "{category}"
# Global sequence (no scope)
scope: null
@@ -352,19 +351,18 @@ assembly_config:
### 5.1 Workbench Commands
The Silo workbench provides git-like commands accessible via toolbar, menu, and Python console:
The Silo workbench provides toolbar commands in FreeCAD:
| Command | Description |
|---------|-------------|
| `silo init` | Initialize Silo tracking for current document |
| `silo status` | Show tracked/untracked objects, modifications |
| `silo checkout <part_number>` | Load item from Silo into current document |
| `silo commit` | Save current state as new revision |
| `silo log` | Show revision history |
| `silo diff` | Compare current state to last committed revision |
| `silo register` | Generate part number for selected object(s) |
| `silo link` | Create relationship between objects |
| `silo bom` | Generate BOM from current assembly |
| Command | Description | Status |
|---------|-------------|--------|
| `Silo_Save` | Auto-save document and upload to MinIO | Implemented |
| `Silo_Commit` | Save with revision comment | Implemented |
| `Silo_Pull` | Download item by part number / create new | Implemented |
| `Silo_Push` | Batch upload modified files | Implemented |
| `Silo_Info` | View revision history for current item | Implemented |
| `Silo_Register` | Generate part number for current document | Implemented |
| `Silo_Open` | Open item from Silo by part number | Implemented |
| `Silo_Browse` | Browse items in a list dialog | Implemented |
### 5.2 Property Synchronization
@@ -566,77 +564,118 @@ auth:
---
## 11. API Design (Sketch)
## 11. API Design
### 11.1 REST Endpoints
### 11.1 REST Endpoints (Implemented)
```
# Items
GET /api/items # List/search items
POST /api/items # Create item
GET /api/items/{part_number} # Get item details
PUT /api/items/{part_number} # Update item (creates revision)
DELETE /api/items/{part_number} # Archive item
# Health
GET /health # Basic health check
GET /ready # Readiness (DB + MinIO)
# Revisions
GET /api/items/{part_number}/revisions
GET /api/items/{part_number}/revisions/{rev}
# Relationships
GET /api/items/{part_number}/bom
POST /api/items/{part_number}/relationships
DELETE /api/items/{part_number}/relationships/{id}
# Files
GET /api/items/{part_number}/file
PUT /api/items/{part_number}/file
GET /api/items/{part_number}/file?rev={rev}
# Web UI
GET / # Items page
GET /schemas # Schemas page
# Schemas
GET /api/schemas
POST /api/schemas
GET /api/schemas/{name}
GET /api/schemas # List all schemas
GET /api/schemas/{name} # Get schema details
GET /api/schemas/{name}/properties # Get property schema for category
POST /api/schemas/{name}/segments/{segment}/values # Add enum value
PUT /api/schemas/{name}/segments/{segment}/values/{code} # Update enum value
DELETE /api/schemas/{name}/segments/{segment}/values/{code} # Delete enum value
# Locations
# Projects
GET /api/projects # List projects
POST /api/projects # Create project
GET /api/projects/{code} # Get project
PUT /api/projects/{code} # Update project
DELETE /api/projects/{code} # Delete project
GET /api/projects/{code}/items # Get project items
# Items
GET /api/items # List/search items
POST /api/items # Create item
GET /api/items/export.csv # Export items to CSV
POST /api/items/import # Import items from CSV
GET /api/items/template.csv # Get CSV import template
GET /api/items/{partNumber} # Get item details
PUT /api/items/{partNumber} # Update item
DELETE /api/items/{partNumber} # Archive item
# Item-Project Tags
GET /api/items/{partNumber}/projects # Get item's projects
POST /api/items/{partNumber}/projects # Add project tags
DELETE /api/items/{partNumber}/projects/{code} # Remove project tag
# Revisions
GET /api/items/{partNumber}/revisions # List revisions
POST /api/items/{partNumber}/revisions # Create revision
GET /api/items/{partNumber}/revisions/compare # Compare two revisions
GET /api/items/{partNumber}/revisions/{revision} # Get specific revision
PATCH /api/items/{partNumber}/revisions/{revision} # Update status/labels
POST /api/items/{partNumber}/revisions/{revision}/rollback # Rollback to revision
# Files
POST /api/items/{partNumber}/file # Upload file
GET /api/items/{partNumber}/file # Download latest file
GET /api/items/{partNumber}/file/{revision} # Download file at revision
# Part Number Generation
POST /api/generate-part-number # Generate without creating item
```
### 11.2 Not Yet Implemented
The following endpoints from the original design are not yet implemented:
```
# Locations (tables exist, no API)
GET /api/locations
POST /api/locations
GET /api/locations/{path}
# Inventory
GET /api/inventory/{part_number}
POST /api/inventory/{part_number}/adjust
# Part number generation
POST /api/generate-part-number
Body: { "schema": "kindred-rd", "project": "PROTO", "part_type": "AS" }
Response: { "part_number": "PROTO-AS-0001" }
# Inventory (tables exist, no API)
GET /api/inventory/{partNumber}
POST /api/inventory/{partNumber}/adjust
```
---
## 12. MVP Scope
### 12.1 Included
### 12.1 Implemented
- [ ] PostgreSQL database schema
- [ ] YAML schema parser for part numbering
- [ ] Part number generation engine
- [ ] Basic CLI for item CRUD
- [ ] FreeCAD workbench with core commands (checkout, commit, status, register)
- [ ] MinIO integration for file storage
- [ ] Single-level and multi-level BOM support
- [ ] Reference designator tracking
- [ ] Alternate part tracking
- [ ] Revision history (append-only)
- [ ] Location hierarchy (YAML-defined)
- [ ] Basic inventory tracking (quantity at location)
- [ ] Web UI for browsing and search
- [ ] "Open in FreeCAD" URI handler
- [x] PostgreSQL database schema (7 migrations)
- [x] YAML schema parser for part numbering
- [x] Part number generation engine
- [x] CLI tool (`cmd/silo`)
- [x] API server (`cmd/silod`) with 35+ endpoints
- [x] FreeCAD workbench (save, commit, pull, push, info, register, open, browse)
- [x] MinIO integration for file storage with versioning
- [x] BOM relationships (component, alternate, reference)
- [x] Reference designator tracking
- [x] Revision history (append-only) with rollback and comparison
- [x] Revision status and labels
- [x] Project management with many-to-many item tagging
- [x] CSV import/export with dry-run validation
- [x] Web UI for items and schemas (htmx)
- [x] Property schema versioning framework
- [x] Docker Compose deployment (dev and prod)
- [x] systemd service and deployment scripts
### 12.2 Excluded (Future)
### 12.2 Partially Implemented
- [ ] Location hierarchy (database tables exist, no API endpoints)
- [ ] Inventory tracking (database tables exist, no API endpoints)
- [ ] Date segment type (schema parser placeholder only)
- [ ] Part number format validation on creation
### 12.3 Not Started
- [ ] Unit tests
- [ ] Schema migration tooling
- [ ] Multi-user with authentication
- [ ] Multi-user authentication (FreeIPA/LDAP planned)
- [ ] Checkout locking
- [ ] Approval workflows
- [ ] External system integrations (ERP, purchasing)
@@ -649,7 +688,7 @@ POST /api/generate-part-number
## 13. Open Questions
1. **CLI language**: Go for consistency with web UI, or Python for FreeCAD ecosystem alignment?
1. ~~**CLI language**: Go for consistency with web UI, or Python for FreeCAD ecosystem alignment?~~ **Resolved:** Go was chosen for both CLI and API server.
2. **Property schema**: Should item properties be schema-defined (like part numbers) or freeform? Recommendation: Support both—schema defines expected properties, but allow ad-hoc additions.
@@ -682,12 +721,14 @@ POST /api/generate-part-number
### A.1 Complete Part Numbering Schema
See `schemas/kindred-rd.yaml` for the full schema (v3). Summary:
```yaml
# kindred-rd-schema.yaml
# kindred-rd-schema.yaml (abbreviated)
schema:
name: kindred-rd
version: 1
description: "Kindred Systems R&D part numbering for prototype development"
version: 3
description: "Kindred Systems R&D part numbering"
separator: "-"
@@ -696,50 +737,26 @@ schema:
case_sensitive: false
segments:
- name: project
type: string
length: 5
case: upper
description: "5-character project identifier"
validation:
pattern: "^[A-Z0-9]{5}$"
message: "Project code must be exactly 5 alphanumeric characters"
required: true
- name: part_type
- name: category
type: enum
description: "Two-character type code"
description: "Category code"
required: true
values:
AS: "Assembly - multi-part unit"
PT: "Part - single manufactured item"
DW: "Drawing - technical drawing"
DC: "Document - specification, procedure, etc."
TB: "Tooling - jigs, fixtures, molds"
PC: "Purchased - externally sourced component"
EL: "Electrical - wiring, PCB, electronics"
SW: "Software - firmware, configuration"
F01: "Hex Cap Screw"
F02: "Socket Head Cap Screw"
# ... 70+ categories (see full file)
- name: sequence
type: serial
length: 4
padding: "0"
start: 1
description: "Sequential number within project/type"
scope: "{project}-{part_type}"
description: "Sequential number within category"
scope: "{category}"
format: "{project}-{part_type}-{sequence}"
# Validation rules applied to complete part number
validation:
min_length: 14
max_length: 14
format: "{category}-{sequence}"
# Metadata for UI/documentation
examples:
- "PROTO-AS-0001"
- "ALPHA-PT-0042"
- "BETA1-EL-0003"
# Example outputs: F01-0001, R27-0001, A01-0001
```
### A.2 Complete Location Schema

179
docs/STATUS.md
View File

@@ -1,137 +1,92 @@
# Silo Development Status
**Date:** 2026-01-23
**Last Updated By:** Claude Code Session
**Last Updated:** 2026-01-29
---
## Current State: MinIO File Upload Implementation
## Implementation Status
### Completed Work
### Core Systems
#### 1. Docker Compose - MinIO Service Added
- File: `deployments/docker-compose.yaml`
- Added MinIO service with versioning enabled
- Configured healthcheck and environment variables
- Note: Using `minio/minio:RELEASE.2024-01-16T16-07-38Z` for CPU compatibility
| Component | Status | Notes |
|-----------|--------|-------|
| PostgreSQL schema | Complete | 7 migrations applied |
| YAML schema parser | Complete | Supports enum, serial, constant, string segments |
| Part number generator | Complete | Scoped sequences, category-based format |
| API server (`silod`) | Complete | 35+ REST endpoints via chi/v5 |
| CLI tool (`silo`) | Complete | Item registration and management |
| MinIO file storage | Complete | Upload, download, versioning, checksums |
| Revision control | Complete | Append-only history, rollback, comparison, status/labels |
| Project management | Complete | CRUD, many-to-many item tagging |
| CSV import/export | Complete | Dry-run validation, template generation |
| Web UI | Complete | Items and schemas pages (htmx) |
| Docker Compose | Complete | Dev and production configurations |
| Deployment scripts | Complete | setup-host, deploy, init-db, setup-ipa-nginx |
| systemd service | Complete | Unit file and environment template |
#### 2. API Endpoints - File Upload/Download
- File: `internal/api/handlers.go`
### FreeCAD Workbench
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/items/{partNumber}/file` | POST | Upload file and create revision |
| `/api/items/{partNumber}/file` | GET | Download latest revision file |
| `/api/items/{partNumber}/file/{revision}` | GET | Download specific revision file |
| `/api/items/{partNumber}/revisions` | POST | Create revision without file |
| Command | Status | Notes |
|---------|--------|-------|
| Silo_Save | Implemented | Auto-save + upload to MinIO |
| Silo_Commit | Implemented | Save with revision comment |
| Silo_Pull | Implemented | Download / create items |
| Silo_Push | Implemented | Batch upload modified files |
| Silo_Info | Implemented | View revision history |
| Silo_Register | Implemented | Generate part number for document |
| Silo_Open | Implemented | Open item by part number |
| Silo_Browse | Implemented | Browse items in list dialog |
#### 3. Routes Added
- File: `internal/api/routes.go`
- All new endpoints wired up
Workbench needs end-to-end testing with a running Silo instance.
#### 4. FreeCAD Client Updated
- File: `pkg/freecad/silo_commands.py`
- Added `_upload_file()` method for multipart form upload
- Updated `create_revision()` to optionally upload files
- Updated `Silo_Commit` command to save document and upload to MinIO
### Not Yet Implemented
#### 5. Build Status
- **Go code compiles successfully** - `go build ./...` passes
| Feature | Notes |
|---------|-------|
| Location API endpoints | Database tables exist (`locations`, `inventory`), no REST handlers |
| Inventory API endpoints | Database tables exist, no REST handlers |
| Date segment type | Schema parser placeholder only |
| Part number format validation | API accepts but does not validate format on creation |
| Unit tests | No test coverage |
---
## Where We Left Off
## Infrastructure
### Problem
MinIO container failing to start due to CPU architecture:
```
Fatal glibc error: CPU does not support x86-64-v2
```
### Solution in Progress
- VM being rebooted to newer architecture
- Already configured older MinIO image as fallback
| Service | Host | Status |
|---------|------|--------|
| PostgreSQL | psql.kindred.internal:5432 | Running |
| MinIO | localhost:9000 (API) / :9001 (console) | Configured |
| Silo API | localhost:8080 | Builds successfully |
---
## Next Steps After VM Reboot
## Schema Status
### 1. Start Services
```bash
cd /home/forbes/projects/silo-0062/deployments
sudo docker compose up -d
```
The part numbering schema (`kindred-rd`) is at **version 3** using the `{category}-{sequence}` format (e.g., `F01-0001`). This replaced the earlier `{project}-{type}-{sequence}` format. Projects are now managed as many-to-many tags rather than being embedded in part numbers.
### 2. Verify Services
```bash
# Check all services
sudo docker compose ps
# Check MinIO health
curl http://localhost:9000/minio/health/live
# Check Silo API with storage
curl http://localhost:8080/ready
```
### 3. Test File Upload
```bash
# Create test file
echo "Test content" > /tmp/test.FCStd
# Upload to existing item
curl -X POST \
-F "file=@/tmp/test.FCStd" \
-F "comment=Test upload" \
-F 'properties={"test": true}' \
http://localhost:8080/api/items/3DX15-A01-0002/file
```
### 4. Test File Download
```bash
# Download latest revision
curl http://localhost:8080/api/items/3DX15-A01-0002/file -o downloaded.FCStd
# Download specific revision
curl http://localhost:8080/api/items/3DX15-A01-0002/file/2 -o rev2.FCStd
```
### 5. Test from FreeCAD
1. Open FreeCAD with Silo workbench
2. Open an existing item: `Silo_Open` command
3. Make changes
4. Commit with file upload: `Silo_Commit` command
5. Verify file appears in MinIO console at http://localhost:9001
The schema defines 70+ categories across 10 groups:
- F01-F18: Fasteners
- C01-C17: Fluid Fittings
- R01-R44: Motion Components
- S01-S17: Structural Materials
- E01-E27: Electrical Components
- M01-M18: Mechanical Components
- T01-T08: Tooling and Fixtures
- A01-A07: Assemblies
- P01-P05: Purchased/Off-the-Shelf
- X01-X08: Custom Fabricated Parts
---
## Remaining MVP Tasks
## Database Migrations
| Task | Status | Priority |
|------|--------|----------|
| Start docker-compose with MinIO | Pending | **Next** |
| Test full upload/download flow | Pending | High |
| Implement date segment support | Pending | Medium |
| Implement part number validation | Pending | Medium |
| Add unit tests | Pending | Medium |
---
## File Changes This Session
```
modified: deployments/docker-compose.yaml (added MinIO service)
modified: internal/api/handlers.go (added file handlers)
modified: internal/api/routes.go (added file routes)
modified: pkg/freecad/silo_commands.py (added file upload)
```
---
## MinIO Console Access
Once running:
- **URL:** http://localhost:9001
- **Username:** silominio
- **Password:** silominiosecret
- **Bucket:** silo-files
| Migration | Description |
|-----------|-------------|
| 001_initial.sql | Core schema (items, revisions, relationships, locations, inventory, sequences) |
| 002_sequence_by_name.sql | Sequence naming changes |
| 003_remove_material.sql | Schema cleanup |
| 004_cad_sync_state.sql | CAD synchronization state |
| 005_property_schema_version.sql | Property versioning framework |
| 006_project_tags.sql | Many-to-many project-item relationships |
| 007_revision_status.sql | Revision status and labels |