Skip to content

Task 14: POC Readiness Audit

Overview

Comprehensive audit mapping every POC requirement to backend APIs, frontend components, and Velocity integration — identifying what's ready, what needs wiring, and what's missing.

Audit Date: 2026-04-15 Backend endpoints counted: 111 total across 15 controllers Question answered: Do we have all backend APIs? Is requirement clarity sufficient?

Executive Summary

Backend API Coverage: ✅ COMPLETE

111 backend endpoints covering all POC flows. No new backend endpoints need to be built for the POC. The work remaining is wiring these existing endpoints to real Velocity CIH API calls (replacing mock logic).

Requirement Clarity: ✅ SUFFICIENT

All POC requirements from v3.0 doc are documented, mapped to implementation, and unambiguous. Two minor clarification items listed at the end.

Readiness for POC Demo

  • Backend APIs: Ready (all 111 endpoints exist)
  • Database schema: Ready (only 2 new columns to add)
  • Frontend pages: Ready (13 pages built)
  • Velocity integration: CIH API verified working, backend code needs wiring
  • Blockers: None remaining

Part 1: Do We Have All Backend APIs?

Verdict: YES — All required backend APIs exist.

Mapping: POC Requirements → Backend Endpoints

Phase 1 — Organization Setup

POC Requirement Backend Endpoint Status
SuperAdmin login POST /auth/login, /auth/callback ✅ Ready
Create Organization POST /superadmin/organizations ✅ Ready
List Organizations (SuperAdmin) GET /superadmin/organizations ✅ Ready
Get Organization details GET /superadmin/organizations/:id ✅ Ready
Submit KYB POST /admin/kyb ✅ Ready
Approve KYB PUT /admin/kyb/:id/approve or PUT /superadmin/organizations/:id/kyb-status ✅ Ready
Reject KYB PUT /admin/kyb/:id/reject ✅ Ready
Create Velocity Tenant POST /superadmin/organizations/:id/tenant ⚠️ Exists but wired to mock
Retry Tenant Creation POST /superadmin/organizations/:id/tenant/retry ⚠️ Exists but wired to mock
Get Tenant Status GET /superadmin/organizations/:id/tenant ✅ Ready
Enable Issuer PUT /superadmin/organizations/:id/enable-issuer ✅ Ready
Create Company Admin POST /superadmin/organizations/:id/admin ✅ Ready
Suspend Organization PUT /superadmin/organizations/:id/suspend ✅ Ready
Reactivate Organization PUT /superadmin/organizations/:id/reactivate ✅ Ready

Phase 2 — Credential Issuance

POC Requirement Backend Endpoint Status
Org Admin login POST /auth/login with org context ✅ Ready
Create employee POST /issuer/employees ✅ Ready
CSV bulk import POST /issuer/employees/bulk ✅ Ready
Search employees GET /issuer/employees/search ✅ Ready
Get employee statistics GET /issuer/employees/stats ✅ Ready
Preview credential POST /issuer/manual-credentials/preview ✅ Ready
Create manual credential POST /issuer/manual-credentials ⚠️ Exists but wired to mock
Get credential types GET /issuer/manual-credentials/credential-types ✅ Ready
Get available types for employee GET /issuer/manual-credentials/employees/:employeeId/available-types ✅ Ready
Get VNF credential types GET /credential-types ⚠️ Uses mock data
Create credential templates POST /issuer/credential-templates ✅ Ready
Manage email templates /admin/email-templates/* (8 endpoints) ✅ Ready
List credentials GET /issuer/credentials ✅ Ready
Get credential stats GET /issuer/credentials/stats ✅ Ready
Revoke credential PATCH /issuer/credentials/:id/revoke ⚠️ Exists but wired to mock
Resend credential POST /issuer/credentials/:id/resend ✅ Ready

Phase 3 — Claim & Tracking

POC Requirement Backend Endpoint Status
Public claim page GET /api/claim/:token ✅ Ready
Verify claim token POST /api/claim/:token/verify ✅ Ready
Claim credential POST /api/claim/:token/claim ✅ Ready
Get claim status GET /api/claim/:token/status ✅ Ready
Get credential manifest (for wallet) GET /api/claim/manifest/:credentialOfferId ⚠️ Returns mock manifest
Handle VNF webhook POST /api/claim/webhook/vnf ✅ Ready
Email open tracking GET /email/track/open/:emailId.png ✅ Ready
Email click tracking GET /email/track/click/:emailId ✅ Ready
Email delivery webhook POST /email/track/webhook/delivery ✅ Ready
Email bounce webhook POST /email/track/webhook/bounce ✅ Ready

Supporting APIs

POC Requirement Backend Endpoint Status
User management /users/* (6 endpoints) ✅ Ready
Company admin user mgmt /admin/company-admin/users/* (7 endpoints) ✅ Ready
Organization profile /admin/organizations/* (8 endpoints) ✅ Ready
Search VNF orgs GET /admin/organizations/vnf/search ⚠️ Uses mock
Session management /auth/sessions/* (4 endpoints) ✅ Ready
KYB workflow /admin/kyb/* (10 endpoints) ✅ Ready
Health check GET /health ✅ Ready

Backend API Status Legend

Symbol Meaning
✅ Ready Endpoint exists and works end-to-end
⚠️ Exists but wired to mock Endpoint exists, returns mock data. Needs to call real CIH API (Task 09)

What's Mock vs Real

Mock data sources (need replacement in Task 09): 1. velocity-registrar.service.ts — createTenant() returns mock tenant 2. vnf-sdk.service.ts — MockVCLProvider returns fake credentials 3. vnf-sdk-test.controller.ts — test endpoints use mocks 4. Credential issuance flow — creates DB records but no real VNF calls

All other endpoints (99 of 111) are already production-ready.

Part 2: Do We Have Enough Requirements Clarity?

Verdict: YES — Requirements are clear and fully documented.

Requirements Documentation Chain

v3.0 Requirements PDF
      ↓
Task 00: Phase 1 Organization Foundation (detailed)
Task 02-07: Phase 2 & 3 task breakdowns
Task 08: Organization form redesign
      ↓
Task 09: Staging Integration (HOW to wire to real VNF)
Task 10: Gap Analysis v3 (what's POC vs post-POC)
Task 11: Consolidated API Reference (all VNF endpoints)
Task 12: POC Application Flow (15-step end-to-end)
Task 13: Verified Integration Log (actual confirmed APIs)
      ↓
THIS DOCUMENT: Readiness audit

POC Scope is Clear

From Task 10 - Gap Analysis: - POC = 2 remaining items: Task 09 (wire Velocity APIs) + GAP-01 (QR code) - Drop 1 Beta: 6 additional features (branding, CSV export, etc.) - Drop 2: 5 features (disclosure, verification, PDF reports) - Post-MVP: 6 features (payments, GDPR, passkeys, etc.)

User Stories are Clear

From v3.0 PDF, we have full user stories for: - Platform Admin (7 stories) - Staffing Company Admin (6 stories) - Staffing Company User (11 stories) - Worker/Employee (2 stories) - Other (8 cross-cutting stories)

Credential Specification is Clear

EmploymentPastV1.1 is the primary (and only MVP) credential type: - Employee field → CredentialSubject mapping documented (Task 11) - Schema URL: https://stagingregistrar.velocitynetwork.foundation/schemas/employment-past-v1.1.schema.json - Required fields identified (company, title, dates, location)

Architecture is Clear

From Architecture Diagram: - 3-tier architecture (Next.js → NestJS → PostgreSQL) - Integration points with Velocity CIH - Email flow via SMTP + tracking - Public claim page (no login) + authenticated dashboard

Part 3: What's Actually Left for POC?

Work Remaining (Precise List)

Backend (2-3 days)

  1. Environment setup (30 min)
  2. Add confirmed env vars to .env
  3. Copy keys.json to config/velocity-keys.json

  4. Update .gitignore

  5. Configuration module (1 hour)

  6. Create velocity-staging.config.ts

  7. Load keys from file

  8. Database migration (30 min)

  9. Add credential_manifest_id and deep_link_url columns

  10. Replace mock in velocity-registrar.service.ts (2 hours)

  11. Remove isPocMode logic
  12. Wire to POST /operator/tenants/create with Bearer auth

  13. Use live tenant ID 69df3e9a1788f7af31e8edb1 in env config

  14. Create new cih-api.service.ts (3 hours)

  15. HTTP client with CIH Bearer token

  16. Methods: createTenant, createCredential, createManyCredentials, refreshIssueLinks, revokeCredential

  17. Replace MockVCLProvider (2 hours)

  18. Delete mock class

  19. Delegate to cih-api.service.ts

  20. Wire manual-credential.service.ts + credential.service.ts (3 hours)

  21. Call createCredential/createManyCredentials on CIH
  22. Store returned credentialId and deepLinkUrl
  23. Update status through flow

Frontend (2-3 hours)

  1. QR code on claim page (GAP-01, 1-2 hours)
  2. Generate QR from deepLinkUrl

  3. Display on /claim/[token] page

  4. Show real DID/status (30 min)

  5. Display real tenant ID on SuperAdmin org detail
  6. Copy-to-clipboard button for DID

Total Effort Estimate

Area Time
Backend wiring 12-15 hours
Frontend tweaks 2-3 hours
End-to-end testing 2-3 hours
Documentation updates 1 hour
Total ~2-3 working days

Part 4: Clarifications Worth Confirming (Low Risk)

These are minor questions that won't block POC, but worth clarifying before demo:

Q1: Identification Credentials for Holders

The SDK sample app requires Email/Phone verifiable credentials for holder identification. However, the CIH API (/operator/issuer-services/create) supports preauth auth mode which doesn't require identification VCs.

Current assumption: Use preauth mode for POC to simplify. Action: Confirm during first test issuance that preauth works without requiring holder to present existing VCs.

Q2: Webhook vs Polling for Claim Status

Two approaches for knowing when a credential is claimed: - Polling: Backend calls GET /operator/credentials/get periodically - Webhook: Configure tenant.webhookUrl to receive callbacks

Current assumption: Use polling for POC (no public URL needed). Action: Consider adding webhook support post-POC when we have a production URL.

Q3: Service Endpoint URL

Currently set to placeholder https://curo-rec.test/api/v1/velocity.

Impact: None for POC (we don't receive webhooks yet). Action: Update to real domain after first production deployment.

Part 5: Risk Assessment

Technical Risks (All LOW)

Risk Likelihood Impact Mitigation
CIH API behavior differs from spec Low Low Swagger spec is live, verified working
Tenant already exists error on re-create Certain None Don't recreate — use existing tenant ID from env
Bearer token expires Unknown High if happens Ask CTO about token lifetime
Credential fails validation Low Medium Use Registrar API to validate against schema before submission
Employee wallet doesn't exist yet Certain for POC demo Medium Use Velocity test wallet; document setup for demo

Business Risks (NOT IN POC — Per Senthil)

Do not track or share progress externally until contract is signed. All status communication stays internal.

Part 6: Final Answers

"Do we have all backend APIs?"

YES. All 111 backend endpoints exist. The POC doesn't require new backend endpoints to be built. What's remaining is replacing mock logic inside 4 service files with real CIH API calls.

"Do we have enough clarity on requirements?"

YES. Requirements are documented across: - v3.0 Requirements PDF (source of truth) - 13 POC task documents (implementation guides) - Full Velocity API specs (4 OpenAPI files + 4 Postman collections) - Verified integration log (actual working API calls)

Two minor clarifications (holder identification method, webhook vs polling) can be resolved during first test issuance — they don't block implementation.

"What's left for POC?"

2-3 days of focused backend wiring + minimal frontend work. See Part 3 for precise task list.

References