update

workspace/sprint_1_2/CODEBASE/frontend/spec/frontend_spec.md

@@ -0,0 +1,41 @@
+# Frontend Specification
+
+## Purpose
+Provides interactive clinical workspace, runs edge models (LiteRT, MediaPipe), handles client-side encryption (WebCrypto), offline sync via IndexedDB/Service Worker, and renders UI viewport with graphics adapter fallback.
+
+## Owner
+Web Experience Team
+
+## Boundary
+PWA service worker, graphics adapter layer (IGraphicsViewport), local browser storage (IndexedDB), and UI components (React, Zustand).
+
+## Internal Design
+- Built as a Single Page Application (SPA) using React with TypeScript.
+- State managed via Zustand store.
+- Client-side encryption via WebCrypto API (AES-256-GCM) before local storage.
+- Offline synchronization via Dexie.js (IndexedDB) and Service Worker that queues actions and retries on reconnection.
+- Graphics rendering abstracted via IGraphicsViewport interface with WebGLThreeAdapter (Three.js) and CPUSpriteAdapter fallback.
+- Edge ML executed in Web Workers: DICOM parser (cornerstone-core), LiteRT angle classifier (MobileNetV4), MediaPipe ROI pre-cropper.
+- UI components render multi-layered canvas, workspace controls, diagnostic ribbons, and explanation panels.
+- Communication with backend via HTTPS to NGINX gateway, JWT-based authentication, role-based access control (RBAC).
+
+## Interface Contract
+See `bento/frontend/spec/interface-contract.md`.
+
+## Consumers
+(None)
+
+## Breaking-change Policy
+See `bento/frontend/spec/interface-contract.md`.
+
+## References
+- NFR-1 (Collaborative Rendering Speed ≤3s)
+- NFR-4 (Client Memory Footprint ≤150MB)
+- NFR-14 (Legacy Hardware Compatibility)
+- UC-48376 (Load Patient Scan Session)
+- UC-47988 (Review Suggested Synovitis Grade)
+- UC-25637 (Expose Pixel-Level Activation Logic)
+- UC-60739 (Isolate Visual Noise/Artifacts)
+- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Sections 2.4, 3.1, 3.2, 3.3)
+- SOLUTION_ARCHITECTURE_SPEC.md (Section 2.4)
+- PROJECT_VIS.md (Section 3.1, 3.2)

workspace/sprint_1_2/CODEBASE/frontend/spec/interface_contract.md

@@ -0,0 +1,39 @@
+# Frontend Interface Contract
+
+## Purpose
+Provides interactive clinical workspace, runs edge models (LiteRT, MediaPipe), handles client-side encryption (WebCrypto), offline sync via IndexedDB/Service Worker, and renders UI viewport with graphics adapter fallback.
+
+## Owner
+Web Experience Team
+
+## Provides
+- ui viewport (interactive canvas, overlays, controls)
+- edge ml (angle classification, inflammation detection, ROI pre-cropping)
+- offline sync (local cache, sync queue, background synchronization)
+
+## Consumes
+- backend:api-spec (REST API endpoints for session, analysis, reporting, feedback)
+- knowledge:guideline-spec (GraphRAG pipeline for grounded explanations, evidence arbitration)
+
+## Consumers
+(None)
+
+## Not Directly Consumable
+- backend internals (e.g., FastAPI route implementations, Triton model details)
+- knowledge internals (Qdrant vectors, ladybugDB graph structure)
+- data internals (Postgres schema, S3 object layout)
+
+## Breaking-change Policy
+- API versioning via path (e.g., /api/v1/).
+- Backward compatibility maintained for one minor version.
+- Deprecation notices issued in release notes.
+- Breaking changes require major version bump.
+
+## References
+- NFR-1 (Collaborative Rendering Speed ≤3s)
+- NFR-4 (Client Memory Footprint ≤150MB)
+- NFR-14 (Legacy Hardware Compatibility)
+- UC-48376 (Load Patient Scan Session)
+- UC-47988 (Review Suggested Synovitis Grade)
+- UC-25637 (Expose Pixel-Level Activation Logic)
+- UC-60739 (Isolate Visual Noise/Artifacts)

workspace/sprint_1_2/CODEBASE/frontend/subprojects/offline/spec/interface_contract.md

@@ -0,0 +1,42 @@
+# Offline Interface Contract
+
+## Purpose
+Provides offline caching and synchronization for the PWA frontend, enabling continued operation during network interruptions and seamless sync upon reconnection.
+
+## Owner
+Web Experience Team (same as frontend)
+
+## Parent
+frontend
+
+Boundary
+IndexedDB database via Dexie.js, Service Worker for background sync, and local queue for offline actions.
+
+## Provides
+- offline cache (IndexedDB storage of encrypted patient sessions, DICOM frames, annotation vectors)
+- sync queue (Service Worker-intercepted pending actions)
+- local persistence (survives browser reloads, network drops)
+
+## Consumes
+(None)
+
+## Consumers
+- frontend
+
+## Not Directly Consumable
+- frontend internals (e.g., React components, Zustand store)
+- backend internals
+
+## Breaking-change Policy
+- Changes to IndexedDB schema require version migration scripts.
+- Sync protocol changes are backward-compatible; old clients can still sync via tombstone markers.
+
+## References
+- NFR-8 (Local Network Fault Tolerance)
+- NFR-4 (Client Memory Footprint)
+- UC-48376 (Load Patient Scan Session)
+- UC-47988 (Review Suggested Synovitis Grade)
+- UC-25637 (Expose Pixel-Level Activation Logic)
+- UC-60739 (Isolate Visual Noise/Artifacts)
+- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Section 3.2)
+- SOLUTION_ARCHITECTURE_SPEC.md (Section 3.2)

workspace/sprint_1_2/CODEBASE/frontend/subprojects/offline/spec/offline_spec.md

@@ -0,0 +1,40 @@
+# Offline Specification
+
+## Purpose
+Provides offline caching and synchronization for the PWA frontend, enabling continued operation during network interruptions and seamless sync upon reconnection.
+
+## Owner
+Web Experience Team (same as frontend)
+
+## Parent
+frontend
+
+Boundary
+IndexedDB database via Dexie.js, Service Worker for background sync, and local queue for offline actions.
+
+## Internal Design
+- Dexie.js wrapper around IndexedDB with encrypted stores for patient sessions, frames, and annotation layers.
+- Service Worker intercepts network requests (fetch, XMLHttpRequest) and caches responses; queues POST/PUT/PATCH actions when offline.
+- On reconnection, Service Worker processes queued actions in order, with idempotent retries.
+- Data stored in IndexedDB is encrypted via WebCrypto before writing; decrypted on read.
+- Schema includes tables: sessions, frames, annotations, audit logs, calibration data.
+- Versioning handled via Dexie.js version upgrades with migration scripts.
+
+## Interface Contract
+See `bento/frontend/subprojects/offline/spec/interface-contract.md`.
+
+## Consumers
+- frontend
+
+## Breaking-change Policy
+See `bento/frontend/subprojects/offline/spec/interface-contract.md`.
+
+## References
+- NFR-8 (Local Network Fault Tolerance)
+- NFR-4 (Client Memory Footprint)
+- UC-48376 (Load Patient Scan Session)
+- UC-47988 (Review Suggested Synovitis Grade)
+- UC-25637 (Expose Pixel-Level Activation Logic)
+- UC-60739 (Isolate Visual Noise/Artifacts)
+- SOFTWARE_SYSTEM_DESIGN_FR_25.md (Section 3.2)
+- SOLUTION_ARCHITECTURE_SPEC.md (Section 3.2)