Skip to content

REC Verifiable Credentialing Platform Architecture

1. Project Overview

The REC Verifiable Credentialing Platform is a cloud-based solution designed to enable UK staffing companies and work-seeking individuals to securely create, issue, receive, and verify workforce credentials across web and mobile services. The platform integrates with Velocity Network Foundation (VNF) services and initially focuses on registering past work records as part of the MVP.

Key Features

  • Secure credential issuance and verification
  • Integration with Velocity Credential Agent
  • Multi-factor authentication with passkey support
  • Payment processing capabilities
  • Comprehensive audit logging
  • Data export in standard formats (CSV, JSON)
  • Scalable architecture supporting 1000+ concurrent users

2. Tech Stack

The REC Verifiable Credentialing Platform is built using a modern, maintainable tech stack that prioritizes code readability, usability, and scalability.

Backend

Technology Purpose Justification
Node.js with TypeScript Server runtime and language Strong typing enhances code readability and maintainability
NestJS Backend framework Enterprise-ready framework with modular architecture and dependency injection
PostgreSQL Primary database Robust, enterprise-grade relational database with JSON support
Redis Caching High-performance caching for improved response times
Auth0 Authentication & authorization Comprehensive identity platform supporting OAuth 2.0/OIDC, MFA, and passkeys
Passport.js Authentication middleware Flexible authentication integration with multiple strategies
Swagger/OpenAPI API documentation Automated, interactive API documentation

Frontend

Technology Purpose Justification
React with TypeScript UI framework Component-based architecture with type safety
Redux Toolkit State management Simplified Redux implementation with less boilerplate
Material-UI/Tailwind CSS UI component library Comprehensive, accessible UI components
Auth0 React SDK Authentication integration Seamless Auth0 integration for React applications

DevOps & Infrastructure

Technology Purpose Justification
AWS Cloud provider Comprehensive cloud services with global reach
GitHub Actions CI/CD pipeline Automated testing and deployment
AWS CloudWatch Monitoring & logging Application performance monitoring and log aggregation
AWS WAF Security DDoS protection and web application firewall
Terraform/CloudFormation Infrastructure as code Consistent, repeatable infrastructure deployment

3. Folder Structure

rec-credentialing-platform/
├── package.json                 # Root package.json for shared dependencies and scripts
├── tsconfig.json                # Base TypeScript configuration
├── .eslintrc.js                 # ESLint configuration
├── .prettierrc                  # Prettier configuration
├── backend/                     # Backend NestJS code
│   ├── package.json             # Backend-specific dependencies
│   ├── tsconfig.json            # Backend-specific TypeScript config
│   ├── src/                     # NestJS source code
│   │   ├── main.ts              # NestJS entry point
│   │   ├── app.module.ts        # Root module
│   │   ├── auth/                # Authentication module
│   │   ├── issuer/              # Credential issuing module
│   │   ├── verification/        # Credential verification module
│   │   ├── users/               # User management module
│   │   ├── admin/               # Admin functionality module
│   │   ├── payment/             # Payment processing module
│   │   └── shared/              # Shared utilities and interfaces
│   └── dist/                    # Compiled backend code
├── frontend/                    # Frontend React code
│   ├── package.json             # Frontend-specific dependencies
│   ├── tsconfig.json            # Frontend-specific TypeScript config
│   ├── public/                  # Static assets
│   ├── src/                     # React source code
│   │   ├── index.tsx            # React entry point
│   │   ├── App.tsx              # Root component
│   │   ├── components/          # Reusable components
│   │   ├── pages/               # Page components
│   │   ├── services/            # API services
│   │   ├── store/               # Redux store
│   │   └── utils/               # Utility functions
│   └── build/                   # Built frontend (deployed to S3)
├── shared/                      # Code shared between frontend and backend
│   ├── types/                   # Shared TypeScript interfaces
│   └── utils/                   # Shared utility functions
├── infrastructure/              # Infrastructure as Code
│   ├── terraform/               # Terraform configurations
│   └── scripts/                 # Deployment scripts
├── docs/                        # Project documentation
│   └── techstack/               # Technical documentation
│       ├── architecture.md      # This architecture document
│       └── auth0_implementation_plan.md # Auth0 implementation details
└── node_modules/                # Dependencies

Key Components

  • backend/: Contains all NestJS server-side code organized by domain modules
  • frontend/: Contains all React client-side code with component-based organization
  • shared/: Contains types and utilities shared between frontend and backend
  • infrastructure/: Contains infrastructure as code and deployment scripts
  • docs/: Contains project documentation and technical specifications

4. System Architecture

The REC Verifiable Credentialing Platform uses a microservices-inspired architecture within a monorepo structure. While the codebase is maintained in a single repository for development benefits, the deployment strategy separates frontend and backend components for optimal performance and scalability.

High-Level Architecture Diagram

flowchart TB
    subgraph "Client Layer"
        WebBrowser["Web Browser"]
        MobileApp["Mobile App"]
        AdminDashboard["Admin Dashboard"]
    end

    subgraph "Auth0 Tenant"
        Auth0["Auth0 Authentication"]
        Auth0Rules["Auth0 Rules & Actions"]
        Auth0MFA["Multi-factor Authentication"]
        Auth0Logs["Audit Logs"]
    end

    subgraph "Frontend Infrastructure"
        S3FE["S3 Bucket (React Build)"]
        CF["CloudFront CDN"]
        S3FE --> CF
    end

    subgraph "Backend Infrastructure"
        ECS["ECS/Elastic Beanstalk (NestJS)"]
        ALB["Application Load Balancer"]
        ALB --> ECS
    end

    subgraph "NestJS Application"
        subgraph "API Layer"
            APIController["API Controllers"]
            AuthGuard["Auth Guards"]
        end

        subgraph "Application Services Layer"
            AuthService["Authentication Service"]
            IssuerService["Credential Issuer Service"]
            VerificationService["Credential Verification Service"]
            UserService["User Management Service"]
            AdminService["Admin Service"]
            PaymentService["Payment Processing Service"]
        end

        subgraph "Integration Layer"
            VCAIntegration["Velocity Credential Agent Integration"]
            PDFIntegration["VCL PDF Generation Service Integration"]
            EmailService["Email Service"]
        end
    end

    subgraph "Data Storage Layer"
        PostgreSQL[(PostgreSQL Database)]
        Redis[(Redis Cache)]
        S3[(S3 File Storage)]
    end

    subgraph "External Services"
        VCA["Velocity Credential Agent"]
        PDFService["VCL PDF Generation Service"]
        VelocityNetwork["Velocity Network"]
    end

    subgraph "DevOps & Monitoring"
        CloudWatch["AWS CloudWatch"]
        WAF["AWS WAF"]
    end

    %% Client to Frontend connections
    WebBrowser --> CF
    MobileApp --> CF
    AdminDashboard --> CF

    %% Client to Auth0 connections
    WebBrowser --> Auth0
    MobileApp --> Auth0
    AdminDashboard --> Auth0

    %% Auth0 to Backend connections
    Auth0 --> AuthGuard

    %% Client to Backend connections
    WebBrowser --> ALB
    MobileApp --> ALB
    AdminDashboard --> ALB

    %% API Guards to Services
    AuthGuard --> APIController
    APIController --> AuthService
    APIController --> IssuerService
    APIController --> VerificationService
    APIController --> UserService
    APIController --> AdminService
    APIController --> PaymentService

    %% Services to Integration Layer
    IssuerService --> VCAIntegration
    VerificationService --> VCAIntegration
    IssuerService --> PDFIntegration
    VerificationService --> PDFIntegration
    AuthService --> EmailService
    IssuerService --> EmailService
    VerificationService --> EmailService

    %% Integration Layer to External Services
    VCAIntegration --> VCA
    PDFIntegration --> PDFService
    VCA --> VelocityNetwork

    %% Services to Data Storage
    AuthService --> PostgreSQL
    IssuerService --> PostgreSQL
    VerificationService --> PostgreSQL
    UserService --> PostgreSQL
    AdminService --> PostgreSQL
    PaymentService --> PostgreSQL

    AuthService --> Redis
    IssuerService --> Redis
    VerificationService --> Redis

    IssuerService --> S3
    VerificationService --> S3

    %% DevOps & Monitoring
    CloudWatch -.- ECS
    WAF -.- ALB

Component Interaction Flow

sequenceDiagram
    participant SC as Staffing Company
    participant UI as React Frontend
    participant Auth0 as Auth0
    participant API as NestJS API
    participant IS as Issuer Service
    participant VS as Verification Service
    participant VCA as Velocity Credential Agent
    participant PDF as PDF Generation Service
    participant DB as Database
    participant C as Candidate

    %% Authentication Flow
    SC->>UI: Access Application
    UI->>Auth0: Redirect to Auth0 Login
    Auth0->>SC: Present Login UI
    SC->>Auth0: Enter Credentials
    Auth0->>Auth0: Validate Credentials
    Auth0->>UI: Return Access & ID Tokens

    %% Credential Issuance Flow
    SC->>UI: Enter Credential Data
    UI->>API: Submit Credential Data (with token)
    API->>API: Validate Token
    API->>IS: Process Credential Request
    IS->>DB: Store Credential Request
    IS->>VCA: Request Credential Issuance
    VCA-->>IS: Credential Created
    IS->>DB: Update Credential Status
    IS->>UI: Return Success
    UI->>SC: Display Success & Email Sent
    IS->>C: Send Email with Credential Offer

    %% Credential Verification Flow
    SC->>UI: Access Verification Portal
    SC->>UI: Request Credential Disclosure
    UI->>API: Submit Disclosure Request (with token)
    API->>API: Validate Token
    API->>VS: Process Disclosure Request
    VS->>DB: Store Disclosure Request
    VS->>C: Send Disclosure Request Email
    C-->>VCA: Share Credentials
    VCA-->>VS: Receive Shared Credentials
    VS->>VCA: Verify Credentials
    VCA-->>VS: Verification Result
    VS->>DB: Store Verification Result
    VS->>PDF: Generate Verification Report
    PDF-->>VS: PDF Report
    VS->>UI: Return Verification Result & PDF
    UI->>SC: Display Verification Result

5. Standards & Conventions

Coding Conventions

  • TypeScript: Use strict mode with comprehensive type definitions
  • Naming: Use camelCase for variables and functions, PascalCase for classes and interfaces
  • File Structure: One class per file, named after the class
  • Comments: JSDoc style comments for public APIs
  • Testing: Unit tests for all business logic, integration tests for API endpoints

API Standards

  • RESTful Design: Follow REST principles for API design
  • Versioning: API versioning in URL path (e.g., /api/v1/resources)
  • Response Format: Consistent JSON response format with status, data, and error fields
  • Status Codes: Appropriate HTTP status codes for different scenarios
  • Documentation: OpenAPI/Swagger documentation for all endpoints

Authentication Standards

  • OAuth 2.0/OpenID Connect: Industry-standard authentication protocols
  • JWT Tokens: Signed JWTs for API authentication
  • Role-Based Access Control: Clearly defined roles and permissions
  • Multi-factor Authentication: Required for admin accounts

Logging & Error Handling

  • Structured Logging: JSON-formatted logs with consistent fields
  • Log Levels: Appropriate log levels (debug, info, warn, error)
  • Error Handling: Centralized error handling with appropriate error responses
  • Audit Logging: Immutable audit logs for security-relevant events

Testing Strategies

  • Unit Testing: Jest for unit tests
  • Integration Testing: Supertest for API testing
  • End-to-End Testing: Cypress for frontend testing
  • Test Coverage: Minimum 80% code coverage
  • Automated Testing: Tests run on every pull request and before deployment

6. DevOps & Deployment

CI/CD Pipeline

The platform uses GitHub Actions for continuous integration and deployment:

flowchart LR
    subgraph "CI/CD Pipeline"
        Checkout["Checkout Code"] --> Install["Install Dependencies"]
        Install --> LintTest["Lint & Test"]

        subgraph "Frontend Pipeline"
            LintTest --> BuildFE["Build Frontend"]
            BuildFE --> DeployFE["Deploy to S3"]
            DeployFE --> InvalidateCache["Invalidate CloudFront Cache"]
        end

        subgraph "Backend Pipeline"
            LintTest --> BuildBE["Build Backend"]
            BuildBE --> PackageBE["Package Backend"]
            PackageBE --> DeployBE["Deploy to ECS/Elastic Beanstalk"]
        end
    end

Environments

  • Development: For active development work
  • Staging: Mirrors production for testing before deployment
  • Production: Live environment for end users

Each environment has its own: - Separate AWS resources - Environment-specific configuration - Data isolation

Infrastructure as Code

All infrastructure is defined using Terraform or AWS CloudFormation:

  • VPC and Networking: Secure network configuration
  • ECS/Elastic Beanstalk: For backend hosting
  • S3 and CloudFront: For frontend hosting
  • RDS: For PostgreSQL database
  • ElastiCache: For Redis caching
  • IAM Roles and Policies: Least privilege access

Deployment Strategy

The platform uses a blue-green deployment strategy:

  1. New version is deployed to a new environment (green)
  2. Tests are run against the green environment
  3. Traffic is gradually shifted from old (blue) to new (green)
  4. If issues are detected, traffic is shifted back to blue
  5. Once green is stable, blue is decommissioned

7. Security & Observability

Security Best Practices

  • Zero Trust Architecture: No implicit trust, verify everything
  • Encryption: Data encrypted at rest and in transit
  • Authentication: Multi-factor authentication with Auth0
  • Authorization: Role-based access control
  • Secrets Management: AWS Secrets Manager for sensitive configuration
  • Vulnerability Scanning: Regular security scans
  • Penetration Testing: Periodic penetration testing

Logging & Monitoring

  • Application Logs: Structured logs sent to CloudWatch
  • Metrics: Custom metrics for application performance
  • Alerting: Alerts for critical issues
  • Dashboards: CloudWatch dashboards for system overview

Tracing & Observability

  • Distributed Tracing: AWS X-Ray for request tracing
  • Performance Monitoring: Custom metrics for key operations
  • Error Tracking: Centralized error tracking and alerting
  • User Analytics: Anonymous usage analytics for feature optimization

8. Integration Points

Velocity Credential Agent

The platform integrates with the Velocity Credential Agent for: - Credential issuance - Credential verification - Interaction with the Velocity Network

VCL PDF Generation Service

Integration with the VCL PDF Generation Service for: - Generating verification reports - Creating credential documentation

Auth0 Integration

Detailed Auth0 integration is documented in auth0_implementation_plan.md, covering: - Authentication flows - Multi-factor authentication - Passkey implementation - Role-based access control

9. Scalability & Performance

Scalability Approach

  • Horizontal Scaling: Add more instances as load increases
  • Auto-scaling: Automatically adjust capacity based on demand
  • Database Scaling: Read replicas for database scaling
  • Caching Strategy: Redis caching for frequently accessed data

Performance Optimization

  • CDN: CloudFront for static asset delivery
  • Compression: GZIP/Brotli compression for API responses
  • Lazy Loading: Lazy loading of frontend components
  • Query Optimization: Optimized database queries with proper indexing
  • Connection Pooling: Database connection pooling

10. Future Considerations

  • Mobile App: Native mobile application development
  • Blockchain Integration: Deeper integration with blockchain technologies
  • AI/ML Features: Potential for AI-powered credential verification
  • Internationalization: Support for multiple languages
  • Advanced Analytics: Enhanced analytics and reporting capabilities

Conclusion

The REC Verifiable Credentialing Platform architecture provides a robust, scalable, and secure foundation for credential issuance and verification. The chosen technologies and architectural patterns ensure the platform can meet current requirements while remaining flexible for future enhancements.