# Sync and UI Upgrade Plan

## Goals
- Deliver hybrid online/offline functionality with resilient background sync and intelligent caching.
- Modernize the module platform so configuration-driven screens rival bespoke views like UserProfile and POS.
- Streamline UI rendering through shared form/element libraries, scoped events, and progressive loading.
- Enhance user trust with clear messaging, better security, and accessible, consistent components.

## Scope Overview
- Applies to `FrontEnd/js/core`, `FrontEnd/js/services`, `FrontEnd/js/modules`, `FrontEnd/Dashboard.php`, designer utilities under `FrontEnd/js/modules/ModuleBuilder`, and supporting PHP endpoints in `api/`.
- Covers IndexedDB + sync flows, websocket and JWT auth, DaisyUI/Tailwind components, and the module registry.
- Includes data/schema clean-up: consolidating on the `modules` table and renaming tenant entities to org entities across JS/PHP.

## Workstreams

### 1. Hybrid Sync Manager
- ✅ Policy-driven LocalSyncManager with per-table cadence, retention, and transport-aware scheduling.
- ✅ Queue + retry layer (`sync_queue`) with metrics and dead-letter events.
- ✅ Shared sync event bus powering Toast/DataLoader/ModuleLoader updates.
- ✅ Initial search helper (local + remote) ready; integrate across modules next.

### 2. Offline Messaging & Diagnostics
- ✅ Dashboard now displays a diagnostics banner backed by the sync event bus (navigator/ws detection, retry control, details panel).
- ✅ LocalSyncManager emits contextual offline/degraded messaging instead of the generic "background sync failed" toast, including navigator/websocket checks.
- ✅ ModuleLoader auto-injects diagnostics banners with retry controls into module shells (drawer, modals, cards).
- ✅ Connection transitions are logged via telemetry queue (sendBeacon with offline queue + auto-flush on reconnect).

### 3. Robust Error Handling
- ✅ Introduced a shared API client wrapper that normalizes error payloads and surfaces friendly toast messages.
- ✅ Dashboard cards now fall back to cached module listings when API calls fail, keeping the UI responsive offline.
- ✅ Server exceptions now flow through `ErrorReporter`, logging structured diagnostics while returning generic responses.

### 4. Action Guardrails
- ✅ Shared `actionGuard` helper prevents double submits and manages busy state on guarded elements.
- ✅ Busy/disabled toggling and cancel hooks now supported via guard options (busyTarget/cancelTarget).
- ✅ Guardrails applied to ModuleBuilder save, FormSubmission submits, and POS pay/hold flows; extend to remaining auth flows next.

### 5. SyncService Singleton Enforcement
- ✅ Singleton now exports event-aware manager; most modules migrated off ad-hoc instances.
- 🔄 Add lint/tests + documentation once remaining modules switch over.

### 6. Module Platform Modernization (Loader, Builder, Designer)
- ✅ Runtime now relies solely on `modules` (no `ui_modals` fallback).
- ✅ Progressive data source definitions now hydrate through ModuleLoader; scoped controller actions supported.
- 🔄 ModalBuilder/Designer updates still needed to expose data source tooling (schema authoring, UI).
- ✅ ModalBuilder now supports data source bindings, computed expressions, grid layouts, custom component registry, and element lifecycle hooks.
- Update ModuleBuilder designer to expose the new schema features (data sources, state/actions, layout presets, scoped events) so teams can visually craft complex modules.

### 7. DataLoader Evolution
- ✅ DataLoader auto-refreshes via sync event bus.
- 🔄 Add pluggable renderers, progressive callbacks, and ModalBuilder integration.

- ✅ Form element type metadata centralized in `core/elementTypes.js`; FormUtils/FormSubmission/ModalBuilder consume the shared constants.
- ✅ FormBuilder/FormUtils now render DaisyUI/Tailwind components with inline validation states, autosave hints, and accessibility defaults.
- ✅ Lightweight file upload widget ships alongside the DMS flow, routing uploads through the DocumentsController simple upload endpoint.
- ✅ Provide simple file preview/list components so modules can display uploads without bespoke code.

### 9. File & Document Experience
- ✅ Sync manager support for queued uploads/downloads with retry and offline awareness.
- ✅ Gallery/table renderers for documents and media with role-based controls.
- ✅ Ensure DMS endpoints enforce JWT auth and return standardized errors for the UI.

### 10. Security & Auth (JWT/Websocket)
- Issue and refresh JWTs on login; validate tokens in PHP middleware for API & sync routes.
- Use secure storage (IndexedDB/session) to avoid stale tokens; handle token expiry gracefully in sync/search helpers.
- Update websocket handshakes to include JWT validation, reconnection jitter, back-off, and fallback polling.

### 11. Event & Workflow Bus
- ✅ Scoped event bus now available via ModuleLoader with controller lifecycle cleanup.
- ✅ ModuleLoader/ModalBuilder integrate declarative events and auto-unsubscribe on teardown.

- ✅ Stand up a shared layout preset registry (`FrontEnd/js/core/layoutPresets.js`) exposing `registerPreset`/`getPreset` APIs with seeded DaisyUI/Tailwind definitions for cards, accordions, tabs, and responsive grids; surface the same presets to `FrontEnd/Dashboard.php` via a lightweight PHP helper so dashboard widgets and ModuleLoader shells resolve layout + breakpoint metadata from one contract.
- ✅ Extend ModuleBuilder/PageConfigBuilder to author the layout metadata (per tenant/department overrides, responsive breakpoints, DaisyUI variant selection) and persist it via the modules table and page configs (UI authors can now choose presets, variants, and scoped overrides directly from the builders).
- ✅ Migrate the highest-traffic dashboard widgets and core modules (Inventory, Workflow queue, POS) to the registry, providing fallbacks for legacy markup and documenting adoption steps. **Completed Oct 4, 2025** - See `docs/frontend/LayoutPresetMigrationCompletion.md` for full results.
- ✅ Harden ModalBuilder/DataLoader defaults for WCAG 2.1 AA compliance—focus trapping, keyboard loops, aria-* wiring, Tailwind focus ring tokens, live regions for status announcements, and comprehensive screen reader support. **Completed Oct 4, 2025** - Full compliance checklist in `docs/frontend/ModalBuilder.md`. Achievements: focus trap with Tab/Shift+Tab cycling, Escape key handling, focus restoration on close, table captions, pagination ARIA labels, live region announcements, proper semantic HTML with role/scope attributes.
- 🔄 Package profile/POS-inspired layout presets (card decks, drawer detail views, tabbed inspectors) with Jest/visual regression coverage so teams can reuse them without bespoke markup.

### 13. Terminology & Schema Cleanup
- Migrate codebase from `tenant`/`tenant_id` to `org`/`org_id` across JS, PHP, IndexedDB stores, schemas, and UI copy.
- Provide database migrations, sync migration scripts, and backwards-compatible data transforms for existing offline caches.
- Update documentation, tests, and analytics dashboards to reflect the new naming.

### 14. Observability & Tooling
- Instrument client logging hooks for sync queues, error rates, websocket uptime, and module load timings.
- Extend Jest tooling to mock IndexedDB/fetch/websocket/service worker scenarios; ensure PHPUnit covers JWT middleware and modules API endpoints.
- Enforce bundle-splitting and lazy-loading budgets; add CI checks for oversized modules.

### 15. API Endpoint Configuration
- Centralize API URL generation in a shared config helper that reads an explicit base URL (env/config) with fallback to the current domain.
- Refactor SyncService, ModuleLoader, DataLoader, ModuleBuilder, FormBuilder, and ad-hoc fetch calls to use the helper.
- Ensure tests cover base-URL overrides, multi-org routing, and secure handling of credentials.

- Instrument client logging hooks for sync queues, error rates, websocket uptime, and module load timings.
- Extend Jest tooling to mock IndexedDB/fetch/websocket/service worker scenarios; ensure PHPUnit covers JWT middleware and modules API endpoints.
- Enforce bundle-splitting and lazy-loading budgets; add CI checks for oversized modules.

## Additional Enhancements
- **Offline Testing Harness**: reusable mocks/utilities for offline-first behaviour in Jest.
- **Documentation Refresh**: update `docs/frontend` to describe the modern module schema, event bus, form element constants, and migration steps (`modules` table, org rename).
- **Developer Playbooks**: provide example configs for complex modules (UserProfile, POS) showcasing progressive loading and scoped events.

### Deferred Legacy Modules
- Calendar, POS, ModuleBuilder designer internals, and other bespoke modules retain their current sync wiring for now; migrate them after the policy-driven LocalSyncManager + search helper is stable.
- Track these deferred modules in the upgrade backlog so future sweeps apply the singleton, `apiUrl`, and progressive loading patterns consistently.
- With `ui_modals` removed from runtime code, schedule clean-up in tests/migrations to rely on the canonical `modules` table and delete any remaining legacy seed data once backfill scripts are in place.

## Dependencies & Sequencing
1. Enforce SyncService singleton usage and introduce module registry foundation (ModuleLoader/ModalBuilder refactor).
2. Deliver LocalSyncManager overhaul with policy metadata, search delegation, and event bus plumbing.
3. Migrate schema terminology (`modules` table adoption, org rename) to avoid conflicting APIs during refactors.
4. Implement ModuleBuilder/ModalBuilder enhancements, progressive loading, and scoped events; update designer tooling.
5. Roll out DataLoader renderers, form element constants, file widgets, and action guardrails.
6. Finalize JWT/websocket upgrades, observability, and documentation/testing harness updates.

## Testing & QA
- Extend Jest suites for sync, search, form components, ModuleLoader progressive hydration, and scoped event bindings.
- Add PHPUnit coverage for JWT middleware, modules API, document upload endpoints, and terminology migration scripts.
- Run `./test_setup.sh`, `phpunit`, and `npm test` in CI; add smoke tests for offline/online transitions, module progressive loading, and org renaming.

## Risks & Mitigations
- **Schema Drift**: tie sync policies to `api/schema.php`; add CI guard for schema changes affecting IndexedDB stores.
- **Offline Storage Limits**: monitor IndexedDB usage, enforce retention metadata, and provide eviction policies.
- **Performance Regressions**: profile new renderers/progressive flows; fall back to virtualized lists where needed.
- **Migration Complexity**: stage `ui_modals` → `modules` and `tenant` → `org` changes with backwards-compatible adapters and robust data migration scripts.
- **Security**: review JWT storage, websocket auth, upload endpoints, and background sync access patterns.

## Deliverables
- Updated `LocalSyncManager`, `ModuleLoader`, `ModalBuilder`, `ModuleBuilder`, `FormBuilder`, `FormUtils`, `DataLoader`, and supporting helpers.
- New shared libraries: action guard, search manager, event bus, form element constants, file upload/display widgets.
- Documentation covering new module schema, progressive loading patterns, scoped events, and migration steps.
- Deployment guidance for JWT/websocket rollout, sync migration, and terminology refactor.