Overview

Goal

Build a new SHServ web client in parallel with the existing vanilla JS client. The new client should use Vue and gnexus-ui-kit, while preserving the current smart-home workflows:

• Monitor devices and their live states.
• Scan and set up new devices.
• Run action scripts.
• Enable/disable regular scripts and scopes.
• Browse areas as a tree.
• Manage favorite areas.
• Open area-specific devices and actions.

Non-Goals For The First Phase

• Rewriting the PHP backend.
• Changing device firmware contracts.
• Removing the current webclient/.
• Implementing server-side auth unless backend work is explicitly scheduled.
• Replacing automation logic in ControlScripts.

Target Architecture

The new client should be a separate frontend application under webclient-vue/. It should communicate with the existing backend through the same HTTP API used by the current client.

Recommended high-level structure:

webclient-vue/
  docs/
  src/
    app/
    api/
    components/
    features/
      areas/
      devices/
      scripts/
    router/
    stores/
    styles/

Design Direction

Use gnexus-ui-kit as the primary UI foundation and keep it as a live, updatable design dependency. The first implementation pass should prioritize compatibility with UI-kit updates, consistency, state clarity, and operational reliability over visual experimentation.

Important UI states:

• Loading
• Empty
• Error
• Offline device
• Action in progress
• Action success
• Action failure

Compatibility Boundary

The current client uses proxy.php with a path=/api/v1/... query parameter. The new client may use the same proxy in local development, but API access should be wrapped behind a dedicated API client so the transport can be changed later.