stack/docs/scratchpads/94-spoke-configuration-ui.md

Issue #94: Spoke Configuration UI (FED-011)

Objective

Implement a Spoke Configuration UI that allows administrators to configure their local instance's federation capabilities and settings. This is the spoke-side configuration that determines what features this instance exposes to the federation.

Context

This is THE FINAL implementation issue for M7-Federation! All backend and other UI components are complete:

• Instance Identity Model (FED-001) ✅
• CONNECT/DISCONNECT Protocol (FED-002) ✅
• OIDC Integration (FED-003) ✅
• Identity Linking (FED-004) ✅
• QUERY/COMMAND/EVENT message types (FED-005/006/007) ✅
• Connection Manager UI (FED-008) ✅
• Aggregated Dashboard (FED-009) ✅
• Agent Spawn via Federation (FED-010) ✅

Now we need the UI to configure the LOCAL instance (spoke) settings.

Requirements

Frontend requirements:

• Configure local instance federation settings
• Enable/disable federation features:
  • Query support (allow remote instances to query this instance)
  • Command support (allow remote instances to send commands)
  • Event support (allow remote instances to subscribe to events)
  • Agent spawn support (allow remote instances to spawn agents)
• Manage instance metadata (name, description)
• Display current instance identity (ID, URL, public key)
• PDA-friendly design (no demanding language)
• Admin-only access (requires admin privileges)
• Proper validation and user feedback
• Minimum 85% test coverage

Backend API Available

From federation.controller.ts:

• GET /api/v1/federation/instance - Get instance identity
• POST /api/v1/federation/instance/regenerate-keys - Regenerate keypair (admin only)

Need to ADD:

• PATCH /api/v1/federation/instance - Update instance configuration (admin only)

Instance Schema

From schema.prisma:

model Instance {
  id         String @id @default(uuid()) @db.Uuid
  instanceId String @unique @map("instance_id")
  name       String
  url        String
  publicKey  String @map("public_key") @db.Text
  privateKey String @map("private_key") @db.Text // Encrypted

  capabilities Json @default("{}")
  metadata     Json @default("{}")

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Capabilities structure:

interface FederationCapabilities {
  supportsQuery: boolean;
  supportsCommand: boolean;
  supportsEvent: boolean;
  supportsAgentSpawn: boolean;
  protocolVersion: string;
}

Approach

Phase 1: Backend API Endpoint (TDD)

1. Add UpdateInstanceDto in federation DTOs
2. Add updateInstanceConfiguration() method to FederationService
3. Add PATCH /api/v1/federation/instance endpoint to controller
4. Write comprehensive tests
5. Ensure admin-only access via AdminGuard

Phase 2: Frontend API Client (TDD)

1. Extend federation.ts API client with:
   • updateInstanceConfiguration(data) function
   • UpdateInstanceRequest interface
   • Tests for the new API function

Phase 3: Core Components (TDD)

1. Create SpokeConfigurationForm component:

   • Display current instance identity (read-only)
   • Edit instance name and description
   • Toggle federation capabilities (checkboxes)
   • Save/Cancel actions
   • Loading and error states

2. Create CapabilityToggle component:

   • Individual capability toggle with label
   • Help text explaining what each capability does
   • Disabled state when saving

3. Create RegenerateKeysDialog component:

   • Warning about regenerating keys
   • Confirmation dialog
   • Shows new public key after regeneration

Phase 4: Page Implementation

1. Create /federation/settings page
2. Integrate components
3. Admin-only route protection
4. Add loading and error states
5. Success feedback on save

Phase 5: PDA-Friendly Polish

1. Review all language for PDA-friendliness
2. Implement calm visual indicators
3. Add helpful descriptions for each capability
4. Test error messaging
5. Add confirmation dialogs for destructive actions

Design Decisions

PDA-Friendly Language

❌ NEVER:

• "You must configure"
• "Required settings"
• "Critical - configure now"
• "Error: Invalid configuration"

✅ ALWAYS:

• "Configure your instance settings"
• "Recommended settings"
• "Consider configuring these options"
• "Unable to save configuration"

Visual Design

• Use Shadcn/ui components (Card, Switch, Button, Dialog)
• Clear section headers: "Instance Identity", "Federation Capabilities", "Advanced"
• Read-only fields for sensitive data (instance ID, public key)
• Truncate long public key with "Copy" button
• Soft color indicators: 🟢 Enabled, ⚪ Disabled

Component Structure

apps/web/src/
├── app/(authenticated)/federation/
│   └── settings/
│       └── page.tsx                         # NEW
├── components/federation/
│   ├── SpokeConfigurationForm.tsx           # NEW
│   ├── SpokeConfigurationForm.test.tsx      # NEW
│   ├── CapabilityToggle.tsx                 # NEW
│   ├── CapabilityToggle.test.tsx            # NEW
│   ├── RegenerateKeysDialog.tsx             # NEW
│   └── RegenerateKeysDialog.test.tsx        # NEW
└── lib/api/
    └── federation.ts                         # UPDATE

Capability Descriptions

Each capability toggle includes help text:

• Query Support: "Allows connected instances to query data from this instance (tasks, events, projects)"
• Command Support: "Allows connected instances to send commands to this instance"
• Event Support: "Allows connected instances to subscribe to events from this instance"
• Agent Spawn Support: "Allows connected instances to spawn and manage agents on this instance"

Progress

• Create scratchpad
• Add backend API endpoint (PATCH /api/v1/federation/instance)
• Write tests for FederationService.updateInstanceConfiguration
• Implement FederationService.updateInstanceConfiguration
• Update FederationController with PATCH endpoint
• Add audit logging for configuration updates
• Extend frontend API client (federation.ts)
• Write tests for SpokeConfigurationForm (10 tests, all passing)
• Implement SpokeConfigurationForm
• Create /federation/settings page (with regenerate keys functionality)
• Run all tests (13 backend tests passing, 10 frontend 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
• Test capability toggle functionality
• Test form validation
• Test save/cancel actions
• Test error handling
• Test admin-only access
• Test key regeneration flow
• Ensure all tests pass before commit

Security Considerations

1. Admin-only access via AdminGuard
2. Never expose private key in UI or API responses
3. Require confirmation for key regeneration
4. Audit log for configuration changes
5. Validate all inputs on backend

Notes

• This is the final piece of M7-Federation
• Backend infrastructure is 100% complete
• UI patterns established by previous federation components
• Need to ensure proper admin role checking
• Consider rate limiting for key regeneration (prevent abuse)

Blockers

None - all dependencies complete.

Related Issues

• #84 (FED-001): Instance Identity Model - COMPLETED
• #91 (FED-008): Connection Manager UI - COMPLETED (UI pattern reference)
• #92 (FED-009): Aggregated Dashboard - COMPLETED (UI pattern reference)