Phase 1: Organization Foundation - POC Task

🎯 VNF SDK Reference Implementation

PRIMARY REFERENCE: vnf-wallet-sdk-nodejs-main/

All Phase 1 tasks MUST follow the official VNF SDK sample application patterns

Key Reference Files: - Organization Search: packages/sample-server/src/routes/Other.ts - Organization discovery patterns - DID Generation: packages/sample-server/src/routes/CryptoServices.ts:41 - generateDidJwk implementation - SDK Initialization: packages/sample-server/src/plugins/VclSdkPlugin.ts - Organization-level SDK setup - Environment Config: packages/sample-server/src/GlobalConfig.ts - Environment management - Organization Entity: packages/sdk/src/api/entities/VCLOrganization.ts - Organization structure

Overview

CRITICAL FIRST PHASE: Implement organization creation, KYB (Know Your Business) management, and issuer enablement workflow as required by Velocity Network Foundation architecture using official VNF SDK patterns.

Velocity Architecture Alignment

This phase implements the mandatory foundation described in the Velocity Phase Explanations with VNF SDK integration: - SuperAdmin creates Organization with VNF DID generation - KYB submission and verification with VNF tenant registration - Organization activation for credential issuance using VNF SDK - Company Admin user management setup with VNF organization context

Backend Tasks

1. Organization State Management

• Task: Implement organization lifecycle states
• Update organization.entity.ts
• Add organization status enum:

  enum OrganizationStatus {
    DRAFT = 'draft',                    // Org created, not started onboarding
    KYB_PENDING = 'kyb_pending',        // KYB submitted
    KYB_APPROVED = 'kyb_approved',      // Velocity approved
    ISSUER_ENABLED = 'issuer_enabled',  // Platform allows issuance
    SUSPENDED = 'suspended'             // Stop issuance
  }
  

• Add state transition validation logic
• Implement audit trail for status changes

2. SuperAdmin Organization Management

• Task: Create SuperAdmin organization management interface
• Create superadmin-org.controller.ts
• Implement endpoints:
  • POST /api/v1/superadmin/organizations - Create organization
  • PUT /api/v1/superadmin/organizations/{id}/kyb-status - Update KYB status
  • PUT /api/v1/superadmin/organizations/{id}/enable-issuer - Enable issuer capabilities
  • GET /api/v1/superadmin/organizations - List all organizations
• Add organization configuration management

3. KYB Management Service

• Task: Implement KYB workflow management
• Create kyb-management.service.ts
• Add KYB submission tracking
• Implement KYB document management
• Add KYB status validation workflow
• Create KYB approval/rejection logic

4. Company Admin User Management

• Task: Enable Company Admin to create organization users
• Update organization.service.ts
• Add user role management:
  • Issuer Admin / Issuer Operator
  • HR Admin
  • Employee users (optional)
  • Relying Partners (optional for POC)
• Implement organization-scoped user creation
• Add role-based permission validation

5. Issuer Capability Management

• Task: Control credential issuance based on organization status
• Create issuer-capability.guard.ts
• Add organization status validation before credential operations
• Implement "ISSUER_ENABLED" requirement for all credential endpoints
• Add capability suspension/restoration logic

Frontend Tasks

1. SuperAdmin Dashboard

• Task: Create SuperAdmin organization management interface
• Create SuperAdminDashboard.tsx
• Display all organizations with status indicators
• Add organization creation form
• Implement KYB status management controls
• Add issuer enablement toggle

2. Organization Creation Wizard

• Task: Step-by-step organization setup
• Create OrganizationWizard.tsx
• Step 1: Basic organization information
• Step 2: KYB document upload
• Step 3: Velocity Network configuration
• Step 4: Initial admin user setup

3. KYB Management Interface

• Task: KYB submission and tracking
• Create KYBManagement.tsx
• KYB document upload interface
• KYB status tracking dashboard
• KYB approval/rejection workflow
• Document verification checklist

4. Company Admin User Management

• Task: Organization user management for Company Admins
• Create OrgUserManagement.tsx
• User creation form with role selection
• User list with role indicators
• User permission management
• Invitation email system

5. Organization Status Guard

• Task: Prevent credential operations for non-enabled organizations
• Create OrganizationStatusGuard.tsx
• Check organization status before showing credential features
• Display appropriate messages for each status
• Redirect to setup steps if organization not ready

Workflow Implementation

SuperAdmin Workflow

flowchart TD
    A[SuperAdmin Login] --> B[Create Organization]
    B --> C[Organization Status: DRAFT]
    C --> D[Start KYB Process]
    D --> E[Organization Status: KYB_PENDING]
    E --> F{KYB Approved?}
    F -->|Yes| G[Organization Status: KYB_APPROVED]
    F -->|No| H[Fix KYB Issues]
    H --> D
    G --> I[Enable Issuer Capabilities]
    I --> J[Organization Status: ISSUER_ENABLED]
    J --> K[Notify Company Admin]

Company Admin Workflow

flowchart TD
    A[Company Admin Login] --> B{Organization Status}
    B -->|ISSUER_ENABLED| C[Access Credential Features]
    B -->|Other Status| D[Show Setup Required Message]
    C --> E[Create Organization Users]
    E --> F[Upload Employee CSV]
    F --> G[Issue Credentials]

API Endpoints

SuperAdmin Endpoints

POST /api/v1/superadmin/organizations
GET /api/v1/superadmin/organizations
PUT /api/v1/superadmin/organizations/{id}
PUT /api/v1/superadmin/organizations/{id}/kyb-status
PUT /api/v1/superadmin/organizations/{id}/enable-issuer
PUT /api/v1/superadmin/organizations/{id}/suspend

Company Admin Endpoints

GET /api/v1/admin/organization/status
POST /api/v1/admin/organization/users
GET /api/v1/admin/organization/users
PUT /api/v1/admin/organization/users/{id}
DELETE /api/v1/admin/organization/users/{id}

Database Schema Updates

Organization Status Tracking

ALTER TABLE organizations 
ADD COLUMN status VARCHAR(20) DEFAULT 'draft',
ADD COLUMN kyb_submitted_at TIMESTAMP,
ADD COLUMN kyb_approved_at TIMESTAMP,
ADD COLUMN issuer_enabled_at TIMESTAMP,
ADD COLUMN status_updated_by UUID REFERENCES users(id);

KYB Document Management

CREATE TABLE kyb_documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    organization_id UUID REFERENCES organizations(id),
    document_type VARCHAR(50) NOT NULL,
    file_path VARCHAR(255) NOT NULL,
    status VARCHAR(20) DEFAULT 'pending',
    uploaded_at TIMESTAMP DEFAULT NOW(),
    reviewed_at TIMESTAMP,
    reviewed_by UUID REFERENCES users(id)
);

Dependencies & Prerequisites

Critical Requirements

• SuperAdmin role must be implemented in Auth0
• Organization status validation must be enforced on all credential endpoints
• KYB document storage system must be configured
• Email notification system for status changes

Velocity Network Dependencies

• Organization DID registration process
• KYB verification requirements from VNF
• Issuer capability activation process

Acceptance Criteria

Phase 1 Foundation Requirements

• SuperAdmin can create organizations with DRAFT status
• KYB submission workflow updates status to KYB_PENDING
• SuperAdmin can approve KYB and update to KYB_APPROVED
• SuperAdmin can enable issuer capabilities (ISSUER_ENABLED)
• Company Admin can only access credential features when ISSUER_ENABLED
• Company Admin can create organization users with proper roles
• All credential operations are blocked for non-enabled organizations
• Audit trail tracks all organization status changes

Security Requirements

• Organization data isolation enforced
• Role-based access control implemented
• KYB document security and encryption
• Status change authorization validation

Estimated Timeline

Week 1-2: 10 days (CRITICAL FOUNDATION) - Day 1-2: Organization status management and database updates - Day 3-4: SuperAdmin organization management - Day 5-6: KYB workflow implementation - Day 7-8: Company Admin user management - Day 9-10: Frontend interfaces and testing

Blockers & Risks

• CRITICAL: This phase MUST be completed before any credential issuance
• Blocker: SuperAdmin role configuration in Auth0
• Risk: KYB document storage and security requirements
• Dependency: Velocity Network organization registration process

---

⚠️ IMPORTANT: This is the mandatory foundation phase required by Velocity Network architecture. No credential issuance can occur without completing this phase first.