Skip to content

Conversation

@aaronsb
Copy link
Owner

@aaronsb aaronsb commented Dec 19, 2025

Summary

Completes Phase 8 of ADR-083 (Artifact Persistence Pattern) by integrating the web client with the artifact and query definition APIs.

  • Zustand Stores: Created useArtifactStore and useQueryDefinitionStore for managing artifact metadata and query definitions
  • localStorage Caching: Implemented LRU cache (50MB limit) for artifact payloads with graph epoch freshness tracking
  • API Integration: All persistence now goes through REST API with localStorage as cache/fallback for offline support
  • Store Migrations: Rewrote blockDiagramStore and reportStore to use APIs with migration utilities for existing localStorage data
  • Component Updates: All workspaces updated for async operations (BlockBuilder, BlockEditorWorkspace, ReportWorkspace, ExplorerView, PolarityExplorerWorkspace)

New Files

  • web/src/types/artifacts.ts - TypeScript types for artifact system
  • web/src/store/artifactStore.ts - Artifact state management with LRU caching
  • web/src/store/queryDefinitionStore.ts - Query definition state management
  • web/src/components/shared/ArtifactStatusBadge.tsx - Freshness indicator components

API-First Pattern

Stores now follow an API-first pattern:

  1. Optimistically update local state for immediate UI feedback
  2. Persist to API in background
  3. On failure, fall back to localStorage
  4. On load, merge API data with any unsynced local data

Test plan

  • Verify web app builds without TypeScript errors
  • Test creating a report from 2D/3D explorer - should save to API
  • Test "Save as Artifact" button in Polarity Explorer
  • Test block diagram save/load - should persist to query_definitions API
  • Verify localStorage serves as fallback when API unavailable
  • Test migrateFromLocalStorage() utility for existing data

Related

  • ADR-083: Artifact Persistence Pattern
  • ADR-082: User Scoping & Artifact Ownership

…e 8)

- Create useArtifactStore with localStorage LRU caching (50MB limit)
- Create useQueryDefinitionStore for saved queries
- Add artifact API methods to web client (list, get, create, delete, regenerate)
- Add "Save as Artifact" button to PolarityExplorerWorkspace
- Create ArtifactStatusBadge and StaleIndicator components
…R-083 Phase 8)

Rewrites blockDiagramStore and reportStore to use artifacts and query_definitions
APIs as primary persistence, with localStorage serving as cache/fallback.

Changes:
- blockDiagramStore: API-first persistence with query_definitions endpoint
  - All methods now async (saveDiagram, loadDiagram, deleteDiagram)
  - Added migrateFromLocalStorage() for one-time migration
  - localStorage serves as offline fallback
- reportStore: API-first persistence with artifacts endpoint
  - Reports stored as artifacts with type 'report'
  - Added loadReports() and migrateFromLocalStorage()
  - Maintains local state for immediate UI updates
- Updated all consuming components for async operations:
  - BlockBuilder: async save/load/delete handlers
  - BlockEditorWorkspace: async diagram selection and deletion
  - ReportWorkspace: async delete and rename
  - ExplorerView: async handleSendToReports
  - PolarityExplorerWorkspace: async handleSendToReports
- Removed completed ADR-081 tracking file
@aaronsb aaronsb merged commit 00dab14 into main Dec 20, 2025
6 checks passed
@aaronsb aaronsb deleted the feature/adr-083-phase8-web-client branch December 20, 2025 03:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants