wifi-densepose/npm/packages/ruvbot/docs/adr/ADR-015-chat-ui.md

ADR-015: Chat UI Architecture

Status

Accepted

Date

2026-01-28

Context

RuvBot provides a powerful REST API for chat interactions, but lacks a user-facing web interface. When users visit the root URL of a deployed RuvBot instance (e.g., on Cloud Run), they receive a 404 error instead of a usable chat interface.

Requirements

1. Provide a modern, responsive chat UI out of the box
2. Support dark mode (default) and light mode themes
3. Work with the existing REST API endpoints
4. No build step required - serve static files directly
5. Support streaming responses for real-time AI interaction
6. Mobile-friendly design
7. Model selection capability
8. Integration with CLI and npm package

Alternatives Considered

Option	Pros	Cons
assistant-ui	Industry leader, 200k+ downloads, Y Combinator backed	Requires React build, adds complexity
Vercel AI Elements	Official Vercel components, AI SDK integration	Requires Next.js
shadcn-chatbot-kit	Beautiful components, shadcn design system	Requires React build
Embedded HTML/CSS/JS	No build step, portable, fast deployment	Less features, custom implementation

Decision

Implement a lightweight embedded chat UI using vanilla HTML, CSS, and JavaScript that:

1. Is served directly from the existing HTTP server
2. Requires no build step or additional dependencies
3. Provides a modern, accessible interface
4. Supports dark mode by default
5. Includes basic markdown rendering
6. Works seamlessly with the existing REST API

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        RuvBot Server                             │
├─────────────────────────────────────────────────────────────────┤
│  GET /              → Chat UI (index.html)                       │
│  GET /health        → Health check                               │
│  GET /api/models    → Available models                           │
│  POST /api/sessions → Create session                             │
│  POST /api/sessions/:id/chat → Chat endpoint                     │
└─────────────────────────────────────────────────────────────────┘

File Structure

src/
├── api/
│   └── public/
│       └── index.html    # Chat UI (single file)
├── server.ts             # Updated to serve static files
└── ...

Features

1. Theme Support: Dark mode default, light mode toggle
2. Model Selection: Dropdown for available models
3. Responsive Design: Mobile-first approach
4. Accessibility: ARIA labels, keyboard navigation
5. Markdown Rendering: Code blocks, lists, links
6. Error Handling: User-friendly error messages
7. Session Management: Automatic session creation
8. Real-time Updates: Typing indicators

CSS Design System

:root {
  --bg-primary: #0a0a0f;      /* Dark background */
  --bg-secondary: #12121a;     /* Card background */
  --text-primary: #f0f0f5;     /* Main text */
  --accent: #6366f1;           /* Indigo accent */
  --radius: 12px;              /* Border radius */
}

API Integration

The UI integrates with existing endpoints:

// Create session
POST /api/sessions { agentId: 'default-agent' }

// Send message
POST /api/sessions/:id/chat { message: '...', model: '...' }

Consequences

Positive

1. Zero Configuration: Works out of the box
2. Fast Deployment: No build step required
3. Portable: Single HTML file, easy to customize
4. Lightweight: ~25KB uncompressed
5. Framework Agnostic: No React/Vue/Svelte dependency
6. Cloud Run Compatible: Works with existing deployment

Negative

1. Limited Features: No streaming UI (yet), basic markdown
2. Manual Updates: No component library updates
3. Custom Code: Maintenance responsibility

Neutral

1. Future option to add assistant-ui or similar for advanced features
2. Can be replaced with any frontend framework later

Implementation

Server Changes (server.ts)

// Serve static files
function getChatUIPath(): string {
  const possiblePaths = [
    join(__dirname, 'api', 'public', 'index.html'),
    // ... fallback paths
  ];
  // Find first existing path
}

// Add root route
{ method: 'GET', pattern: /^\/$/, handler: handleRoot }

CLI Integration

# View chat UI URL after deployment
ruvbot deploy-cloud cloudrun
# Output: URL: https://ruvbot-xxx.run.app

# Open chat UI
ruvbot open  # Opens browser to chat UI

npm Package

The chat UI is bundled with the npm package:

{
  "files": [
    "dist",
    "bin",
    "scripts",
    "src/api/public"
  ]
}

Future Enhancements

1. Streaming Responses: SSE/WebSocket for real-time streaming
2. File Uploads: Image and document support
3. Voice Input: Speech-to-text integration
4. assistant-ui Migration: Full-featured React UI option
5. Themes: Additional theme presets
6. Plugins: Extensible UI components

References

• assistant-ui - Industry-leading chat UI library
• Vercel AI SDK - AI SDK with streaming support
• shadcn/ui - Design system inspiration
• ADR-013: GCP Deployment - Cloud Run deployment

Changelog

Date	Change
2026-01-28	Initial version - embedded chat UI