Skip to content

Velocity SDK Integration

Overview

This user story covers the integration with the Velocity SDK for organization registration and credential operations, replacing the current direct API approach with a more robust and maintainable solution.

User Stories

Migrate to Velocity SDK

As a platform administrator,
I want to migrate from direct Velocity Network API calls to the Velocity SDK,
So that the platform has improved reliability, reduced complexity, and better maintainability.

Acceptance Criteria: - Given the platform currently uses direct API calls to Velocity Network - When the SDK migration is implemented - Then the system should use the Velocity SDK for all Velocity Network operations - And the code complexity should be reduced by approximately 68% - And the system should maintain all existing functionality - And error handling should be improved with built-in SDK mechanisms - And the system should support automatic SDK updates - And performance should be maintained or improved

Configure Velocity SDK Environment

As a platform administrator,
I want to configure the Velocity SDK with proper environment variables,
So that the integration works correctly in both sandbox and production environments.

Acceptance Criteria: - Given I need to configure the Velocity SDK - When I set up the environment variables - Then the system should require these essential (Tier 1) variables: - VNF_SDK_API_KEY - SDK access key from VCL - VNF_SDK_ENVIRONMENT - sandbox or production - VNF_AGENT_URL - Credential agent endpoint - VNF_SDK_DID - Organization DID - VNF_SDK_PRIVATE_KEY - Signing key - And the system should validate all required configuration on startup - And the system should fail to start if essential configuration is missing - And configuration should be environment-specific (sandbox vs production) - And sensitive configuration should be properly secured

Implement SDK Health Checks

As a platform administrator,
I want to monitor the health of the Velocity SDK integration,
So that I can ensure the system is functioning properly and identify issues quickly.

Acceptance Criteria: - Given the Velocity SDK is integrated - When I check the system health - Then I should see health indicators for: - SDK initialization status - Velocity Network connectivity - API response times - Error rates for SDK operations - Last successful operation timestamp - And health checks should run automatically at regular intervals - And alerts should be sent for SDK integration failures - And health status should be visible in the admin dashboard - And historical health data should be available for trend analysis

Replace Manual Payload Transformation

As a platform developer,
I want to replace the manual payload transformation logic with SDK methods,
So that the code is more maintainable and less error-prone.

Acceptance Criteria: - Given the current system has 311 lines of manual payload transformation code - When the SDK integration is implemented - Then the transformToVelocityPayload() method should be replaced with SDK methods - And the code should be reduced to approximately 100 lines - And all payload formatting should be handled by the SDK - And data validation should be improved with SDK validation - And the transformation should be more reliable and consistent - And the code should be easier to maintain and update

Implement SDK Error Handling

As a platform administrator,
I want to implement proper error handling for SDK operations,
So that the system can gracefully handle failures and provide meaningful error messages.

Acceptance Criteria: - Given SDK operations may fail due to various reasons - When an SDK operation encounters an error - Then the system should: - Use SDK-provided error handling mechanisms - Implement retry logic with exponential backoff - Log detailed error information for troubleshooting - Provide user-friendly error messages - Maintain system stability during failures - And temporary failures should be retried automatically - And permanent failures should be logged and reported - And error rates should be monitored and alerted on - And error handling should be consistent across all SDK operations

Support Batch Operations via SDK

As a staffing company user,
I want to perform batch operations using the SDK,
So that I can efficiently process large numbers of credentials and organizations.

Acceptance Criteria: - Given I need to process multiple operations simultaneously - When I use batch functionality - Then the SDK should support: - Batch credential issuance (500+ credentials) - Batch organization registration - Parallel processing where possible - Progress tracking for batch operations - Error handling for individual items in batches - And batch operations should be more efficient than individual operations - And the system should handle large batches without performance degradation - And batch results should provide detailed success/failure information - And batch operations should be resumable in case of interruption

Maintain Backward Compatibility

As a platform user,
I want to continue using existing functionality during the SDK migration,
So that there is no disruption to current operations.

Acceptance Criteria: - Given the SDK migration is being implemented - When the migration is in progress - Then all existing functionality should continue to work - And users should not experience any service interruption - And data integrity should be maintained throughout the migration - And the migration should be reversible if issues arise - And existing API endpoints should continue to function - And database schemas should remain compatible - And user interfaces should work without changes

Technical Notes

Implementation Phases

Based on the Velocity SDK Implementation Guide:

  1. Phase 1: Foundation Setup (Week 1)
  2. Environment variables configuration
  3. Package installation (@velocitycareerlabs/vnf-wallet-sdk)

  4. SDK credentials setup

  5. Phase 2: Core Service Implementation (Week 2)

  6. Replace VelocityRegistrarService with comprehensive VelocityService
  7. Configuration module updates

  8. Connection health checks

  9. Phase 3: Organization Registration Migration (Week 3)

  10. Replace HTTP calls in OrganizationService.createOrganization()
  11. Maintain Auth0 integration alongside SDK
  12. Update error handling

Performance Targets

  • Support 1000-2000 transactions/hour
  • Handle 1000 concurrent users
  • Process CSV batches of 500+ credentials
  • Generate verification reports under 2 seconds

Dependencies

  • Velocity SDK credentials from VCL
  • Environment configuration management
  • Background job processing system
  • Monitoring and alerting infrastructure

Priority

High - Essential for improving system reliability and maintainability, required for first project drop

References