Skip to content

Milestone: M2 — Platform and Client Admin | SOW Reference: FR5 | Requirement Clarity: 🟡 See phasing note below | Dev Status: 🟢 Prototyped in POC Moved from docs/requirements/tasks/kyb-verification-implementation.md — this is the original detailed implementation breakdown, unmodified below. Phasing note (not covered in the moved content below): the SOW's Appendix 1 FR5 text says KYB checks "will initially take place directly at the Velocity Registrar for the MVP but should be executed via a web form on the platform by full Beta release." That implies the in-platform KYB web form (as built here) may not need to be live for the initial MVP milestone — only by the point of full Beta. Confirm with Curo which milestone this web-form requirement actually gates against, since the task breakdown below builds the web form outright with no phasing distinction.

M2-01 KYB Verification Implementation Tasks

This document breaks down the implementation tasks for creating the Know Your Business (KYB) verification functionality of the REC Verifiable Credentialing Platform. KYB verification is a critical compliance step to ensure that only legitimate businesses can use the platform for issuing and verifying credentials.

Implementation Strategy

The implementation will follow these steps: 1. Create DTOs for KYB verification 2. Implement services for KYB record management 3. Develop controllers for KYB verification API endpoints 4. Create document upload and storage functionality 5. Implement the verification workflow 6. Develop the compliance officer dashboard

Current Implementation Status

The project currently has:

  1. KYB Record Entity:
  2. Basic KybRecord entity with fields for status, notes, and evidence

  3. Relationship to the Organization entity

  4. Organization Entity:

  5. KybStatus field to track verification status

Backend Tasks

KYB Verification DTOs

  • Create app/backend/src/admin/dto/kyb-record.dto.ts
  • Implement CreateKybRecordDto:
    • orgId (string, required): Organization ID
    • documents (array, required): Array of document metadata
    • notes (string, optional): Additional notes
  • Implement UpdateKybRecordDto:
    • status (enum, optional): KYB record status
    • notes (string, optional): Additional notes
    • evidence (object, optional): Evidence metadata
  • Implement KybRecordResponseDto:
    • id (string): KYB record ID
    • orgId (string): Organization ID
    • status (string): KYB record status
    • notes (string): Additional notes
    • evidence (object): Evidence metadata
    • createdAt (string): Creation timestamp
    • updatedAt (string): Last update timestamp
  • Implement KybDocumentDto:
    • type (string, required): Document type (e.g., "business_registration", "tax_certificate")
    • name (string, required): Document name
    • description (string, optional): Document description
    • fileKey (string, required): S3 file key
    • mimeType (string, required): File MIME type
    • size (number, required): File size in bytes
    • uploadedAt (string, required): Upload timestamp

Document Upload Service

  • Create app/backend/src/admin/services/document.service.ts
  • Implement constructor with dependencies:
    • Inject ConfigService for accessing S3 configuration
    • Inject LoggerService for logging
  • Implement uploadDocument method:
    • Parameters: file (Buffer), metadata (object)
    • Returns: Promise (S3 file key)
    • Generate a unique file key
    • Upload the file to S3
    • Log the upload operation
  • Implement getDocumentUrl method:
    • Parameters: fileKey (string)
    • Returns: string (presigned URL)
    • Generate a presigned URL for the file
  • Implement deleteDocument method:
    • Parameters: fileKey (string)
    • Returns: Promise
    • Delete the file from S3
    • Log the delete operation

KYB Record Service

  • Create app/backend/src/admin/services/kyb-record.service.ts
  • Implement constructor with dependencies:
    • Inject KybRecordRepository
    • Inject OrganizationRepository
    • Inject DocumentService
    • Inject LoggerService
  • Implement createKybRecord method:
    • Parameters: CreateKybRecordDto
    • Returns: Promise
    • Create a new KYB record
    • Associate it with the organization
    • Update the organization's KYB status to PENDING
    • Log the creation operation
  • Implement getKybRecords method:
    • Parameters: filters (object)
    • Returns: Promise<[KybRecord[], number]>
    • Get KYB records with pagination and filtering
  • Implement getKybRecordById method:
    • Parameters: id (string)
    • Returns: Promise
    • Get a single KYB record by ID
  • Implement updateKybRecord method:
    • Parameters: id (string), UpdateKybRecordDto
    • Returns: Promise
    • Update the KYB record
    • If status is changed, update the organization's KYB status
    • Log the update operation
  • Implement approveKybRecord method:
    • Parameters: id (string), notes (string)
    • Returns: Promise
    • Update the KYB record status to APPROVED
    • Update the organization's KYB status to APPROVED
    • Log the approval operation
  • Implement rejectKybRecord method:
    • Parameters: id (string), reason (string)
    • Returns: Promise
    • Update the KYB record status to REJECTED
    • Update the organization's KYB status to REJECTED
    • Log the rejection operation
  • Implement requestAdditionalInfo method:
    • Parameters: id (string), info (string)
    • Returns: Promise
    • Update the KYB record status to ADDITIONAL_INFO_REQUIRED
    • Update the organization's KYB status to ADDITIONAL_INFO_REQUIRED
    • Log the request operation

KYB Record Controller

  • Create app/backend/src/admin/controllers/kyb-record.controller.ts
  • Implement constructor with dependencies:
    • Inject KybRecordService
    • Inject DocumentService
  • Implement createKybRecord endpoint:
    • POST /organizations/:id/kyb
    • Parameters: organizationId (path), CreateKybRecordDto (body)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to appropriate roles
    • Add validation using class-validator
    • Add Swagger documentation
  • Implement getOrganizationKybRecords endpoint:
    • GET /organizations/:id/kyb
    • Parameters: organizationId (path), pagination and filter params (query)
    • Returns: Array of KybRecordResponseDto
    • Add @Roles decorator to restrict access to appropriate roles
    • Add Swagger documentation
  • Implement getKybRecords endpoint:
    • GET /kyb-records
    • Parameters: pagination and filter params (query)
    • Returns: Array of KybRecordResponseDto
    • Add @Roles decorator to restrict access to PLATFORM_ADMIN and SYSTEM_AUDITOR
    • Add Swagger documentation
  • Implement getKybRecordById endpoint:
    • GET /kyb-records/:id
    • Parameters: recordId (path)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to appropriate roles
    • Add Swagger documentation
  • Implement updateKybRecord endpoint:
    • PUT /kyb-records/:id
    • Parameters: recordId (path), UpdateKybRecordDto (body)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to appropriate roles
    • Add validation using class-validator
    • Add Swagger documentation
  • Implement approveKybRecord endpoint:
    • PUT /kyb-records/:id/approve
    • Parameters: recordId (path), notes (body)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to PLATFORM_ADMIN and SYSTEM_AUDITOR
    • Add Swagger documentation
  • Implement rejectKybRecord endpoint:
    • PUT /kyb-records/:id/reject
    • Parameters: recordId (path), reason (body)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to PLATFORM_ADMIN and SYSTEM_AUDITOR
    • Add Swagger documentation
  • Implement requestAdditionalInfo endpoint:
    • PUT /kyb-records/:id/request-info
    • Parameters: recordId (path), info (body)
    • Returns: KybRecordResponseDto
    • Add @Roles decorator to restrict access to PLATFORM_ADMIN and SYSTEM_AUDITOR
    • Add Swagger documentation
  • Implement uploadDocument endpoint:
    • POST /kyb-records/:id/documents
    • Parameters: recordId (path), file (multipart/form-data)
    • Returns: KybDocumentDto
    • Add @Roles decorator to restrict access to appropriate roles
    • Add Swagger documentation
  • Implement getDocumentUrl endpoint:
    • GET /kyb-records/:id/documents/:documentId
    • Parameters: recordId (path), documentId (path)
    • Returns: { url: string }
    • Add @Roles decorator to restrict access to appropriate roles
    • Add Swagger documentation

KYB Verification Workflow

  • Create app/backend/src/admin/services/kyb-workflow.service.ts
  • Implement constructor with dependencies:
    • Inject KybRecordService
    • Inject EmailService
    • Inject LoggerService
  • Implement startVerification method:
    • Parameters: organizationId (string)
    • Returns: Promise
    • Create a new KYB record
    • Send notification email to compliance officers
    • Log the workflow start
  • Implement completeVerification method:
    • Parameters: recordId (string), approved (boolean), notes (string)
    • Returns: Promise
    • Update the KYB record status
    • Send notification email to the organization
    • Log the workflow completion
  • Implement requestAdditionalInformation method:
    • Parameters: recordId (string), info (string)
    • Returns: Promise
    • Update the KYB record status
    • Send notification email to the organization
    • Log the workflow update

Unit Tests

  • Create app/backend/src/admin/services/kyb-record.service.spec.ts
  • Test createKybRecord method
  • Test getKybRecords method
  • Test getKybRecordById method
  • Test updateKybRecord method
  • Test approveKybRecord method
  • Test rejectKybRecord method

  • Test requestAdditionalInfo method

  • Create app/backend/src/admin/controllers/kyb-record.controller.spec.ts

  • Test all controller endpoints
  • Test authorization restrictions
  • Test validation errors

Frontend Tasks

KYB Submission Form

  • Create app/frontend/src/components/kyb/KybSubmissionForm.tsx
  • Implement form with the following fields:
    • Document upload section with drag-and-drop support
    • Document type selection
    • Document description
    • Additional notes
  • Add validation for all inputs
  • Implement form submission to API
  • Add success/error handling
  • Add progress indicators for file uploads

KYB Verification Dashboard

  • Create app/frontend/src/components/kyb/KybDashboard.tsx
  • Implement dashboard with the following sections:
    • Pending verifications
    • In-progress verifications
    • Completed verifications
  • Add filtering and sorting options
  • Implement pagination
  • Add search functionality

KYB Record Detail View

  • Create app/frontend/src/components/kyb/KybRecordDetail.tsx
  • Implement detail view with the following sections:
    • Organization information
    • KYB record status and history
    • Uploaded documents with preview
    • Notes and evidence
  • Add action buttons for approval, rejection, and requesting additional information
  • Implement document preview functionality
  • Add comment/notes section

KYB Status Monitoring

  • Create app/frontend/src/components/kyb/KybStatusMonitor.tsx
  • Implement status monitoring dashboard with the following features:
    • Overview of KYB verification statuses
    • Alerts for pending verifications
    • Statistics on verification times
    • Compliance metrics

Dependencies & Assumptions

Prerequisites

  • The Organization entity must be properly defined
  • The KybRecord entity must be properly defined
  • S3 or equivalent storage must be available for document storage
  • Email service must be available for notifications

Cross-team Needs

  • Frontend team needs to implement the UI components
  • DevOps team needs to configure S3 or equivalent storage
  • QA team needs to test the KYB verification workflow

Implementation Notes

  1. Security Considerations:
  2. All KYB documents must be encrypted at rest
  3. Access to KYB information must be restricted to authorized users

  4. All KYB verification actions must be logged for audit purposes

  5. Compliance Requirements:

  6. KYB verification must comply with relevant regulations
  7. Document retention policies must be implemented

  8. Audit trails must be maintained for all verification activities

  9. Performance Considerations:

  10. Document uploads should be optimized for large files
  11. Document previews should be generated asynchronously

  12. KYB record queries should be optimized for performance

  13. Testing Requirements:

  14. Unit tests should cover all service methods
  15. Integration tests should verify the complete verification workflow
  16. Security tests should verify access control restrictions