# Real-time Activity Feed - Design Prototype

## Overview
The Activity Feed provides a real-time view of all events happening across Syndarix projects. It displays agent status changes, messages, issue updates, sprint events, approval requests, and errors. This is the central hub for monitoring autonomous agent activity and responding to approval requests.

## User Stories
- As a user, I want to see real-time updates from my projects so I stay informed
- As a user, I want to filter events by type, agent, or project to focus on what matters
- As a user, I want to quickly identify items requiring my action
- As a user, I want to expand events to see more details
- As a user, I want to approve or reject requests directly from the feed
- As a user, I want to know if I'm connected to the real-time stream
- As a user, I want to mark events as read to track what I've seen

## Key Screens

### Main Feed View

**Header**
- Page title with description
- Action required count badge
- Mark all read button
- Real-time connection indicator

**Search and Filters**
- Full-text search input
- Filter button (toggles filter panel)
- Refresh button

**Filter Panel** (expandable)
- Event type checkboxes (with icons)
- Agent checkboxes
- "Action required only" toggle
- Clear all / Apply buttons

**Event Groups**
- Grouped by time period: New, Earlier Today, Yesterday, This Week, Older
- Group header with count badge
- Separator line

**Event Cards**
- Event type icon (colored)
- Title with New/Action Required badges
- Description text
- Metadata row (agent, project, type)
- Expand/collapse button
- Expanded details (conditional)
- Action buttons (for approval requests)

## Event Types

| Type | Icon | Color | Description |
|------|------|-------|-------------|
| Agent Status | Bot | Blue | Agent started, paused, resumed, stopped |
| Agent Message | MessageSquare | Purple | Agent communication, updates, questions |
| Issue Update | CircleDot | Green | Status change, assignment, creation |
| Sprint Event | Zap | Yellow | Standup, retrospective, planning |
| Approval Request | AlertCircle | Orange | Requires user action |
| Error | XCircle | Red | Agent or system errors |
| Milestone | CheckCircle | Emerald | Goals achieved, completions |

## User Flow

### Monitoring Activity
1. User lands on feed page
2. Feed shows real-time updates (newest first)
3. User scrolls through events
4. User clicks event to expand details
5. User navigates to related issue/PR if needed

### Filtering Events
1. User clicks Filter button
2. Filter panel expands
3. User selects event types, agents, etc.
4. User clicks Apply
5. Feed updates to show matching events

### Handling Approval Request
1. Approval request appears with orange badge
2. User reads request details
3. User clicks Approve or Request Changes
4. Event updates to show completed
5. Badge count decreases

## Design Decisions

### Card-Based Layout
- Each event is a distinct card
- Visual separation between events
- Expandable for more details
- Cards are self-contained

### Time-Based Grouping
- Events grouped by time period
- Helps users orient in the timeline
- "New" group highlights unread items
- Clear visual hierarchy

### Real-Time Indicator
- Pulsing green dot when connected
- Gray dot when disconnected
- Builds trust in data freshness
- Matches common patterns (Slack, Discord)

### Action Required Emphasis
- Orange left border on cards
- Badge in header with count
- Cannot be missed
- Inline approval buttons

### Expandable Details
- Keeps feed scannable
- Details available on demand
- Consistent expand/collapse pattern
- Metadata shown when expanded

### Search and Filters
- Combined search and filter approach
- Quick search for specific events
- Structured filters for browsing
- Filter state indicator

## States

### Loading
- Skeleton cards while loading
- Connection indicator shows connecting

### Empty
- No events: "Activity will appear here" message
- No matches: "Try adjusting filters" message

### Disconnected
- Gray indicator
- Retry button available
- Last known data shown

### Action Completed
- Card updates to remove action badge
- Success toast notification

## Responsive Breakpoints

### Desktop (lg: 1024px+)
- Centered content (max-w-3xl)
- Full filter panel inline
- Comfortable spacing

### Tablet (md: 768px)
- Full-width content
- Filter panel still inline
- Slightly tighter spacing

### Mobile (< 768px)
- Full-width cards
- Filter panel stacks vertically
- Touch-friendly buttons
- Simplified metadata row

## Accessibility Notes
- Event type icons have text labels
- Color is not only indicator (badges, icons)
- Keyboard navigation for expand/collapse
- Screen reader announces new events
- Focus management on filter panel
- Live region for real-time updates

## Components Used
- Card, CardContent
- Button (default, outline, ghost variants)
- Badge (default, secondary, outline, destructive variants)
- Input (search)
- Checkbox
- Label
- Separator
- Lucide icons

## Event Data Structure

```typescript
interface ActivityEvent {
  id: string;
  type: 'agent_status' | 'agent_message' | 'issue_update' |
        'sprint_event' | 'approval_request' | 'error' | 'milestone';
  title: string;
  description: string;
  timestamp: string; // ISO 8601
  agent: {
    name: string;
    avatar: string;
  };
  project: string;
  metadata: {
    issueNumber?: number;
    pullRequest?: number;
    documentUrl?: string;
    progress?: number;
    summary?: {
      agents: number;
      inProgress: number;
      blocked: number;
    };
    importance?: 'low' | 'medium' | 'high';
    // ... other type-specific fields
  };
  requiresAction: boolean;
  isNew: boolean;
}
```

## Real-Time Implementation Notes

For production, the feed should:
1. Connect via WebSocket or SSE
2. Handle reconnection gracefully
3. Queue events during disconnect
4. Merge with existing events on reconnect
5. Support pagination for history
6. Implement optimistic updates for actions

## Questions for Review
1. Should events be grouped by time or show flat chronologically?
2. How many events should load initially? (Currently showing 10)
3. Should there be sound/browser notifications for urgent items?
4. Should users be able to "star" or save important events?
5. Should there be a compact view option?
6. Should events support threading/replies?

## How to View
Navigate to: `/prototypes/activity-feed`

Try the features:
1. Scroll through the event feed
2. Click events to expand details
3. Open the filter panel
4. Try the action buttons on approval requests
5. Use the search to filter events

## Next Steps
After approval:
1. Implement WebSocket connection for real-time updates
2. Add browser notification support
3. Implement event pagination (infinite scroll)
4. Add optimistic updates for approve/dismiss
5. Implement notification sound settings
6. Add project-level filtering
7. Implement event archiving
8. Add keyboard shortcuts (j/k navigation)
