flynn/docs/plans/2026-02-07-web-ui-dashboard.md

Flynn Web UI / Control Dashboard

Date: 2026-02-07 Priority: P7 Status: In Progress

Overview

Upgrade the existing minimal web UI (src/gateway/ui/) into a proper control dashboard with:

1. Dashboard — system health, sessions, tools, channels, usage stats
2. Chat — real-time streaming chat with token-by-token content, session management
3. Sessions — browse/switch/delete sessions, view history
4. Settings — view/edit configuration, manage channels, view/edit hooks

Architecture

Tech Stack

• No build step — vanilla HTML/CSS/JS (consistent with existing UI)
• SPA routing — hash-based (#/, #/chat, #/sessions, #/settings)
• WebSocket — reuse existing JSON-RPC protocol for all data
• CSS — extend existing style.css design system (dark theme, design tokens)
• Marked.js — CDN for markdown rendering (already used)
• Highlight.js — CDN for syntax highlighting in code blocks

File Structure

src/gateway/ui/
├── index.html          # SPA shell (nav + router)
├── style.css           # Extended design system
├── app.js              # SPA router + WebSocket client
├── pages/
│   ├── dashboard.js    # Dashboard page
│   ├── chat.js         # Chat page
│   ├── sessions.js     # Sessions browser
│   └── settings.js     # Settings page
└── lib/
    └── ws-client.js    # WebSocket RPC client (shared)

Backend Changes

1. content streaming events — agent.send should emit content events with text chunks as the model generates them. Currently only emits tool_start, tool_end, done. Requires wiring the model client's streaming iterator through the agent.

2. New gateway methods:

   • sessions.delete — clear a session's history
   • sessions.switch — switch the connection's active session
   • system.channels — list active channel adapters and their status
   • system.usage — aggregated usage stats (tokens, cost)
   • config.channels — channel-specific configuration view

3. Static file serving — extend static.ts to serve .js files from subdirectories (already supports .js, but need to handle nested paths under pages/ and lib/)

4. Content-type additions — add .png, .ico, .woff2 to CONTENT_TYPES in static.ts (for future assets).

Implementation Phases

Phase 1: Backend enhancements

• Add sessions.delete handler
• Add sessions.switch handler
• Add system.channels handler
• Add system.usage handler
• Add streaming content events to agent.send
• Extend static.ts for nested paths
• Tests for all new handlers

Phase 2: SPA shell + WebSocket client

• Rewrite index.html as SPA shell with hash router and nav
• Create lib/ws-client.js — promise-based RPC client with reconnect
• Create app.js — page router, WebSocket lifecycle

Phase 3: Dashboard page

• Health cards (status, version, uptime, connections, sessions, tools)
• Channel status cards
• Usage summary (tokens, cost, calls)
• Auto-refresh on interval

Phase 4: Chat page

• Session selector dropdown
• New session button
• Real-time streaming text (token by token via content events)
• Tool events display (collapsible)
• Markdown rendering with syntax highlighting
• Session history loading on page entry
• Input area with send/cancel

Phase 5: Sessions page

• Session list with message count, last activity
• Click to view session history
• Delete session button
• Session detail view with full message history

Phase 6: Settings page

• Read-only config view (with redacted secrets)
• Editable hook patterns (confirm/log/silent)
• Channel status overview
• Tool list with descriptions

Estimated Effort

• Phase 1: Backend — 1 hour
• Phase 2: SPA shell — 30 min
• Phase 3: Dashboard — 30 min
• Phase 4: Chat — 1 hour
• Phase 5: Sessions — 30 min
• Phase 6: Settings — 30 min
• Total: ~4 hours