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

docs: update SPECIFICATION.md for React SPA and current endpoints

Browse Source 
- Replace htmx with React SPA in architecture diagram and tech stack
- Rewrite Section 6 (Web Interface) with React SPA architecture,
  pages table, and design patterns
- Update Section 11.1: remove old web UI routes, add /api/auth/config,
  /api/uploads/presign, file attachment endpoints, thumbnail endpoint
- Fix endpoint count: 76 → 75 (actual registered routes)
- Fix migration count: 10 → 11
- Add file attachments to MVP checklist
- Update test coverage note (9 test files exist)

Closes #26
This commit is contained in:
Forbes
2026-02-08 14:11:12 -06:00
parent eb43fbb9ec
commit e3da072229
1 changed files with 47 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/SPECIFICATION.md
View File

@@ -37,13 +37,13 @@ Silo treats **part numbering schemas as configuration, not code**. Multiple numb
▼
┌─────────────────────────────────────────────────────────────┐
│ Silo Server (silod) │
│ - REST API (76 endpoints) │
│ - REST API (75 endpoints) │
│ - Authentication (local, LDAP, OIDC) │
│ - Schema parsing and validation │
│ - Part number generation engine │
│ - Revision management │
│ - Relationship graph / BOM │
│ - Web UI (htmx) │
│ - Web UI (React SPA) │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
@@ -68,7 +68,7 @@ Silo treats **part numbering schemas as configuration, not code**. Multiple numb
| CLI & API Server | Go (1.24) | chi/v5 router, pgx/v5 driver, zerolog |
| Authentication | Multi-backend | Local (bcrypt), LDAP/FreeIPA, OIDC/Keycloak |
| Sessions | PostgreSQL pgxstore | alexedwards/scs, 24h lifetime |
| Web UI | Go html/template + htmx | Lightweight, minimal JS |
| Web UI | React 19, Vite 6, TypeScript 5.7 | Catppuccin Mocha theme, inline styles |
---
@@ -362,15 +362,35 @@ Recommendation: Pessimistic locking for CAD files (merge is impractical).
## 6. Web Interface
### 6.1 Features
### 6.1 Architecture
- **Browse**: Navigate item hierarchy (project → assembly → subassembly → part)
- **Search**: Full-text search across part numbers, descriptions, properties
- **View**: Item details, revision history, relationships, location
- **BOM Viewer**: Expandable tree view of assembly structure
- **"Open in FreeCAD"**: Launch FreeCAD with specific item via URI handler
The web UI is a React single-page application served at `/` by the Go server. The SPA communicates with the backend exclusively via the JSON REST API at `/api/*`.
### 6.2 URI Handler
- **Stack**: React 19, React Router 7, Vite 6, TypeScript 5.7
- **Theme**: Catppuccin Mocha (dark) via CSS custom properties
- **Styling**: Inline `React.CSSProperties` — no CSS modules, no Tailwind
- **State**: Local `useState` + custom hooks (no Redux/Zustand)
- **SPA serving**: `web/dist/` served by Go's `NotFound` handler with `index.html` fallback for client-side routing
### 6.2 Pages
| Page | Route | Description |
|------|-------|-------------|
| Items | `/` | Master-detail layout with resizable split panel, sortable table, 5-tab detail view (Main, Properties, Revisions, BOM, Where Used), in-pane CRUD forms |
| Projects | `/projects` | Project CRUD with sortable table, in-pane forms |
| Schemas | `/schemas` | Schema browser with collapsible segments, enum value CRUD |
| Settings | `/settings` | Account info, API token management |
| Audit | `/audit` | Item completeness scoring |
| Login | `/login` | Username/password form, conditional OIDC button |
### 6.3 Design Patterns
- **In-pane forms**: Create/Edit/Delete forms render in the detail pane area (Infor ERP-style), not as modal overlays
- **Permission checks**: Write actions conditionally rendered based on user role
- **Fuzzy search**: Debounced search with scope toggle (All/PN/Description)
- **Persistence**: `useLocalStorage` hook for user preferences (layout mode, column visibility)
### 6.4 URI Handler
Register `silo://` protocol handler:
@@ -379,12 +399,7 @@ silo://open/PROTO-AS-0001 # Open latest revision
silo://open/PROTO-AS-0001?rev=3 # Open specific revision
```
### 6.3 Technology
- **Backend**: Go with standard library HTTP
- **Frontend**: htmx for interactivity, minimal JavaScript
- **Templates**: Go html/template
- **Search**: PostgreSQL full-text search (pg_trgm for fuzzy matching)
See [frontend-spec.md](../frontend-spec.md) for full component specifications.
---
@@ -583,7 +598,7 @@ See [AUTH.md](AUTH.md) for full architecture details and [AUTH_USER_GUIDE.md](AU
## 11. API Design
### 11.1 REST Endpoints (Implemented)
### 11.1 REST Endpoints (75 Implemented)
```
# Health (no auth)
@@ -597,21 +612,18 @@ POST /logout # Logout
GET /auth/oidc # OIDC login redirect
GET /auth/callback # OIDC callback
# Web UI (auth + CSRF)
GET / # Items page
GET /projects # Projects page
GET /schemas # Schemas page
GET /audit # Audit/completeness page
GET /settings # User settings / token management
POST /settings/tokens # Create API token (web)
POST /settings/tokens/{id}/revoke # Revoke API token (web)
# Public API (no auth required)
GET /api/auth/config # Auth backend configuration (for login UI)
# Auth API
# Auth API (require auth)
GET /api/auth/me # Current authenticated user
GET /api/auth/tokens # List user's API tokens
POST /api/auth/tokens # Create API token
DELETE /api/auth/tokens/{id} # Revoke API token
# Presigned Uploads (editor)
POST /api/uploads/presign # Get presigned MinIO upload URL [editor]
# Schemas (read: viewer, write: editor)
GET /api/schemas # List all schemas
GET /api/schemas/{name} # Get schema details
@@ -659,9 +671,13 @@ PATCH /api/items/{partNumber}/revisions/{revision} # Update status/labe
POST /api/items/{partNumber}/revisions/{revision}/rollback # Rollback to revision [editor]
# Files
GET /api/items/{partNumber}/files # List item file attachments
GET /api/items/{partNumber}/file # Download latest file
GET /api/items/{partNumber}/file/{revision} # Download file at revision
POST /api/items/{partNumber}/file # Upload file [editor]
POST /api/items/{partNumber}/files # Associate uploaded file with item [editor]
DELETE /api/items/{partNumber}/files/{fileId} # Remove file association [editor]
PUT /api/items/{partNumber}/thumbnail # Set item thumbnail [editor]
# BOM
GET /api/items/{partNumber}/bom # List direct children
@@ -718,11 +734,11 @@ POST /api/inventory/{partNumber}/move
### 12.1 Implemented
- [x] PostgreSQL database schema (10 migrations)
- [x] PostgreSQL database schema (11 migrations)
- [x] YAML schema parser for part numbering
- [x] Part number generation engine
- [x] CLI tool (`cmd/silo`)
- [x] API server (`cmd/silod`) with 76 endpoints
- [x] API server (`cmd/silod`) with 75 endpoints
- [x] MinIO integration for file storage with versioning
- [x] BOM relationships (component, alternate, reference)
- [x] Multi-level BOM (recursive expansion with configurable depth)
@@ -736,7 +752,8 @@ POST /api/inventory/{partNumber}/move
- [x] Project management with many-to-many item tagging
- [x] CSV import/export with dry-run validation
- [x] ODS spreadsheet import/export (items, BOMs, project sheets)
- [x] Web UI for items, projects, schemas, audit (htmx)
- [x] Web UI for items, projects, schemas, audit, settings (React SPA)
- [x] File attachments with presigned upload and thumbnail support
- [x] Authentication (local, LDAP, OIDC) with role-based access control
- [x] API token management (SHA-256 hashed)
- [x] Session management (PostgreSQL-backed)
@@ -757,7 +774,7 @@ POST /api/inventory/{partNumber}/move
### 12.3 Not Started
- [ ] Unit tests (Go server — minimal coverage exists)
- [ ] Unit tests (Go server — 9 test files exist, coverage is partial)
- [ ] Schema migration tooling
- [ ] Checkout locking
- [ ] Approval workflows