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