stack/docs/scratchpads/91-connection-manager-ui.md

Issue #91: Connection Manager UI

Objective

Implement the Connection Manager UI to allow users to view, initiate, accept, reject, and disconnect federation connections to remote Mosaic Stack instances.

Requirements

• View existing federation connections with their status
• Initiate new connections to remote instances
• Accept/reject pending connections
• Disconnect active connections
• Display connection status and metadata
• PDA-friendly design and language (no demanding language)
• Proper error handling and user feedback
• Test coverage for all components

Backend API Endpoints (Already Available)

• GET /api/v1/federation/connections - List all connections
• GET /api/v1/federation/connections/:id - Get single connection
• POST /api/v1/federation/connections/initiate - Initiate connection
• POST /api/v1/federation/connections/:id/accept - Accept connection
• POST /api/v1/federation/connections/:id/reject - Reject connection
• POST /api/v1/federation/connections/:id/disconnect - Disconnect connection
• GET /api/v1/federation/instance - Get local instance identity

Connection States

• PENDING - Connection initiated but not yet accepted
• ACTIVE - Connection established and working
• DISCONNECTED - Connection was active but now disconnected
• REJECTED - Connection was rejected

Approach

Phase 1: Core Components (TDD)

1. Create connection types and API client functions
2. Implement ConnectionCard component with tests
3. Implement ConnectionList component with tests
4. Implement InitiateConnectionDialog component with tests
5. Implement ConnectionActions component with tests

Phase 2: Page Implementation

1. Create /federation/connections page
2. Integrate all components
3. Add loading and error states
4. Implement real-time updates (optional)

Phase 3: 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

Visual Status Indicators (PDA-Friendly)

• 🟢 Active - Soft green (#10b981)
• 🔵 Pending - Soft blue (#3b82f6)
• ⏸️ Disconnected - Soft yellow (#f59e0b)
• ⚪ Rejected - Light gray (#d1d5db)

Language Guidelines

• "Target passed" instead of "overdue"
• "Approaching target" instead of "urgent"
• "Would you like to..." instead of "You must..."
• "Connection not responding" instead of "Connection failed"
• "Unable to connect" instead of "Connection error"

Component Structure

apps/web/src/
├── app/(authenticated)/federation/
│   └── connections/
│       └── page.tsx
├── components/federation/
│   ├── ConnectionCard.tsx
│   ├── ConnectionCard.test.tsx
│   ├── ConnectionList.tsx
│   ├── ConnectionList.test.tsx
│   ├── InitiateConnectionDialog.tsx
│   ├── InitiateConnectionDialog.test.tsx
│   ├── ConnectionActions.tsx
│   └── ConnectionActions.test.tsx
└── lib/api/
    └── federation.ts

Progress

• Create scratchpad
• Research existing backend API
• Review PDA-friendly design principles
• Implement federation API client
• Write tests for ConnectionCard
• Implement ConnectionCard
• Write tests for ConnectionList
• Implement ConnectionList
• Write tests for InitiateConnectionDialog
• Implement InitiateConnectionDialog
• Create connections page
• Run all tests (42 tests passing)
• TypeScript type checking (passing)
• Linting (passing)
• PDA-friendliness review (all language reviewed)
• Final QA (ready for review)

Testing Strategy

• Unit tests for each component
• Integration tests for the connections page
• Test error states and edge cases
• Test PDA-friendly language compliance
• Ensure all tests pass before commit

Notes

• Backend API is complete from Phase 1-3
• Need to handle authentication with BetterAuth
• Consider WebSocket for real-time connection status updates (Phase 5)
• Connection metadata can be extended for future features