Migration Plan

Phase 1 - Specification And Contracts

• Document current routes and workflows.
• Document API calls and response shapes.
• Identify backend gaps that block a clean Vue client.
• Confirm JavaScript-only implementation.
• Decide exact gnexus-ui-kit installation method.

Deliverable:

• Complete docs in webclient-vue/docs/.

Phase 2 - Project Scaffold

• Create Vue app under webclient-vue/.
• Configure build tooling.
• Add gnexus-ui-kit.
• Add router.
• Add API client wrapper.
• Add app shell, layout, navigation, toast, modal, and error state primitives.

Deliverable:

• New client opens locally and can call GET /api/v1/areas/list.

Phase 2.1 - Minimal Vertical Slice

Build the smallest complete app slice:

• App shell.
• Hash router.
• API client.
• Areas API module.
• Favorites localStorage store with key sh_fav_areas.
• /areas/favorites page.
• Loading, empty, and error state components.

Acceptance criteria:

• Running the dev server opens the Vue client.
• / redirects to /areas/favorites.
• /areas/favorites calls the backend areas list endpoint.
• Existing favorite ids from localStorage are respected.
• Empty favorites state is rendered correctly.
• No old webclient/src/js code is imported.
• UI-kit access is isolated behind local adapter components, even if adapters are initially minimal.

Phase 3 - Read-Only Screens

Implement without mutations first:

• Areas favorites.
• Areas tree.
• Devices list.
• Devices scanning list.
• Scripts actions list.
• Scripts regular list.
• Scripts scopes list.

Deliverable:

• New client can display the same operational data as the current client.

Phase 4 - Mutations And Modals

Implement user actions:

• Run action script.
• Enable/disable regular scripts.
• Enable/disable scopes.
• Device details.
• Device reboot.
• Device setup.
• Area details.
• Area create/edit.
• Area devices modal.
• Area actions modal.

Deliverable:

• New client covers daily operational workflows.

Phase 5 - Hardening

• Add concurrency limits to device live-state loading.
• Add request cancellation on route leave/modal close.
• Add normalized error handling.
• Add stale data and retry states.
• Add smoke checklist.

Deliverable:

• New client is safe to use as primary UI.

Phase 6 - Switch-Over

• Keep old webclient/ available as fallback.
• Serve new client on the chosen route/domain.
• Monitor backend logs and user-reported issues.
• Remove or archive old client only after a stable period.

Open Decisions

• Vue state library: Pinia or lightweight composables only.
• Router mode: hash mode for compatibility or history mode with server config.
• How to consume gnexus-ui-kit as an updatable dependency: package/git dependency preferred, submodule only if necessary.
• Whether to keep proxy.php or use direct backend API from the new dev server.

Current Recommendations

• Use JavaScript.
• Use Pinia.
• Use hash router for the first production-capable version.
• Keep proxy.php compatibility in the API client, but allow direct backend URL through environment variables.
• Integrate gnexus-ui-kit through local adapter components, not direct imports across feature code.