Getting Started & Running BPEVeriFlow¶

This page provides technical guidelines to set up the BPEVeriFlow platform locally for testing, development, and staging environments.

Technical Prerequisites¶

Node.js Version Requirement

BPEVeriFlow requires Node.js v22.x or higher. Earlier versions will fail to compile the Next.js 16 app or the TypeScript microservices. Run node --version to check your current version.

Tool	Minimum Version	Required?	Purpose
Node.js	`22.x`	✅ Yes	Runtime for Next.js and microservices
NPM	`10.x`	✅ Yes	Package manager
Docker & Compose	`24.x`	⚙️ Optional	Containerised microservice deployment
Python + MkDocs	`3.11+`	⚙️ Optional	Build or edit this documentation locally

1. Local Workspace Installation¶

Clone the repository and install all frontend packages from the project root:

# Clone the repository
git clone https://github.com/bpe-gov-ng/bpeveriflow.git
cd bpeveriflow

# Install Next.js / root dependencies
npm install

2. Environment Configuration¶

Required Before First Run

The application reads secrets from a .env file in the project root. Without it, API routes will use mock fallbacks only and some features may behave unexpectedly.

Copy the provided example and fill in your values:

cp .env.example .env

Key variables in .env:

# Next.js runtime
NODE_ENV=development
PORT=3000

# Backend microservice URLs (leave as-is for local Docker setup)
GATEWAY_URL=http://localhost:4000
IDENTITY_SERVICE_URL=http://localhost:4001
VERIFY_SERVICE_URL=http://localhost:4002
EXCEPTION_SERVICE_URL=http://localhost:4003

# Database (optional for full persistence)
DATABASE_URL=postgresql://user:pass@localhost:5432/bpe_db?sslmode=disable

# Security
JWT_SECRET=dev_local_secret_change_in_production

3. Running the Next.js Web App¶

Start the Next.js local server in development mode:

npm run dev

Open http://localhost:3000 in your browser.

Works Without Microservices

If the backend containers are offline, the Next.js API routes automatically detect ECONNREFUSED errors and fall back to high-fidelity mock responders. The full onboarding timeline, biometric fallback flow, and payment gateway simulation all work out of the box without any backend.

To build the optimised production bundle:

npm run build
npm run start

4. Launching Microservices Directly¶

Each backend microservice lives in the microservices/ directory:

Directory	Port	Role
`microservices/gateway`	`4000`	Central routing proxy & rate limiter
`microservices/identity-service`	`4001`	NIMC · CAC · SSI credential checks
`microservices/verify-service`	`4002`	AI scoring engine · fraud analysis
`microservices/exception-service`	`4003`	Human review queue & escalations

To compile and launch a service manually (no Docker):

macOS / LinuxWindows (PowerShell)

cd microservices/gateway
npm install
npm run build
npm start

Set-Location microservices\gateway
npm install
npm run build
npm start

Repeat for each service under microservices/.

5. Deploying via Docker Compose¶

To run all four microservices simultaneously in isolated containers:

cd microservices
docker-compose up --build

Verify all services are healthy:

curl http://localhost:4000/health

A healthy response returns:

{
  "status": "ok",
  "services": {
    "identity": "healthy",
    "verify": "healthy",
    "exception": "healthy"
  },
  "uptime": 42.3
}

Port Map¶

Service	URL
Next.js Frontend	`http://localhost:3000`
API Gateway	`http://localhost:4000`
Identity Service	`http://localhost:4001`
Verify Service	`http://localhost:4002`
Exception Service	`http://localhost:4003`

6. Troubleshooting¶

Port 3000 already in use

Another process is using port 3000. Find and kill it:

lsof -ti:3000 | xargs kill -9

Then re-run npm run dev.

ECONNREFUSED 127.0.0.1:4000 in console

The microservices gateway is not running. This is expected in a frontend-only setup — the app will automatically fall back to mock data. You can safely ignore this warning during development.

TypeScript build errors on npm run build

Ensure you're on Node.js v22+: node --version. Then clear the build cache and retry:

rm -rf .next
npm run build

MkDocs pymdownx.emoji import error

Install the full Material for MkDocs bundle:

pip install mkdocs-material