# 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:

```text
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.