claudetools/UPDATES_PAGE_STRUCTURE.md

Updates Page Component Structure

Visual Hierarchy

Updates Page
├── Header Section
│   ├── Title: "Agent Updates"
│   ├── Subtitle: "Manage agent version rollouts..."
│   └── Refresh Button (with spinner)
│
└── Rollouts Card
    ├── Card Header
    │   └── Title: "Rollouts"
    │
    └── Card Content
        ├── Loading State (spinner + "Loading rollouts...")
        ├── Error State (error icon + message + retry button)
        ├── Empty State ("No rollouts yet...")
        │
        └── Rollouts Table
            ├── Table Header
            │   ├── Version
            │   ├── OS / Arch
            │   ├── Channel
            │   ├── Health
            │   ├── Success Rate
            │   ├── Beta Agents
            │   ├── Stable Agents
            │   └── Actions
            │
            └── Table Body (for each rollout)
                ├── Version (monospace)
                ├── OS / Arch (gray text)
                ├── Channel Badge (blue/purple)
                ├── Health Badge (green/yellow/red/gray)
                ├── Success Rate (colored %)
                ├── Beta Count
                ├── Stable Count
                └── Action Buttons
                    ├── Promote Button (arrow up)
                    └── Rollback Button (rotate ccw)

Component Breakdown

Main Component: Updates

• State Management:
  • rollouts - Array of rollout data
  • isLoading - Loading state
  • error - Error message
  • promoteDialog - Promote dialog state
  • rollbackDialog - Rollback dialog state
• Effects:
  • Initial data fetch
  • 30-second auto-refresh
• Mutations:
  • promoteMutation - Handles promotion with force option
  • rollbackMutation - Handles rollback with reason

Sub-Components

HealthStatusBadge

Props: { status: string } Variants:

• healthy → green + CheckCircle
• warning → yellow + AlertTriangle
• critical → red + AlertCircle
• blocked → dark red + X
• unknown → gray (no icon)

ChannelBadge

Props: { channel: string } Variants:

• beta → blue badge
• stable → purple badge

PromoteDialog

Props:

• rollout - Rollout to promote
• onClose - Close handler
• onConfirm - Confirm with force flag
• isLoading - Loading state
• showForceOption - Show force promote option

Features:

• Normal promotion flow
• Force promotion flow (after 403)
• Warning message for force promote

RollbackDialog

Props:

• rollout - Rollout to rollback
• onClose - Close handler
• onConfirm - Confirm with reason
• isLoading - Loading state

Features:

• Required reason text input
• Warning about force-downgrade
• Disabled confirm until reason entered

Data Flow

┌─────────────────┐
│  Initial Load   │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────┐
│  fetchRollouts()            │
│  GET /api/updates/rollouts  │
└────────┬────────────────────┘
         │
         ▼
┌────────────────────┐      ┌──────────────────┐
│  setRollouts()     │◄─────┤  Auto-refresh    │
│  setIsLoading()    │      │  (every 30s)     │
└────────────────────┘      └──────────────────┘

User Action: Promote
┌─────────────────────┐
│  Click Promote Btn  │
└────────┬────────────┘
         │
         ▼
┌───────────────────────┐
│  Open Promote Dialog  │
└────────┬──────────────┘
         │
         ▼
┌──────────────────────────────────────┐
│  User Confirms                       │
│  POST /api/updates/rollouts/promote  │
└────────┬─────────────────────────────┘
         │
         ├──► Success
         │    ├─► Show success toast
         │    ├─► Close dialog
         │    ├─► Refresh rollouts
         │    └─► Invalidate agent cache
         │
         └──► 403 (Health Failed)
              ├─► Show force promote dialog
              └─► User can force promote

User Action: Rollback
┌──────────────────────┐
│  Click Rollback Btn  │
└────────┬─────────────┘
         │
         ▼
┌────────────────────────┐
│  Open Rollback Dialog  │
│  User enters reason    │
└────────┬───────────────┘
         │
         ▼
┌───────────────────────────────────────┐
│  User Confirms                        │
│  POST /api/updates/rollouts/rollback  │
└────────┬──────────────────────────────┘
         │
         ├──► Success
         │    ├─► Show toast with agent count
         │    ├─► Close dialog
         │    ├─► Refresh rollouts
         │    └─► Invalidate agent cache
         │
         └──► Error
              └─► Show error toast

API Contract

GET /api/updates/rollouts

Response: RolloutInfo[]

[
  {
    "version": "0.6.27",
    "os": "windows",
    "arch": "x86_64",
    "channel": "beta",
    "health": {
      "status": "healthy",
      "total_attempts": 50,
      "success_count": 48,
      "failure_count": 2,
      "crash_count": 0
    },
    "beta_agent_count": 15,
    "stable_agent_count": 230,
    "created_at": "2026-05-24T10:30:00Z"
  }
]

POST /api/updates/rollouts/:version/promote

Request:

{
  "os": "windows",
  "arch": "x86_64",
  "force": false
}

Response (200):

{
  "message": "Version 0.6.27 promoted to stable"
}

Response (403 - Health Check Failed):

{
  "error": "Health check failed: crash rate too high"
}

POST /api/updates/rollouts/:version/rollback

Request:

{
  "os": "windows",
  "arch": "x86_64",
  "reason": "Critical bug causing memory leaks"
}

Response:

{
  "message": "Version 0.6.27 rolled back",
  "agents_downgraded": 15
}

Styling Classes

Color Coding

• Success rates:

  • = 95%: text-green-600 dark:text-green-400

  • = 80%: text-yellow-600 dark:text-yellow-400

  • < 80%: text-red-600 dark:text-red-400

Badge Variants

• Green (healthy): bg-green-500/15 text-green-600 dark:text-green-400
• Yellow (warning): bg-yellow-500/15 text-yellow-700 dark:text-yellow-400
• Red (critical/error): bg-red-500/15 text-red-600 dark:text-red-400
• Blue (beta): bg-blue-500/15 text-blue-600 dark:text-blue-400
• Purple (stable): bg-purple-500/15 text-purple-600 dark:text-purple-400

Table Styling

• Header: border-b border-[hsl(var(--border))]
• Row hover: hover:bg-[hsl(var(--muted))]/50
• Monospace font: font-mono text-sm

Accessibility Features

• Semantic HTML (table, th, td)
• Button tooltips for disabled states
• Dialog aria-labels (via Radix UI)
• Loading states announced
• Error states with retry option
• Required field indicators (*) on forms
• Focus management in dialogs
• Keyboard navigation support

Responsive Design

• Table container with horizontal scroll
• Card layout adapts to screen size
• Dialog responsive (max-w-lg)
• Mobile-friendly button spacing
• Text wrapping for long content

Error Handling

• Network errors → error state with retry
• 403 on promote → show force option
• Empty rollouts → empty state message
• Loading timeout → error state
• Mutation errors → toast notification