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

docs: update stale documentation to reflect current state

Browse Source 
Closes #1 — Bring documentation in line with implemented features.

GAP_ANALYSIS.md:
- Mark auth system and audit log gaps as Implemented
- Replace FreeCAD Integration section with Client Integration (silo-mod)
- Update Phase 2 sections: auth and audit marked COMPLETE
- Update Appendix A file structure and Appendix B endpoints

STATUS.md:
- Update client integrations to reference silo-mod and silo-calc repos
- Update unit tests row to remove pkg/calc/tests reference

ROADMAP.md:
- Update executive summary with links to silo-mod and silo-calc
- Update unit tests row, CAD gap section references

SPECIFICATION.md:
- Update architecture overview to reference silo-mod and silo-calc
- Update Section 5 Client Integration with both repos

REPOSITORY_STATUS.md:
- Remove Python/FreeCAD row from language stats, update totals
This commit is contained in:
Forbes
2026-02-06 16:18:58 -06:00
parent 31586755b7
commit 004dc9aef0
5 changed files with 356 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/GAP_ANALYSIS.md
View File

@@ -1,7 +1,7 @@
# Silo Gap Analysis and Revision Control Roadmap
**Date:** 2026-01-24
**Status:** Analysis Complete
**Date:** 2026-02-06
**Status:** Analysis Complete (Updated)
---
@@ -41,7 +41,6 @@ This document analyzes the current state of the Silo project against its specifi
| Gap | Impact | Effort |
|-----|--------|--------|
| **User Workflows** | Users lack step-by-step guidance | Medium |
| **FreeCAD Command Reference** | Addon features undiscoverable | Low |
| **Troubleshooting Guide** | Support burden increases | Medium |
| **Developer Setup Guide** | Onboarding friction | Low |
@@ -112,15 +111,9 @@ CREATE TABLE revisions (
| `/api/items/{pn}/file` | GET | Implemented (latest) |
| `/api/items/{pn}/file/{rev}` | GET | Implemented |
### 2.4 FreeCAD Integration
### 2.4 Client Integration
| Command | Function | Status |
|---------|----------|--------|
| `Silo_Save` | Auto-save + upload | Implemented |
| `Silo_Commit` | Save with comment | Implemented |
| `Silo_Pull` | Download/create | Implemented |
| `Silo_Push` | Batch upload | Implemented |
| `Silo_Info` | View revision history | Implemented |
FreeCAD workbench maintained in separate [silo-mod](https://git.kindred-systems.com/kindred/silo-mod) repository. The server provides the revision and file endpoints consumed by the workbench.
---
@@ -141,7 +134,7 @@ CREATE TABLE revisions (
|-----|-------------|--------|--------|
| **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 |
| ~~**No audit log**~~ | ~~Actions not logged separately~~ | ~~Compliance gap~~ | **Implemented** (migration 009, `audit_log` table + completeness scoring) |
| **Thumbnail missing** | Schema exists, not populated | No visual preview | Open |
### 3.3 Nice-to-Have Gaps
@@ -175,7 +168,7 @@ All Phase 1 items have been implemented:
#### 2.1 Pessimistic Locking
```
Effort: High | Priority: High | Risk: Medium
Effort: High | Priority: High | Risk: Medium | Status: Not Started
```
**Database Migration:**
@@ -201,56 +194,20 @@ DELETE /api/items/{pn}/lock # Release lock
GET /api/items/{pn}/lock # Check lock status
```
**FreeCAD Integration:**
- Auto-lock on `Silo_Pull` (configurable)
- Auto-unlock on `Silo_Save`/`Silo_Commit`
- Show lock status in `Silo_Info`
#### 2.2 Authentication -- COMPLETE
#### 2.2 Authentication (LDAP/FreeIPA)
```
Effort: High | Priority: High | Risk: Medium
```
Authentication is fully implemented with three backends (local/bcrypt, LDAP/FreeIPA, OIDC/Keycloak), role-based access control (admin > editor > viewer), API token management, and PostgreSQL-backed sessions. See `docs/AUTH.md` for full details.
**Changes Required:**
- Add `internal/auth/` package
- LDAP bind configuration in config.yaml
- Middleware for API authentication
- `created_by` populated from authenticated user
- Migration: `009_auth.sql`
- Code: `internal/auth/`, `internal/api/middleware.go`
**Configuration:**
```yaml
auth:
enabled: true
provider: ldap
ldap:
server: ldap://freeipa.example.com
base_dn: cn=users,cn=accounts,dc=example,dc=com
bind_dn: uid=silo-service,cn=users,...
bind_password_env: LDAP_BIND_PASSWORD
```
#### 2.3 Audit Logging -- COMPLETE
#### 2.3 Audit Logging
```
Effort: Medium | Priority: Medium | Risk: Low
```
Audit logging is implemented via migration 009 with the `audit_log` table and completeness scoring system. Endpoints:
- `GET /api/audit/completeness` — summary of all items
- `GET /api/audit/completeness/{partNumber}` — per-item scoring with weighted fields and tier classification
**Database Migration:**
```sql
CREATE TABLE audit_log (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
timestamp TIMESTAMPTZ NOT NULL DEFAULT now(),
user_id TEXT NOT NULL,
action TEXT NOT NULL, -- 'create', 'update', 'delete', 'lock', 'unlock'
resource_type TEXT NOT NULL, -- 'item', 'revision', 'project', 'relationship'
resource_id TEXT NOT NULL,
details JSONB,
ip_address TEXT
);
CREATE INDEX idx_audit_timestamp ON audit_log(timestamp DESC);
CREATE INDEX idx_audit_user ON audit_log(user_id);
CREATE INDEX idx_audit_resource ON audit_log(resource_type, resource_id);
```
Code: `internal/api/handlers_audit.go`
---
@@ -334,11 +291,14 @@ Effort: Medium | Priority: Low | Risk: Low
2. ~~**Rollback Support**~~ - Implemented
3. ~~**Revision Labels/Status**~~ - Implemented (migration 007)
### Recently Completed
4. ~~**Authentication**~~ - Implemented (3 backends: local, LDAP, OIDC; RBAC; API tokens; sessions)
5. ~~**Audit Logging**~~ - Implemented (audit_log table, completeness scoring)
### Next (Short-term)
4. **Pessimistic Locking** - Required before multi-user
5. **Authentication** - Required before production deployment
6. **Audit Logging** - Compliance and debugging
6. **Pessimistic Locking** - Required before multi-user
### Medium-term (3-6 Months)
@@ -389,26 +349,35 @@ These design decisions remain unresolved:
---
## Appendix A: File Structure for New Features
## Appendix A: File Structure
Revision endpoints, status, and labels are already implemented in the existing handler files. Future features would add:
Revision endpoints, status, labels, authentication, and audit logging are implemented. Current structure:
```
internal/
api/
handlers_audit.go # Audit/completeness endpoints (implemented)
middleware.go # Auth middleware (implemented)
auth/
auth.go # Auth service: local, LDAP, OIDC (implemented)
migrations/
008_odoo_integration.sql # Odoo ERP tables (implemented)
009_auth.sql # Auth + audit tables (implemented)
010_item_extended_fields.sql # Extended item fields (implemented)
```
Future features would add:
```
internal/
api/
handlers_lock.go # Locking endpoints
handlers_audit.go # Audit log endpoints
auth/
ldap.go # LDAP authentication
middleware.go # Auth middleware
db/
locks.go # Lock repository
audit.go # Audit repository
releases.go # Release repository
migrations/
008_item_locks.sql # Locking table
009_audit_log.sql # Audit logging
010_releases.sql # Release management
011_item_locks.sql # Locking table
012_releases.sql # Release management
```
---
@@ -423,14 +392,29 @@ PATCH /api/items/{pn}/revisions/{rev} # Update status/labels
```
### Phase 2 Endpoints
**Authentication (Implemented):**
```
GET /api/auth/me # Current user info
GET /api/auth/tokens # List API tokens
POST /api/auth/tokens # Create API token
DELETE /api/auth/tokens/{id} # Revoke API token
```
**Audit (Implemented):**
```
GET /api/audit/completeness # All items completeness summary
GET /api/audit/completeness/{partNumber} # Per-item scoring
```
**Locking (Not Implemented):**
```
POST /api/items/{pn}/lock # Acquire lock
DELETE /api/items/{pn}/lock # Release lock
GET /api/items/{pn}/lock # Check lock status
GET /api/audit # Query audit log
```
### Phase 3 Endpoints
### Phase 3 Endpoints (Not Implemented)
```
GET /api/releases # List releases
POST /api/releases # Create release