stack/docs/scratchpads/92-aggregated-dashboard.md

# Issue #92: Aggregated Dashboard View

## Objective

Implement an Aggregated Dashboard View that displays data from multiple federated Mosaic Stack instances in a unified interface. This allows users to see tasks, events, and projects from all connected instances in one place, with clear provenance indicators showing which instance each item comes from.

## Requirements

Backend infrastructure complete from Phase 3:

- QUERY message type implemented
- Connection Manager UI (FED-008) implemented
- Query service with signature verification
- Connection status tracking

Frontend requirements:

- Display data from multiple federated instances in unified view
- Query federated instances for tasks, events, projects
- Show data provenance (which instance data came from)
- Filter and sort aggregated data
- PDA-friendly design (no demanding language)
- Proper loading states and error handling
- Minimum 85% test coverage

## Approach

### Phase 1: Federation API Client (TDD)

1. Write tests for federation query API client
2. Implement federation query client functions:
   - `sendFederatedQuery(connectionId, query, context)`
   - `fetchQueryMessages(status?)`
   - Types for federated queries and responses

### Phase 2: Core Components (TDD)

1. Write tests for FederatedTaskCard component
2. Implement FederatedTaskCard with provenance indicator
3. Write tests for FederatedEventCard component
4. Implement FederatedEventCard with provenance indicator
5. Write tests for AggregatedDataGrid component
6. Implement AggregatedDataGrid with filtering/sorting

### Phase 3: Dashboard Page Implementation

1. Create `/federation/dashboard` page
2. Integrate components
3. Implement query logic to fetch from all active connections
4. Add loading and error states
5. Add empty states

### Phase 4: PDA-Friendly Polish

1. Review all language for PDA-friendliness
2. Implement calm visual indicators
3. Add helpful empty states
4. Test error messaging

## Design Decisions

### Data Provenance Indicators

Each item shows its source instance with:

- Instance name badge
- Instance-specific color coding (subtle)
- Hover tooltip with full instance details
- "From: [Instance Name]" text

### PDA-Friendly Language

- "Unable to reach" instead of "Connection failed"
- "No data available" instead of "No results"
- "Loading data from instances..." instead of "Fetching..."
- "Would you like to..." instead of "You must..."
- Status indicators: 🟢 Active, 🔵 Loading, ⏸️ Paused, ⚪ Unavailable

### Component Structure

```
apps/web/src/
├── app/(authenticated)/federation/
│   └── dashboard/
│       └── page.tsx
├── components/federation/
│   ├── FederatedTaskCard.tsx
│   ├── FederatedTaskCard.test.tsx
│   ├── FederatedEventCard.tsx
│   ├── FederatedEventCard.test.tsx
│   ├── AggregatedDataGrid.tsx
│   ├── AggregatedDataGrid.test.tsx
│   ├── ProvenanceIndicator.tsx
│   └── ProvenanceIndicator.test.tsx
└── lib/api/
    └── federation-queries.ts (extend federation.ts)
```

### Query Strategy

For MVP:

- Query all ACTIVE connections on page load
- Show loading state per connection
- Display results as they arrive
- Cache results for 5 minutes (optional, future enhancement)
- Handle connection failures gracefully

## Progress

- [x] Create scratchpad
- [x] Research backend query API
- [x] Extend federation API client with query support
- [x] Write tests for ProvenanceIndicator
- [x] Implement ProvenanceIndicator
- [x] Write tests for FederatedTaskCard
- [x] Implement FederatedTaskCard
- [x] Write tests for FederatedEventCard
- [x] Implement FederatedEventCard
- [x] Write tests for AggregatedDataGrid
- [x] Implement AggregatedDataGrid
- [x] Create dashboard page
- [x] Implement query orchestration logic
- [x] Add loading/error states
- [x] Run all tests (86 tests passing)
- [x] TypeScript type checking (passing)
- [x] Linting (passing)
- [x] PDA-friendliness review (all language reviewed)
- [x] Final QA (ready for review)

## Testing Strategy

- Unit tests for each component
- Integration tests for the dashboard page
- Test error states and edge cases
- Test provenance display accuracy
- Test PDA-friendly language compliance
- Test loading states for slow connections
- Ensure all tests pass before commit

## API Endpoints Used

From backend (already implemented):

- `POST /api/v1/federation/query` - Send query to remote instance
- `GET /api/v1/federation/queries` - List query messages
- `GET /api/v1/federation/queries/:id` - Get single query message
- `GET /api/v1/federation/connections` - List connections

Query payload structure:

```json
{
  "connectionId": "conn-1",
  "query": "tasks.list",
  "context": {
    "status": "IN_PROGRESS",
    "limit": 10
  }
}
```

Query response structure:

```json
{
  "id": "msg-123",
  "messageId": "uuid",
  "status": "DELIVERED",
  "response": {
    "data": [...],
    "provenance": {
      "instanceId": "instance-work-001",
      "timestamp": "2026-02-03T..."
    }
  }
}
```

## Notes

- Backend query service is complete (query.service.ts)
- Need to define standard query names: "tasks.list", "events.list", "projects.list"
- Consider implementing query result caching in future phase
- Real-time updates via WebSocket can be added later (Phase 5)
- Initial implementation will use polling/manual refresh

## Blockers

None - all backend infrastructure is complete.

## Related Issues

- #85 (FED-005): QUERY Message Type - COMPLETED
- #91 (FED-008): Connection Manager UI - COMPLETED
- #90 (FED-007): EVENT Subscriptions - COMPLETED (for future real-time updates)