claude-relay-service/.spec-workflow/archive/specs/api-keys-batch-management/design.md

Design Document

Overview

The API Keys Batch Management feature extends the existing Claude Relay Service infrastructure to provide comprehensive batch operations for API key management. The design leverages the current Vue.js 3 frontend architecture, Express.js backend routing, and Redis data persistence while introducing new batch operation services and enhanced user interface components.

The solution follows the established patterns in the codebase: service-oriented backend architecture, middleware-based authentication, and reactive frontend components with modern UI/UX design principles.

Steering Document Alignment

Technical Standards (tech.md)

The implementation follows Node.js/Express.js backend patterns and Vue.js 3 Composition API frontend architecture established in the project. All batch operations maintain consistency with existing API key management patterns and security middleware.

Project Structure (structure.md)

New components will be organized following the existing structure:

• Backend services in src/services/
• API routes in src/routes/admin.js
• Frontend components in web/admin-spa/src/components/
• Utilities in respective utils/ directories

Code Reuse Analysis

Existing Components to Leverage

• ApiKeyService: Extend with batch operation methods for tag management, account assignment, and status updates
• Redis Model: Utilize existing redis.js methods for data persistence and add batch-specific operations
• Admin Authentication: Reuse authenticateAdmin middleware for securing batch operations
• ApiKeysView.vue: Extend existing multi-select implementation with enhanced batch operation controls
• API Client: Extend existing apiClient with batch operation endpoints

Integration Points

• Existing Batch Delete: Build upon current batch delete infrastructure in admin routes
• Multi-select State: Enhance existing selectedApiKeys, selectAllChecked, isIndeterminate reactive state
• Logger Service: Integrate with existing Winston logging for audit trails
• Toast Notifications: Use existing toast system for batch operation feedback

Architecture

The batch management system follows a layered architecture pattern consistent with the existing codebase:

graph TD
    A[Vue.js Frontend] --> B[API Client Layer]
    B --> C[Express.js Routes]
    C --> D[Authentication Middleware]
    D --> E[Batch Service Layer]
    E --> F[API Key Service]
    E --> G[Audit Service]
    F --> H[Redis Data Layer]
    G --> H
    
    I[Progress Tracking] --> E
    J[Transaction Manager] --> E

Modular Design Principles

• Single File Responsibility: Each batch operation type (tags, accounts, status) handled by focused service modules
• Component Isolation: UI components separated by operation type with shared base components
• Service Layer Separation: Clear separation between data access (Redis), business logic (services), and presentation (Vue components)
• Utility Modularity: Batch operation utilities organized by function (validation, progress tracking, audit logging)

Components and Interfaces

Backend Components

BatchOperationService

• Purpose: Orchestrates batch operations with transaction management and progress tracking
• Interfaces:
  • batchUpdateTags(keyIds, tagsToAdd, tagsToRemove)
  • batchUpdateAccounts(keyIds, accountAssignments)
  • batchUpdateStatus(keyIds, isActive)
  • getBatchProgress(operationId)
• Dependencies: ApiKeyService, AuditService, Redis
• Reuses: Existing error handling patterns from admin routes

BatchTagService

• Purpose: Handles tag-specific batch operations with conflict resolution
• Interfaces:
  • addTagsToKeys(keyIds, tags)
  • removeTagsFromKeys(keyIds, tags)
  • getTagConflicts(keyIds, newTags)
• Dependencies: Redis, Logger
• Reuses: Existing tag parsing and validation logic from ApiKeyService

BatchAccountService

• Purpose: Manages account assignment operations with validation
• Interfaces:
  • assignAccounts(keyIds, accountData)
  • validateAccountAssignments(assignments)
  • resolveAccountConflicts(keyIds, accountData)
• Dependencies: Account validation services, Redis
• Reuses: Existing account validation from ApiKeyService

AuditService

• Purpose: Comprehensive logging and audit trail management
• Interfaces:
  • logBatchOperation(operationType, keyIds, changes, adminId)
  • createAuditEntry(keyId, beforeState, afterState, operation)
  • exportAuditData(filters)
• Dependencies: Logger, Redis
• Reuses: Existing Winston logger configuration

Frontend Components

BatchOperationPanel.vue

• Purpose: Main batch operation interface with operation selection and progress display
• Interfaces:
  • Props: selectedKeys, availableOperations
  • Events: @operation-selected, @operation-cancelled
• Dependencies: API Client, Toast service
• Reuses: Existing modal patterns and button components

TagManagementModal.vue

• Purpose: Specialized modal for batch tag operations
• Interfaces:
  • Props: selectedKeys, existingTags
  • Events: @tags-updated, @operation-cancelled
• Dependencies: Tag validation utilities
• Reuses: Existing modal base component and form validation patterns

AccountAssignmentModal.vue

• Purpose: Interface for batch account assignment
• Interfaces:
  • Props: selectedKeys, availableAccounts
  • Events: @accounts-assigned, @operation-cancelled
• Dependencies: Account service, validation utilities
• Reuses: Existing dropdown components and form validation

BatchProgressTracker.vue

• Purpose: Real-time progress display for batch operations
• Interfaces:
  • Props: operationId, totalItems
  • Events: @operation-complete, @operation-failed
• Dependencies: WebSocket or polling service for real-time updates
• Reuses: Existing progress bar components and loading states

Data Models

BatchOperation

{
  id: "string",              // Unique operation identifier
  type: "string",            // 'tag-update', 'account-assignment', 'status-change'
  keyIds: ["string"],        // Array of API key IDs
  adminId: "string",         // Administrator performing operation
  status: "string",          // 'pending', 'in-progress', 'completed', 'failed'
  progress: {
    total: "number",         // Total items to process
    completed: "number",     // Items completed
    failed: "number",        // Items failed
    errors: ["object"]       // Error details for failed items
  },
  data: "object",            // Operation-specific data (tags, accounts, etc.)
  createdAt: "timestamp",
  completedAt: "timestamp",
  result: "object"           // Operation results and summary
}

BatchTagUpdate

{
  tagsToAdd: ["string"],     // Tags to add to selected keys
  tagsToRemove: ["string"],  // Tags to remove from selected keys
  conflictResolution: "string", // 'merge', 'replace', 'skip'
  preserveExisting: "boolean"   // Whether to preserve existing tags
}

BatchAccountAssignment

{
  claudeAccountId: "string",       // Claude account ID (optional)
  geminiAccountId: "string",       // Gemini account ID (optional)
  openaiAccountId: "string",       // OpenAI account ID (optional)
  bedrockAccountId: "string",      // Bedrock account ID (optional)
  overwriteExisting: "boolean",    // Whether to overwrite existing assignments
  conflictResolution: "string"     // How to handle conflicts
}

AuditEntry

{
  id: "string",
  keyId: "string",           // Affected API key ID
  operationId: "string",     // Batch operation ID
  adminId: "string",         // Administrator ID
  operationType: "string",   // Type of operation performed
  beforeState: "object",     // State before change
  afterState: "object",      // State after change
  timestamp: "timestamp",
  success: "boolean",
  errorMessage: "string"     // Error details if operation failed
}

Error Handling

Error Scenarios

1. Partial Operation Failure

   • Handling: Continue processing remaining items, collect all errors, provide detailed failure report
   • User Impact: User sees summary of successful/failed operations with specific error details

2. Transaction Rollback Required

   • Handling: Implement Redis transactions for atomic operations, rollback on critical failures
   • User Impact: Clear indication that operation was cancelled and no changes were made

3. Concurrent Operation Conflict

   • Handling: Use Redis locks to prevent concurrent batch operations on same keys
   • User Impact: User informed that operation cannot proceed due to conflict, suggested retry timing

4. Network/Database Connection Issues

   • Handling: Implement retry logic with exponential backoff, save operation state for recovery
   • User Impact: Progress preserved, operation can be resumed when connection restored

5. Invalid Data Validation Errors

   • Handling: Pre-validate all data before starting operation, provide specific validation errors
   • User Impact: Clear validation feedback before operation starts, prevents wasted processing

Testing Strategy

Unit Testing

• Service Layer Testing: Test each batch service independently with mocked dependencies
• Validation Logic: Test tag validation, account assignment validation, and conflict resolution
• Error Handling: Test error scenarios, rollback mechanisms, and partial failure handling
• Audit Logging: Verify audit entries are created correctly for all operations

Integration Testing

• API Endpoint Testing: Test batch operation endpoints with various data combinations
• Database Integration: Test Redis transactions and data consistency
• Authentication: Verify admin authentication for all batch operations
• Cross-service Communication: Test interaction between batch services and existing services

End-to-End Testing

• Complete User Workflows: Test full batch operation workflows from UI to database
• Multi-select Interactions: Test selection persistence across search and pagination
• Progress Tracking: Verify real-time progress updates and completion notifications
• Error Recovery: Test user experience during various error scenarios

Performance Testing

• Large Batch Operations: Test performance with 100, 500, and 1000 API keys
• Concurrent User Operations: Test system behavior with multiple administrators
• Memory Usage: Monitor memory consumption during large batch operations
• Response Times: Ensure UI responsiveness during background processing