Enterprise Client Integration & Reference Guide¶

Welcome to the BPEVeriFlow Enterprise Integration Guide. This document provides federal IT officers, enterprise architects, security auditors, and system integrators with the specifications required to deploy, connect, scale, and audit BPEVeriFlow within sovereign cloud environments.

1. Enterprise Architecture & Service Mesh¶

BPEVeriFlow is designed as a secure, containerised service mesh. The Next.js gateway acts as a resilient proxy between sovereign client browsers and backend verification microservices.

              +-----------------------------------+
              |         Applicant Web UI          |
              |          (React / Client)         |
              +-----------------+-----------------+
                                |
                                | HTTPS / JSON
                                v
              +-----------------+-----------------+
              |         Next.js Gateway           |
              |       (API Routing Proxy)         |
              +--------+-----------------+--------+
                       |                 .
          REST / HTTP  |                 . Circuit Breaker
          (Online)     v                 . Fallback (Offline)
              +--------+-----------------+--------+
              |         Express Gateway           |
              |          (Port 4000)              |
              +--------+--------+--------+--------+
                       |        |        |
    +------------------+        |        +------------------+
    | Port 4001                 | Port 4002                 | Port 4003
    v                           v                           v
+---+------------+      +-------+--------+      +----------+-----+
| Identity Serv. |      | Verify Service |      | Exception Serv.|
| (SSI/Wallet)   |      | (AI Engine)    |      | (Human Review) |
+---+------------+      +-------+--------+      +----------+-----+
    |                           |                           |
    +------------------+--------+---------------------------+
                       |
           +-----------+-----------+
           |    NeonDB PostgreSQL  |
           |   (HA Cluster Sync)   |
           +-----------------------+

Infrastructure Resilience:

Database Layer: Supports PostgreSQL clustering with NeonDB. Secondary read replicas ensure data availability and sub-millisecond query latency.
Stateless Microservices: All Express services are completely stateless, enabling horizontal scaling behind load balancers (Nginx, AWS ALB, or Fly.io load balancers).

2. API Integration Reference¶

All endpoints communicate over REST/HTTP with standard JSON payloads. All requests must include:

Content-Type: application/json
Authorization: Bearer <jwt_token>

Gateway Rate Limits¶

Tier	Limit	Window	Applies To
Public (unauthenticated)	50 req	15 min	`/health`, `/api/ssi` (pre-auth)
Authenticated (user roles)	500 req	15 min	All `/api/*` routes
Executive/Admin	1000 req	15 min	Command center polling endpoints

A. Identity Verification (SSI Connection)¶

Endpoint: POST /api/ssi
Description: Verifies applicant's Decentralised Identifier (DID) and credentials during the login handshake.
Request Body:

{
  "walletType": "affinidi"
}

Response:

{
  "success": true,
  "did": "did:key:z6MkuXYZ...",
  "walletType": "affinidi",
  "credentials": [
    {
      "id": "vc-nin-ng-001",
      "type": "NationalIdentityCredential",
      "issuer": "did:bpe:nimc.gov.ng",
      "status": "active"
    }
  ],
  "prefillData": {
    "fullName": "Adebayo Emmanuel Okafor",
    "nin": "12345678901",
    "rcNumber": "RC-1234567"
  }
}

B. AI Desk Verification Analysis¶

Endpoint: POST /api/verify/:desk
Description: Runs compliance audits for the specified desk (1–5).
Request Body:

{
  "applicationId": "BPE-XXXXXXXX",
  "fullName": "Applicant Name",
  "nin": "11-digit NIN String",
  "bvn": "11-digit BVN String",
  "rcNumber": "Company Registration String",
  "organizationName": "Organization Name"
}

Response (Desk 1 example):

{
  "success": true,
  "applicationId": "BPE-K7G2J",
  "result": {
    "deskNumber": 1,
    "status": "completed",
    "aiScore": 89,
    "aiFlags": [],
    "aiSummary": "Pre-screening complete. NIMC-NIBSS NIN-BVN linkage verified automatically.",
    "confidence": 98,
    "processingTimeMs": 3450
  },
  "timestamp": "2026-06-19T15:40:00Z"
}

C. Gateway Health Check¶

Endpoint: GET /health
Description: Returns operational status for all downstream services. Useful for pre-deployment readiness checks.

{
  "status": "ok",
  "gateway": "healthy",
  "services": {
    "identity": { "status": "healthy", "latencyMs": 12 },
    "verify":   { "status": "healthy", "latencyMs": 18 },
    "exception": { "status": "healthy", "latencyMs": 9 }
  },
  "uptime": 3862.4,
  "timestamp": "2026-06-19T15:40:00Z"
}

BPEVeriFlow enforces Privacy-by-Design paradigms aligned with the Nigeria Data Protection Regulation (NDPR) 2019 and the General Data Protection Regulation (GDPR).

Regulation Mandate	Platform Implementation	Cryptographic Basis
Granular Consent (NDPR Art. 2.1)	Per-category consent manager in PETs Dashboard	State-synchronised permission maps
Right to Erasure (NDPR Art. 2.13)	One-click data purge from PETs tab	DB cascade deletes + credential revocation
Identity Masking (NDPR Art. 2.1)	16-digit Virtual ID tokens replace NIN/BVN for third parties	Secure token mapping with configurable expiries
Data Minimisation (GDPR Art. 25)	SSI wallets prevent raw PII from reaching BPE servers	W3C Verifiable Credentials + DIDComm handshakes

Cryptographic Audit Trail¶

Each event in BPEVeriFlow is appended to a chronologically chained audit ledger. Every block is signed with a SHA-256 equivalent mock hash linking to its parent:

$$H_i = \text{Hash}(H_{i-1} \parallel \text{Action} \parallel \text{Actor} \parallel \text{Details} \parallel \text{Timestamp})$$

Any modification to historical data breaks the signature chain, providing absolute tamper evidence.

4. High Availability & Disaster Recovery¶

Failover & Circuit Breakers¶

Auto-Fallback Boundary

The circuit breaker triggers after 1.5 seconds of timeout or an HTTP 503 response. Fallback mode is logged with isMockFallback: true metadata so affected records can be re-synced when services come back online.

Health Pings: Next.js checks downstream services at process.env.VERIFY_SERVICE_URL.
Circuit Interceptor: Timeout (>1.5s) or HTTP 503 triggers the circuit breaker.
Mock Fallback: System falls back to high-fidelity local JS modules computing desk eligibility locally.
Audit Tagging: Fallback actions are tagged isMockFallback: true for reconciliation.

DR Recovery Runbook¶

In case of database disconnects or cluster hardware failures:

Promote NeonDB read-replicas to the primary cluster.

Update gateway environment:

DATABASE_URL="postgresql://bpe_admin:credentials@new-replica-host/bpe_db?sslmode=require"

Restart gateway processes to load the new configuration.

5. Deployment Configuration¶

Production Environment Variables¶

Never Commit Secrets

The JWT_SECRET and DATABASE_URL values below are placeholders only. Always use your CI/CD secret manager (e.g. Fly.io Secrets, AWS Secrets Manager, or HashiCorp Vault) to inject these at runtime. Never commit real credentials to source control.

.env.production

# System Environment
NODE_ENV=production
PORT=3000

# Service Bindings (internal Docker/Fly.io hostnames)
GATEWAY_URL=http://gateway:4000
IDENTITY_SERVICE_URL=http://identity-service:4001
VERIFY_SERVICE_URL=http://verify-service:4002
EXCEPTION_SERVICE_URL=http://exception-service:4003

# Database Connectivity
DATABASE_URL=postgresql://user:pass@neondb-cluster/db?sslmode=require

# Security (use a randomly generated 256-bit key)
JWT_SECRET=REPLACE_WITH_SECURE_RANDOM_KEY

Docker Compose Horizontal Scaling¶

To scale the AI Verify service across multiple container instances under heavy load:

docker-compose up --scale verify-service=3 -d

This distributes Desk evaluation loads evenly across 3 container endpoints via the Docker internal load balancer.