POC Architecture Diagram - REC Verifiable Credentialing Platform

High-Level Process Flow

flowchart TD
    Start([Organization Admin Login]) --> Upload[Upload Employee CSV]
    Upload --> Validate{Validate Data}
    Validate -->|Invalid| Error[Show Validation Errors]
    Error --> Upload
    Validate -->|Valid| Store[Store Employee Records]

    Store --> Queue[Queue Credential Creation]
    Queue --> Batch[Batch Process Records]
    Batch --> VNF[Generate VNF Credentials]
    VNF --> Success{Credential Created?}

    Success -->|No| Retry[Retry Logic]
    Retry --> VNF
    Success -->|Yes| Email[Send Email Notifications]

    Email --> Track[Track Email Status]
    Track --> Dashboard[Update Dashboard]
    Dashboard --> Monitor[Monitor Claim Status]

    Monitor --> Complete{All Processed?}
    Complete -->|No| Batch
    Complete -->|Yes| Report[Generate Reports]
    Report --> End([Process Complete])

    %% Parallel processes
    Dashboard --> Export[Export Data]
    Monitor --> Alerts[Send Alerts if Needed]

    %% Styling
    classDef startEnd fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
    classDef process fill:#2196f3,stroke:#1565c0,stroke-width:2px,color:#fff
    classDef decision fill:#ff9800,stroke:#ef6c00,stroke-width:2px,color:#fff
    classDef error fill:#f44336,stroke:#c62828,stroke-width:2px,color:#fff

    class Start,End startEnd
    class Upload,Store,Queue,Batch,VNF,Email,Track,Dashboard,Monitor,Report,Export,Alerts process
    class Validate,Success,Complete decision
    class Error,Retry error

User Journey Flow

journey
    title POC User Journey - Credential Issuance
    section Login & Setup
      Login to Platform: 5: Admin
      Navigate to Upload: 4: Admin
    section Data Upload
      Select CSV File: 4: Admin
      Preview Data: 5: Admin
      Validate Records: 3: Admin
      Fix Errors: 2: Admin
      Confirm Upload: 5: Admin
    section Processing
      Monitor Progress: 4: Admin
      View Status Updates: 5: Admin
    section Email Phase
      Review Email Template: 4: Admin
      Send Notifications: 5: Admin
      Track Delivery: 4: Admin
    section Monitoring
      Check Dashboard: 5: Admin
      View Claim Status: 4: Admin
      Export Reports: 3: Admin
    section Employee Experience
      Receive Email: 5: Employee
      Click Claim Link: 4: Employee
      Download Credential: 5: Employee

System Architecture Overview

graph TB
    %% External Systems
    subgraph "External Systems"
        VNF[Velocity Network Foundation]
        SMTP[SMTP Email Service]
        Auth0[Auth0 Authentication]
    end

    %% Frontend Layer
    subgraph "Frontend Layer (Next.js)"
        UI[User Interface]
        Upload[CSV Upload Component]
        Dashboard[Status Dashboard]
        EmailEditor[Email Template Editor]
        Auth[Authentication Pages]
    end

    %% Backend Layer
    subgraph "Backend Layer (NestJS)"
        API[API Gateway]

        subgraph "Controllers"
            UploadCtrl[Upload Controller]
            CredCtrl[Credential Controller]
            EmailCtrl[Email Controller]
            UserCtrl[User Controller]
        end

        subgraph "Services"
            UploadSvc[Upload Service]
            CredSvc[Credential Service]
            EmailSvc[Email Service]
            VNFSvc[VNF Integration Service]
        end

        subgraph "Background Jobs"
            BatchProcessor[Batch Processor]
            EmailQueue[Email Queue]
            StatusUpdater[Status Updater]
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB[(PostgreSQL Database)]
        FileStore[File Storage]
        Cache[Redis Cache]
    end

    %% Data Flow
    UI --> API
    Upload --> UploadCtrl
    Dashboard --> CredCtrl
    EmailEditor --> EmailCtrl
    Auth --> UserCtrl

    UploadCtrl --> UploadSvc
    CredCtrl --> CredSvc
    EmailCtrl --> EmailSvc
    UserCtrl --> Auth0

    UploadSvc --> FileStore
    UploadSvc --> BatchProcessor
    CredSvc --> VNFSvc
    EmailSvc --> EmailQueue

    VNFSvc --> VNF
    EmailQueue --> SMTP
    BatchProcessor --> DB
    StatusUpdater --> DB

    API --> Cache
    API --> DB

    %% Styling
    classDef external fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
    classDef frontend fill:#4caf50,stroke:#2e7d32,stroke-width:2px
    classDef backend fill:#2196f3,stroke:#1565c0,stroke-width:2px
    classDef data fill:#ff9800,stroke:#ef6c00,stroke-width:2px

    class VNF,SMTP,Auth0 external
    class UI,Upload,Dashboard,EmailEditor,Auth frontend
    class API,UploadCtrl,CredCtrl,EmailCtrl,UserCtrl,UploadSvc,CredSvc,EmailSvc,VNFSvc,BatchProcessor,EmailQueue,StatusUpdater backend
    class DB,FileStore,Cache data

Component Flow Diagram

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant UploadSvc
    participant BatchProcessor
    participant VNFSvc
    participant EmailSvc
    participant VNF
    participant SMTP
    participant DB

    User->>Frontend: Upload CSV file
    Frontend->>API: POST /upload/employees
    API->>UploadSvc: Process CSV
    UploadSvc->>DB: Store employee records
    UploadSvc->>BatchProcessor: Queue credential creation

    BatchProcessor->>VNFSvc: Create credentials batch
    VNFSvc->>VNF: Generate credentials
    VNF-->>VNFSvc: Return credential offers
    VNFSvc->>DB: Store credential offers

    BatchProcessor->>EmailSvc: Queue email notifications
    EmailSvc->>SMTP: Send credential emails
    SMTP-->>EmailSvc: Delivery confirmation
    EmailSvc->>DB: Update email status

    DB-->>Frontend: Real-time status updates
    Frontend-->>User: Display progress

Data Architecture

erDiagram
    ORGANIZATION ||--o{ USER : has
    ORGANIZATION ||--o{ CANDIDATE : manages
    CANDIDATE ||--o{ CREDENTIAL_OFFER : receives
    CREDENTIAL_OFFER ||--o{ EMAIL_LOG : tracks
    USER ||--o{ UPLOAD_SESSION : creates
    UPLOAD_SESSION ||--o{ CANDIDATE : contains

    ORGANIZATION {
        uuid id PK
        string name
        string did
        string vnf_org_id
        timestamp created_at
        timestamp updated_at
    }

    USER {
        uuid id PK
        uuid organization_id FK
        string email
        string name
        string auth0_id
        timestamp created_at
    }

    CANDIDATE {
        uuid id PK
        uuid organization_id FK
        uuid upload_session_id FK
        string first_name
        string last_name
        string email
        string phone
        json employment_details
        string status
        timestamp created_at
    }

    CREDENTIAL_OFFER {
        uuid id PK
        uuid candidate_id FK
        string vnf_offer_id
        string credential_type
        json credential_data
        string status
        string claim_url
        timestamp expires_at
        timestamp created_at
        timestamp claimed_at
    }

    EMAIL_LOG {
        uuid id PK
        uuid credential_offer_id FK
        string recipient_email
        string subject
        string template_used
        string status
        timestamp sent_at
        timestamp delivered_at
        timestamp opened_at
    }

    UPLOAD_SESSION {
        uuid id PK
        uuid user_id FK
        string filename
        integer total_records
        integer processed_records
        integer failed_records
        string status
        json error_log
        timestamp created_at
        timestamp completed_at
    }

Technology Stack

graph LR
    subgraph "Frontend Stack"
        NextJS[Next.js 14]
        React[React 18]
        Redux[Redux Toolkit]
        TailwindCSS[Tailwind CSS]
        TypeScript1[TypeScript]
    end

    subgraph "Backend Stack"
        NestJS[NestJS]
        TypeORM[TypeORM]
        TypeScript2[TypeScript]
        JWT[JWT/NextAuth]
        Bull[Bull Queue]
    end

    subgraph "Database & Storage"
        PostgreSQL[PostgreSQL]
        Redis[Redis]
        S3[File Storage]
    end

    subgraph "External Services"
        VNF_API[VNF Node.js SDK]
        Auth0_Service[Auth0]
        SMTP_Service[SMTP Provider]
    end

    NextJS --> NestJS
    NestJS --> PostgreSQL
    NestJS --> Redis
    NestJS --> VNF_API
    NextJS --> Auth0_Service
    NestJS --> SMTP_Service

Security Architecture

graph TB
    subgraph "Security Layers"
        subgraph "Authentication"
            Auth0_JWT[Auth0 JWT Tokens]
            Session[Session Management]
            MFA[Multi-Factor Auth]
        end

        subgraph "Authorization"
            RBAC[Role-Based Access]
            OrgScope[Organization Scoping]
            APIKeys[API Key Management]
        end

        subgraph "Data Protection"
            Encryption[Data Encryption]
            TLS[TLS/HTTPS]
            Validation[Input Validation]
        end

        subgraph "Monitoring"
            AuditLog[Audit Logging]
            RateLimit[Rate Limiting]
            Monitoring[Security Monitoring]
        end
    end

    Auth0_JWT --> RBAC
    Session --> OrgScope
    RBAC --> Encryption
    OrgScope --> TLS
    Encryption --> AuditLog
    TLS --> RateLimit

Deployment Architecture

graph TB
    subgraph "Production Environment"
        subgraph "Frontend Tier"
            CDN[CDN/Edge Cache]
            NextApp[Next.js Application]
        end

        subgraph "Backend Tier"
            LB[Load Balancer]
            API1[NestJS Instance 1]
            API2[NestJS Instance 2]
            Worker[Background Workers]
        end

        subgraph "Data Tier"
            PrimaryDB[(Primary PostgreSQL)]
            ReadReplica[(Read Replica)]
            RedisCluster[Redis Cluster]
        end

        subgraph "External Services"
            VNF_Prod[VNF Production API]
            Email_Prod[Production SMTP]
            Auth0_Prod[Auth0 Production]
        end
    end

    CDN --> NextApp
    NextApp --> LB
    LB --> API1
    LB --> API2
    API1 --> PrimaryDB
    API2 --> ReadReplica
    API1 --> RedisCluster
    API2 --> RedisCluster
    Worker --> PrimaryDB
    Worker --> VNF_Prod
    Worker --> Email_Prod
    NextApp --> Auth0_Prod

POC Implementation Phases

gantt
    title POC Implementation Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1: Setup
    Environment Setup           :done, setup, 2024-01-01, 3d
    VNF SDK Integration        :done, vnf, after setup, 4d

    section Phase 2: Core Features
    Employee Upload Module     :active, upload, 2024-01-08, 7d
    Data Validation           :validation, after upload, 3d

    section Phase 3: Credentials
    Credential Creation Engine :cred, after validation, 7d
    Batch Processing          :batch, after cred, 4d

    section Phase 4: Notifications
    Email System              :email, after batch, 5d
    Template Configuration    :template, after email, 3d

    section Phase 5: Dashboard
    Status Dashboard          :dashboard, after template, 5d
    Export Functionality      :export, after dashboard, 3d

    section Phase 6: Testing
    Integration Testing       :testing, after export, 5d
    Performance Validation    :perf, after testing, 3d
    Documentation            :docs, after perf, 2d

Key Integration Points

1. Velocity Network Foundation (VNF)

• Purpose: Credential creation and management
• Integration: Node.js SDK
• Endpoints: Agent Operator API, Registrar API
• Authentication: API Key + Organization DID

2. Auth0 Authentication

• Purpose: User authentication and authorization
• Integration: NextAuth.js provider
• Features: SSO, MFA, Organization scoping
• Token Management: JWT with refresh tokens

3. Email Service Integration

• Purpose: Credential offer notifications
• Integration: SMTP provider (SendGrid/AWS SES)
• Features: Template management, delivery tracking
• Compliance: CAN-SPAM, GDPR compliance

4. File Processing

• Purpose: CSV upload and validation
• Integration: Multer + CSV parser
• Features: Batch processing, error handling
• Storage: Temporary file storage with cleanup

Performance Considerations

• Batch Processing: Handle 500+ records in 5-minute batches
• Rate Limiting: Respect VNF API limits with retry logic
• Caching: Redis for session data and frequent queries
• Database Optimization: Indexed queries for status tracking
• Background Jobs: Queue-based processing for scalability

Monitoring & Observability

• Application Metrics: Response times, error rates
• Business Metrics: Credential creation success rates
• Infrastructure Metrics: Database performance, queue depths
• Security Metrics: Authentication failures, suspicious activity
• User Experience: Upload success rates, email delivery rates

---

This architecture supports the POC requirements while providing a foundation for future scaling and feature expansion.