guru-connect/dashboard/README.md

GuruConnect Operator Dashboard (v2)

React + Vite + TypeScript SPA — the operator console for GuruConnect v2. A dark "operations terminal" UI for managing the remote-support fleet.

Pass 1 scope. This pass ships the scaffold, design system, app shell, auth, the typed API client, and the Machines view. Sessions, Codes, and Users are nav stubs only (disabled in the sidebar) and arrive in later passes.

Stack

• React 18 + React Router 6 (client-side routing)
• Vite 5 (dev server + build)
• TypeScript (strict)
• @tanstack/react-query (server-state, polling, cache invalidation)
• @fontsource — Hanken Grotesk (UI) + JetBrains Mono (technical data)

No component/icon libraries — primitives and icons are hand-built to keep the console aesthetic and the bundle lean.

Scripts

npm install
npm run dev        # Vite dev server (proxies /api + /ws to the local GC server)
npm run build      # tsc -b && vite build  ->  dist/
npm run preview     # serve the production build locally
npm run typecheck  # tsc --noEmit
npm run lint       # eslint

Project layout

src/
  api/            Typed API client + response interfaces (source of truth: server/src/api/*.rs)
    client.ts       fetch wrapper: base URL, bearer token, dual error-envelope normalization
    types.ts        TS mirrors of the Rust response structs
    auth.ts         login / me / logout
    machines.ts     list / get / history / delete + admin key endpoints
    stubs.ts        sessions / codes / users — scaffolds for later passes
  auth/           AuthProvider (token in memory + sessionStorage), context, ProtectedRoute
  components/
    ui/             Reusable primitives: Button, Badge/StatusDot, Table, Panel,
                    Modal, ConfirmDialog, Input/Field, Spinner, States, Toast
    layout/         AppShell, Sidebar, Topbar, PageHeader, inline SVG icons
  features/
    auth/           LoginPage
    machines/       MachinesPage + detail / delete / admin-keys modals + hooks
  lib/            time formatting, clipboard, relay-status probe
  styles/         tokens.css (design tokens)

Design system — "operations terminal"

Dark control-room console. Tokens live in src/styles/tokens.css; primitive styles in src/components/ui/*.css.

• Surfaces: --bg #0b0f14, --panel #141b22, --panel-2 #0e1419
• Accent (signal cyan): --accent #22d3bf — primary actions + live state
• Status language (dot + label, used everywhere): ok/online --ok, pending --warn (soft pulse), denied/offline/error --bad, neutral --neutral. Mapping centralised in components/ui/status.ts.
• Type: Hanken Grotesk for UI; JetBrains Mono for all technical data (agent IDs, support codes, IPs, versions, timestamps, key fingerprints).
• Motion (restrained): staggered row fade-in, the consent pulse, the live relay pip, hover transitions. All disabled under prefers-reduced-motion.

Auth

POST /api/auth/login → { token, user }. The token is held in an in-memory ref and mirrored to sessionStorage (never localStorage), so it clears when the tab closes. GET /api/auth/me restores the session on reload; POST /api/auth/logout revokes it server-side. The client attaches Authorization: Bearer <token> to every request and bounces to /login on any 401. Admin-only UI (per-agent key management) is gated on role === "admin".

The API uses two error envelopes — { error } and { detail, error_code, status_code }. api/client.ts extracts a message from whichever is present (and falls back to plain-text bodies that some routes return), so callers see one normalized ApiError.

Dev proxy

vite.config.ts proxies /api and /ws to the local GC server (http://localhost:3002). Run the Rust server locally, then npm run dev — same-origin requests reach the backend with no CORS setup.

To develop the UI against a remote backend instead, set VITE_API_URL (see .env.example).

Production serving — WIRED

The SPA is served by the GC Axum server from the server root. No manual copy step: vite.config.ts sets build.outDir to ../server/static/app/, so the build lands exactly where the server serves it.

Build & deploy flow

# from dashboard/
npm run build      # tsc -b && vite build  ->  ../server/static/app/

That single command refreshes the served SPA. emptyOutDir clears only server/static/app/ (the dedicated SPA subdir), so the v1 portal files in the static root are never touched.

How the server serves it (server/src/main.rs)

• base is / (absolute asset paths). The SPA uses BrowserRouter, so a hard reload of a deep link (/machines) must still load /assets/*; relative (./) paths would resolve against the deep-link path and 404. Absolute is required.
• The Router's fallback_service is ServeDir::new("static/app") with .fallback(ServeFile::new("static/app/index.html")). Real files under /assets/* are served from disk; any other unmatched path returns index.html (HTTP 200) so React Router resolves the route.
• Precedence / safety: the fallback runs only after every explicit /api/*, /ws/*, /health, /metrics route and the /downloads nest. Two catch-all routes — /api/*rest and /ws/*rest — return a JSON 404 for unrouted API/WS paths, so the SPA fallback never answers an API/WS path with HTML (which would break this client's error-envelope parsing).
• Caching: /assets/* (content-hashed) → immutable, one year; index.html and everything else → no-cache, must-revalidate.

Build output in git

server/static/app/ is a build artifact. Whether to commit it or .gitignore it depends on the deploy model (server-side npm run build vs shipping the repo's static dir). Decide at commit time. The old dashboard/dist/ path is no longer used.

Sub-path mounting (not used)

The dashboard is mounted at the server root. If it is ever moved under a sub-path, switch Vite base to that path and pass the same basename to <BrowserRouter>.