# Community ADE Approval System - Dashboard UI Specifications

## Overview

This document defines the UI components and specifications for the Delta-V2 Dashboard's Approval System integration. The dashboard provides human operators with visibility and control over the approval workflow.

---

## Design System

### Color Palette

| Token | Hex | Usage |
|-------|-----|-------|
| `--color-primary` | `#3B82F6` | Primary actions, links |
| `--color-primary-dark` | `#2563EB` | Hover states |
| `--color-success` | `#10B981` | Approved, completed, success states |
| `--color-warning` | `#F59E0B` | Pending, medium risk, warnings |
| `--color-danger` | `#EF4444` | Rejected, high risk, errors |
| `--color-info` | `#6366F1` | Info states, low risk |
| `--color-neutral-100` | `#F3F4F6` | Backgrounds |
| `--color-neutral-200` | `#E5E7EB` | Borders |
| `--color-neutral-700` | `#374151` | Body text |
| `--color-neutral-900` | `#111827` | Headings |

### State Colors

| State | Background | Border | Text | Icon |
|-------|------------|--------|------|------|
| `DRAFT` | `#F3F4F6` | `#D1D5DB` | `#6B7280` | Edit icon |
| `SUBMITTED` | `#DBEAFE` | `#93C5FD` | `#1E40AF` | Upload icon |
| `REVIEWING` | `#FEF3C7` | `#FCD34D` | `#92400E` | Eye icon |
| `APPROVED` | `#D1FAE5` | `#6EE7B7` | `#065F46` | Check icon |
| `APPLYING` | `#E0E7FF` | `#A5B4FC` | `#3730A3` | Play icon (animated) |
| `COMPLETED` | `#D1FAE5` | `#10B981` | `#065F46` | CheckCircle icon |
| `REJECTED` | `#FEE2E2` | `#FCA5A5` | `#991B1B` | X icon |
| `CANCELLED` | `#F3F4F6` | `#9CA3AF` | `#4B5563` | Slash icon |

### Typography

| Level | Font | Size | Weight | Line Height |
|-------|------|------|--------|-------------|
| H1 | Inter | 24px | 600 | 1.3 |
| H2 | Inter | 20px | 600 | 1.3 |
| H3 | Inter | 16px | 600 | 1.4 |
| Body | Inter | 14px | 400 | 1.5 |
| Small | Inter | 12px | 400 | 1.5 |
| Mono | JetBrains Mono | 13px | 400 | 1.5 |

---

## Layout Structure

```
┌─────────────────────────────────────────────────────────────────────────────┐
│  HEADER                                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  Logo    Search    [🔔 Notifications]    [👤 User Menu]            │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────────────────┤
│  SIDEBAR    │  MAIN CONTENT                                                  │
│             │                                                                │
│  Dashboard  │  ┌────────────────────────────────────────────────────────┐  │
│  Tasks      │  │  PAGE HEADER                                           │  │
│  Approvals  │  │  [Title]              [Primary Action] [Secondary]    │  │
│  ─────────  │  └────────────────────────────────────────────────────────┘  │
│  Locks      │                                                                │
│  Audit Log  │  ┌────────────────────────────────────────────────────────┐  │
│  ─────────  │  │  CONTENT AREA                                          │  │
│  Settings   │  │                                                        │  │
│             │  │  [Cards / Tables / Forms / Modals as needed]          │  │
│             │  │                                                        │  │
│             │  └────────────────────────────────────────────────────────┘  │
│             │                                                                │
└─────────────┴────────────────────────────────────────────────────────────────┘
```

---

## Component Specifications

### 1. Navigation Components

#### Sidebar Navigation
```typescript
interface SidebarProps {
  activeSection: 'dashboard' | 'tasks' | 'approvals' | 'locks' | 'audit' | 'settings';
  badgeCounts: {
    approvals: number;  // Pending approvals for current user
    locks: number;      // Active locks requiring attention
  };
  user: {
    name: string;
    role: string;
    avatarUrl?: string;
  };
}
```

**Features:**
- Collapsible on mobile (drawer)
- Badge indicators for pending items
- Keyboard navigation support (Arrow keys, Enter)
- Active state highlighting

**Menu Items:**
- Dashboard (overview stats)
- Tasks (all tasks)
- Approvals (queue) - with badge count
- Locks (lock manager)
- Audit Log
- Settings

---

### 2. Dashboard Components

#### Stats Overview Card
```typescript
interface StatsCardProps {
  title: string;
  value: number | string;
  trend?: {
    direction: 'up' | 'down' | 'neutral';
    value: string;
    label: string;
  };
  icon: IconComponent;
  color: 'primary' | 'success' | 'warning' | 'danger' | 'info';
  linkTo?: string;
}
```

**Layout:**
```
┌────────────────────────────┐
│  [Icon]                    │
│                            │
│  Title                     │
│  ┌────────────────────┐    │
│  │ VALUE              │    │
│  └────────────────────┘    │
│  ▲ 12% vs last week        │
└────────────────────────────┘
```

**Dashboard Stats:**
1. Pending My Approval (count + link)
2. Tasks in Review (count)
3. Active Locks (count)
4. Completed Today (count + success rate)

---

#### Approval Queue Widget
```typescript
interface ApprovalQueueWidgetProps {
  approvals: Array<{
    id: string;
    taskId: string;
    taskType: string;
    taskDescription: string;
    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
    requestedBy: string;
    requestedAt: string;
    dueAt?: string;
    priority: 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
  }>;
  onApprove: (id: string) => void;
  onReject: (id: string) => void;
  onView: (id: string) => void;
  maxItems?: number;
}
```

**Features:**
- Expandable list (default show 5, "View All" link)
- Inline quick actions (Approve/Reject with confirmation)
- Color-coded risk badges
- Relative timestamps ("2 hours ago")
- Urgent items highlighted with red border

---

#### Activity Feed
```typescript
interface ActivityFeedProps {
  events: Array<{
    id: string;
    type: 'task_created' | 'task_submitted' | 'approval_requested' | 
          'approval_responded' | 'task_executing' | 'task_completed' | 
          'lock_acquired' | 'lock_released';
    actor: {
      id: string;
      name: string;
      avatarUrl?: string;
    };
    target: {
      type: 'task' | 'approval' | 'lock';
      id: string;
      name: string;
    };
    metadata?: Record<string, unknown>;
    timestamp: string;
  }>;
  maxItems?: number;
  pollInterval?: number;
}
```

**Features:**
- Real-time updates via WebSocket
- Collapsible event details
- Click to navigate to related resource
- Infinite scroll or pagination

---

### 3. Task Components

#### Task List Table
```typescript
interface TaskListTableProps {
  tasks: TaskResponse[];
  columns: Array<{
    key: string;
    title: string;
    sortable?: boolean;
    width?: string;
  }>;
  selectedIds: string[];
  onSelect: (ids: string[]) => void;
  onRowClick: (task: TaskResponse) => void;
  onSort: (key: string, order: 'asc' | 'desc') => void;
  pagination: {
    page: number;
    limit: number;
    total: number;
    onChange: (page: number) => void;
  };
  filters: TaskFilters;
  onFilterChange: (filters: TaskFilters) => void;
}

interface TaskFilters {
  state?: TaskState[];
  author?: string;
  resourceType?: ResourceType;
  riskLevel?: RiskLevel;
  dateRange?: { from: Date; to: Date };
  tags?: string[];
}
```

**Columns:**
| Column | Width | Sortable | Content |
|--------|-------|----------|---------|
| Checkbox | 40px | No | Multi-select |
| State | 120px | Yes | Badge with icon |
| Task | 300px | Yes | Description + type tag |
| Author | 150px | Yes | Avatar + name |
| Risk | 100px | Yes | Score + level badge |
| Resources | 200px | Yes | Icon list (hover for details) |
| Created | 150px | Yes | Relative time |
| Actions | 100px | No | Menu button |

**Features:**
- Batch actions toolbar (appears on selection)
- Column resizing
- Export to CSV/JSON
- Saved filter presets

---

#### Task State Badge
```typescript
interface TaskStateBadgeProps {
  state: TaskState;
  size?: 'sm' | 'md' | 'lg';
  showIcon?: boolean;
  pulse?: boolean;  // Animate for APPLYING state
}
```

**Visual States:**
- `DRAFT`: Gray, edit icon
- `SUBMITTED`: Blue, upload icon
- `REVIEWING`: Yellow, eye icon
- `APPROVED`: Green with border, check icon
- `APPLYING`: Indigo, animated spinner + play icon
- `COMPLETED`: Solid green, check-circle icon
- `REJECTED`: Red, X icon
- `CANCELLED`: Gray strikethrough, slash icon

---

#### Risk Score Indicator
```typescript
interface RiskScoreProps {
  score: number;  // 0-100
  size?: 'sm' | 'md' | 'lg';
  showLabel?: boolean;
  showFactors?: boolean;
}
```

**Visual Design:**
```
┌────────────────────────────────┐
│ ┌──────────┐                   │
│ │    75    │  HIGH RISK        │
│ │  ┌──┐    │                   │
│ │  │██│    │  • Critical resource │
│ │  │██│    │  • Wide blast radius │
│ │  │░░│    │  • No rollback    │
│ └──┴──┴────┘                   │
└────────────────────────────────┘
```

- Circular progress indicator
- Color gradient: Green (0) → Yellow (50) → Red (100)
- Tooltip showing risk factors on hover

---

#### Task Detail View
```typescript
interface TaskDetailViewProps {
  task: TaskResponse;
  activeTab: 'overview' | 'preview' | 'approvals' | 'execution' | 'audit';
  onTabChange: (tab: string) => void;
  onAction: (action: 'submit' | 'cancel' | 'retry') => void;
}
```

**Layout:**
```
┌─────────────────────────────────────────────────────────────────┐
│  Breadcrumbs > Task: Database Migration                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  [State Badge]  Task Title                              │   │
│  │  Created by John Doe • 2 hours ago • Ticket: PROJ-123   │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Overview] [Preview] [Approvals] [Execution] [Audit]          │
│  ─────────────────────────────────────────────────────────      │
│                                                                 │
│  TAB CONTENT                                                    │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  ACTION BAR (contextual based on state)                        │
│  [Submit for Approval] [Save Draft] [Cancel]                   │
└─────────────────────────────────────────────────────────────────┘
```

---

#### Preview Panel
```typescript
interface PreviewPanelProps {
  preview: PreviewResult;
  onRefresh: () => void;
  lastUpdated: string;
}
```

**Content:**
- Validation status (valid/invalid with error list)
- Change list with diff view
- Affected services diagram
- Estimated execution time
- Rollback capability indicator

**Diff View Component:**
```
┌─────────────────────────────────────────────────────────────┐
│  Resource: database/prod-db-01                              │
│  Action: MODIFY                                             │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌────────────────┐                    │
│  │ BEFORE         │  │ AFTER          │                    │
│  │                │  │                │                    │
│  │ instance:      │  │ instance:      │                    │
│  │   type: db.m5  │  │   type: db.r6  │ ◄── Changed        │
│  │   size: large  │  │   size: xlarge │ ◄── Changed        │
│  │   storage: 100 │  │   storage: 100 │                    │
│  │                │  │                │                    │
│  └────────────────┘  └────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
```

---

### 4. Approval Components

#### Approval Card
```typescript
interface ApprovalCardProps {
  approval: {
    id: string;
    task: {
      id: string;
      title: string;
      type: string;
      description: string;
      risk: RiskAssessment;
      resources: ResourceRef[];
      preview: PreviewResult;
    };
    requestedBy: {
      id: string;
      name: string;
      avatarUrl?: string;
      team?: string;
    };
    requestedAt: string;
    dueAt?: string;
    priority: 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
    delegationChain?: string[];
  };
  onApprove: (id: string, reason?: string) => void;
  onReject: (id: string, reason: string) => void;
  onRequestChanges: (id: string, feedback: string) => void;
  onDelegate: (id: string, delegateTo: string) => void;
}
```

**Layout:**
```
┌─────────────────────────────────────────────────────────────────┐
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ [Avatar] Requested by Sarah Chen • Platform Team       │   │
│  │ 2 hours ago • Due in 2 days                            │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Database Migration - Shard Addition                           │
│  [INFRASTRUCTURE] [HIGH PRIORITY]                              │
│                                                                 │
│  Add new read replica to handle increased traffic...           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ RISK SCORE: 65/100 [MEDIUM]                             │   │
│  │ • Production database affected                          │   │
│  │ • 15-minute estimated downtime                          │   │
│  │ • Automatic rollback available                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  AFFECTED RESOURCES:                                           │
│  [DB] prod-db-01  [SVC] api-service  [SVC] worker-queue        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ CHANGES PREVIEW (3 changes)                    [View ▼] │   │
│  │ • Modify database instance size                        │   │
│  │ • Update service configuration                         │   │
│  │ • Scale worker replicas                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [✓ Approve]  [✗ Reject]  [💬 Request Changes]  [➡ Delegate] │
│                                                                 │
│  Reason (required for rejection):                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

---

#### Batch Approval Panel
```typescript
interface BatchApprovalPanelProps {
  selectedApprovals: string[];
  approvals: Array<{
    id: string;
    taskTitle: string;
    riskLevel: string;
  }>;
  onBatchAction: (action: 'approve' | 'reject', options: BatchOptions) => void;
  onClearSelection: () => void;
}

interface BatchOptions {
  applyImmediately: boolean;
  skipValidation: boolean;
  continueOnError: boolean;
}
```

**Features:**
- Slide-out panel from right
- Summary of selected items
- Risk level aggregation ("3 Low, 2 High risk")
- Bulk action with confirmation
- Apply immediately toggle

---

#### Delegation Settings Panel
```typescript
interface DelegationSettingsProps {
  policies: DelegationPolicy[];
  availableDelegates: Array<{
    id: string;
    name: string;
    role: string;
    avatarUrl?: string;
  }>;
  onCreatePolicy: (policy: Omit<DelegationPolicy, 'id'>) => void;
  onUpdatePolicy: (id: string, updates: Partial<DelegationPolicy>) => void;
  onDeletePolicy: (id: string) => void;
}
```

**Features:**
- Visual policy builder
- Condition preview ("When task is INFRASTRUCTURE and risk > 50")
- Chain visualization
- Active/Inactive toggle

---

### 5. Lock Components

#### Lock Monitor Dashboard
```typescript
interface LockMonitorProps {
  locks: Array<{
    id: string;
    resourceType: 'task' | 'resource' | 'agent';
    resourceId: string;
    mode: 'exclusive' | 'shared';
    holder: {
      agentId: string;
      agentName: string;
      acquiredAt: string;
      expiresAt: string;
      purpose?: string;
    };
    queue: Array<{
      agentId: string;
      position: number;
      waitTime: number;
    }>;
    ttl: number;
  }>;
  deadlocks: DeadlockInfo[];
  onForceRelease: (lockId: string, reason: string) => void;
  onRefresh: () => void;
}
```

**Layout:**
```
┌─────────────────────────────────────────────────────────────────┐
│  LOCK MONITOR                                      [↻ Refresh] │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Active Locks    │ │ Waiting Agents  │ │ Detected Dead-  │   │
│  │ 24              │ │ 7               │ │ locks 0         │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ACTIVE LOCKS                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Type     Resource        Holder      TTL    Queue  Act  │   │
│  │ ──────────────────────────────────────────────────────── │   │
│  │ task     task-123        agent-01    23s    2      [⋯]  │   │
│  │ resource db/prod-01      agent-03    45s    0      [⋯]  │   │
│  │ task     task-456        agent-02    12s    1      [⋯]  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  LOCK QUEUE                                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Position  Agent       Waiting For    Est. Time         │   │
│  │ ──────────────────────────────────────────────────────── │   │
│  │ 1         agent-04    task-123         ~15s             │   │
│  │ 2         agent-05    task-123         ~30s             │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

---

#### Lock Detail Modal
```typescript
interface LockDetailModalProps {
  lock: LockInfo;
  isOpen: boolean;
  onClose: () => void;
  onForceRelease: (reason: string) => void;
  onExtendTTL: (seconds: number) => void;
}
```

**Content:**
- Lock metadata
- Holder information with heartbeat status
- Queue visualization (if waiters exist)
- Action buttons (Extend, Force Release - admin only)
- Lock history/timeline

---

#### Deadlock Alert
```typescript
interface DeadlockAlertProps {
  deadlocks: DeadlockInfo[];
  onResolve: (deadlockId: string, strategy: 'abort_youngest' | 'abort_shortest') => void;
  onDismiss: (deadlockId: string) => void;
}
```

**Visual Design:**
```
┌─────────────────────────────────────────────────────────────────┐
│  ⚠️  DEADLOCK DETECTED                                          │
├─────────────────────────────────────────────────────────────────┤
│  Circular wait detected between:                                │
│                                                                 │
│  agent-01 ──holds──► lock:task:123                              │
│     ▲                                      │                    │
│     └────────waits─────────────────────────┘                    │
│                                                                 │
│  agent-02 ──holds──► lock:resource:db/prod-01                   │
│     ▲                                      │                    │
│     └────────waits─────────────────────────┘                    │
│                                                                 │
│  [Resolve: Abort Youngest]  [Resolve: Abort Shortest]          │
└─────────────────────────────────────────────────────────────────┘
```

---

### 6. Form Components

#### Task Creation Form
```typescript
interface TaskCreationFormProps {
  initialValues?: Partial<TaskConfig>;
  resourceTypes: ResourceType[];
  availableResources: Array<{
    type: ResourceType;
    id: string;
    name: string;
  }>;
  onSubmit: (values: TaskConfig) => Promise<void>;
  onPreview: (values: TaskConfig) => Promise<PreviewResult>;
  onSaveDraft: (values: Partial<TaskConfig>) => Promise<void>;
}
```

**Sections:**
1. **Basic Info**: Type, Description, Priority
2. **Resources**: Multi-select with type filtering
3. **Parameters**: Dynamic form based on task type
4. **Advanced**: Timeout, Rollback strategy, Tags
5. **Preview**: Side panel showing changes before submit

---

#### Approval Response Form
```typescript
interface ApprovalResponseFormProps {
  approvalId: string;
  action: 'approve' | 'reject' | 'request_changes';
  requireReason: boolean;
  onSubmit: (values: { action: string; reason?: string }) => void;
  onCancel: () => void;
}
```

**Features:**
- Quick select buttons for common rejection reasons
- Character counter for reason field
- File attachment for supporting docs

---

### 7. Feedback Components

#### Toast Notifications
```typescript
interface ToastProps {
  id: string;
  type: 'success' | 'error' | 'warning' | 'info';
  title: string;
  message?: string;
  action?: {
    label: string;
    onClick: () => void;
  };
  duration?: number;
  onClose: (id: string) => void;
}
```

**Events:**
- Approval submitted
- Task approved/rejected
- Lock acquired/released
- Error notifications

---

#### Confirmation Dialogs
```typescript
interface ConfirmationDialogProps {
  isOpen: boolean;
  title: string;
  message: string;
  confirmLabel: string;
  cancelLabel: string;
  danger?: boolean;
  requireText?: string;  // Type to confirm (for destructive actions)
  onConfirm: () => void;
  onCancel: () => void;
}
```

**Use Cases:**
- Force release lock
- Cancel running task
- Batch approve high-risk items
- Delete delegation policy

---

### 8. Real-time Components

#### Live Update Indicator
```typescript
interface LiveIndicatorProps {
  status: 'connected' | 'disconnected' | 'reconnecting';
  lastUpdate?: string;
}
```

**Visual:**
- Green pulse dot when connected
- Yellow when reconnecting
- Red when disconnected with retry button

---

#### WebSocket Status Bar
```typescript
interface WebSocketStatusProps {
  connectionState: 'connecting' | 'open' | 'closed' | 'error';
  pendingEvents: number;
  onReconnect: () => void;
}
```

---

## Responsive Breakpoints

| Breakpoint | Width | Layout Changes |
|------------|-------|----------------|
| Mobile | < 640px | Single column, sidebar becomes drawer, table becomes cards |
| Tablet | 640-1024px | Two columns where applicable, condensed sidebar |
| Desktop | 1024-1440px | Full layout, fixed sidebar |
| Wide | > 1440px | Expanded content area, more data visible |

---

## Accessibility Requirements

### ARIA Labels
- All interactive elements have descriptive labels
- Live regions for real-time updates
- Role="status" for async operations

### Keyboard Navigation
- Tab order follows visual flow
- Escape closes modals/drawers
- Enter activates buttons, Space toggles checkboxes
- Arrow keys navigate tables and lists

### Screen Reader Support
- State changes announced via aria-live
- Complex visualizations have text alternatives
- Risk scores read as "High risk: 75 out of 100"

### Color Contrast
- Minimum 4.5:1 for normal text
- Minimum 3:1 for large text and icons
- States distinguishable without color

---

## Performance Targets

| Metric | Target |
|--------|--------|
| Initial Load | < 2s |
| Time to Interactive | < 3s |
| List Scroll | 60fps |
| Modal Open | < 100ms |
| Real-time Update | < 500ms latency |
| Form Submit | < 200ms feedback |

---

## Integration Points

### API Integration
- REST API for CRUD operations
- WebSocket for real-time events
- Server-Sent Events fallback

### External Services
- Auth provider for user info
- File storage for attachments
- Search service for full-text search

### Browser APIs
- Notifications API for approval alerts
- Idle Detection for auto-refresh pause
- Page Visibility for connection management