From e3da072229b3599034ddb2776b3232fe6bebd3bd Mon Sep 17 00:00:00 2001 From: Forbes Date: Sun, 8 Feb 2026 14:11:12 -0600 Subject: [PATCH] docs: update SPECIFICATION.md for React SPA and current endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/SPECIFICATION.md | 77 ++++++++++++++++++++++++++----------------- 1 file changed, 47 insertions(+), 30 deletions(-) diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md index 60533de..8f89a93 100644 --- a/docs/SPECIFICATION.md +++ b/docs/SPECIFICATION.md @@ -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