5-Tier Enterprise Architecture
IdentityFlow follows a strict separation of concerns across five horizontal tiers, ensuring scalability, auditability, and security isolation at every boundary.
Identity Verification Pipeline
End-to-end request lifecycle from citizen device to NIMC/NIBSS and back, with security checkpoints at every boundary.
NIN Verification Flow
Citizen submits NIN + OTP
TLS 1.3 · Encrypted payload
WAF validates · Rate-check · JWT verify
Cloud Armor · <5ms
Orchestration Engine hashes NIN (bcrypt-12)
Never stored raw
NIMC API call with vNIN token request
mTLS · Signed request
NIMC returns name/DOB/state/LGA
Zero-knowledge selective
Response cached 90s · Audit log written
Spanner · tamper-proof
Citizen receives verified profile
JWT refresh · <200ms total
BVN Linkage Flow
Citizen submits BVN + bank selector
TLS 1.3 · Encrypted payload
BVN immediately hashed (SHA-3-256)
Hash stored, not BVN
NIBSS API called with hash + bank code
NIBSS OAuth 2.0 client creds
NIBSS returns match confidence score
Probabilistic match ≥ 0.97
Financial Identity Score calculated
Composite: BVN + NIN + liveness
Bank linkage stored encrypted
Per-user KMS key
BPE pre-qualification score updated
<180ms end-to-end
Agency Data Share Flow
Agency (e.g. BPE) sends data request
Signed API key · IP allowlist
Consent Manager checks authorisation
Firestore real-time read
ZKP engine generates proof payload
Only authorised fields
Data minimisation filter applied
NDPR Art. 2.1(1)(c)
Encrypted payload sent to agency
Agency public key encryption
Access event logged to audit chain
Immutable Spanner record
Citizen notified via dashboard/SMS
Real-time Pub/Sub event
Zero-Trust Security Architecture
Every request is authenticated, authorised, and encrypted regardless of network origin. Trust is never assumed — it is always verified.
Identity & Access Management
Encryption Architecture
Zero-Knowledge Proofs
Network Security
Monitoring & Detection
Compliance Controls
Cloud-Native, Africa-Hosted Infrastructure
All citizen data remains within Africa (Google Cloud af-south1, Johannesburg) to satisfy NDPR data residency requirements. Multi-region failover to europe-west1 for DR only — no citizen data persisted outside Africa.
Google Cloud — Primary Region (af-south1 · Johannesburg)
Edge Layer
Compute Layer
Data Layer
Security Layer
Integration Layer
DR Region (europe-west1 · Belgium) — Metadata Only
Citizen PII is never replicated outside Africa. DR region holds only anonymised infrastructure state for failover orchestration. RPO: 1 hour. RTO: 4 hours.
SLA / SLO Targets
Platform Availability
≤ 4.38 hrs downtime/year
API P50 Latency
NIN verification end-to-end
API P95 Latency
Including NIMC API round-trip
API P99 Latency
Cold-start + NIBSS peak load
Throughput (normal)
Horizontal Cloud Run scaling
Throughput (burst)
Auto-scale + Cloud Armor burst
Data RPO
Continuous Spanner replication
Data RTO
Documented runbook · tested quarterly
Incident P0 SLA
Alert → Acknowledge → Response
Capacity Model
Citizen records
Nigeria total population
Active sessions
Cloud Spanner horizontal scale
Agency API calls
Government MDA combined
Audit log storage
Compressed · 7-year NDPR retention
vNIN generation
NIMC API quota based
Government API Integration Matrix
Each agency integration is independently managed with dedicated credentials, retry logic, circuit breakers, and compliance-aligned data handling.
| Agency | API Endpoint | Auth Method | Data Sent | Data Received | Timeout | Retry | Circuit Breaker |
|---|---|---|---|---|---|---|---|
| NIMC | api.nimc.gov.ng/v2 | OAuth 2.0 + mTLS | NIN hash, OTP | Name, DOB, State, LGA, Photo hash | 3s | 3× exp. backoff | 50% error/10s |
| NIBSS | api.nibss-plc.com.ng/bvn | API Key + IP allowlist | BVN hash, Bank code | Match score, linked name | 2s | 2× exp. backoff | 30% error/5s |
| CAC | services.cac.gov.ng/api | API Key + JWT | RC Number, Company name | Registration status, Directors | 5s | 3× exp. backoff | 40% error/10s |
| FIRS | api.firs.gov.ng/tin | OAuth 2.0 + HMAC-256 | TIN, NIN hash | TCC validity, expiry date | 4s | 2× exp. backoff | 35% error/10s |
| PENCOM | api.pencom.gov.ng/rsa | mTLS + OAuth 2.0 | NIN hash, BVN hash | RSA status, PFA name | 4s | 3× exp. backoff | 40% error/10s |
| BPE | api.bpe.gov.ng/gateway | API Key + signed request | Identity proof bundle | Pre-qualification status | 6s | 2× exp. backoff | 30% error/15s |
Enterprise Compliance Matrix
IdentityFlow maps every architectural component to its applicable compliance standard. Green = compliant. Amber = in progress. Grey = not applicable.
NDPR 2019 (Nigeria)
NIMC Act 2007 (Nigeria)
ISO/IEC 27001:2022
SOC 2 Type II (AICPA)
CBN Guidelines (BVN Framework)
Cybercrimes Act 2015 (Nigeria)
Full Technology Stack
| Technology | Purpose | Why Chosen |
|---|---|---|
| Next.js 15 | React framework (SSR/SSG/App Router) | SEO, performance, server components |
| React 19 | UI component library | Server actions, concurrent features |
| TypeScript 5 | Static typing | Type safety, DX, runtime confidence |
| Tailwind CSS 3 | Utility-first styling | Design system consistency |
| shadcn/ui | Accessible component primitives | WAI-ARIA compliance, Radix UI base |
| Lucide React | Icon system | Consistent, tree-shakeable SVGs |
| Technology | Purpose | Why Chosen |
|---|---|---|
| Node.js 22 LTS | Runtime | Long-term support, V8 performance |
| Google Genkit 1.x | AI orchestration framework | Flow-based AI pipelines, observability |
| Gemini 1.5 Pro | AI model (alternative suggestions, guidance) | Grounded in Nigerian identity context |
| Zod 3 | Schema validation (API + AI) | Runtime type safety for external data |
| Google Pub/Sub | Async event bus | Decoupled agency notifications |
| Cloud Run | Serverless container runtime | Auto-scale to zero, no idle cost |
| Technology | Purpose | Why Chosen |
|---|---|---|
| Cloud Spanner | Primary relational database | Global ACID transactions, 99.999% SLA |
| Cloud Firestore | Real-time session & consent state | Sub-10ms read latency, offline sync |
| Redis Memorystore | Session cache, token store | Sub-1ms cache reads, token revocation |
| Cloud KMS + HSM | Key management | FIPS 140-2 Level 3, hardware key isolation |
| BigQuery | Analytics & compliance reporting | Petabyte-scale audit log analysis |
| Cloud Storage | Document uploads (encrypted) | Client-side encryption, per-object keys |
| Technology | Purpose | Why Chosen |
|---|---|---|
| Cloud Armor | WAF + DDoS mitigation | OWASP CRS 3.3, adaptive protection |
| Google Chronicle | SIEM / threat intelligence | Planet-scale log analysis, IoC matching |
| Cloud SCC | Security posture management | Continuous misconfiguration detection |
| Workload Identity Federation | Service-to-service auth | No static keys in codebase or env |
| PagerDuty | On-call alerting | P0 < 5 min escalation SLA |
| Terraform | Infrastructure as Code | Reproducible, auditable infra changes |
Operational Excellence & DevSecOps
CI/CD Pipeline
- GitHub Actions — automated on every PR
- Unit tests (Jest) + Integration tests (Supertest)
- SAST scanning (CodeQL) on every push
- DAST scanning (OWASP ZAP) nightly
- Container image scanning (Trivy)
- IaC security scan (tfsec)
- Blue/green deployments via Cloud Deploy
- Automated rollback on P0 alert
Observability
- Structured JSON logging (all services)
- Cloud Trace — distributed request tracing
- Cloud Monitoring — SLO dashboards
- Custom metrics: NIN verify latency, BVN match rate
- Error budget alerts (99.95% target)
- Real User Monitoring (Web Vitals LCP/INP/CLS)
- Uptime checks every 60s (multi-region)
- Incident post-mortems (blameless · 48hr)
Business Continuity
- RPO: 1 hour (Cloud Spanner continuous backup)
- RTO: 4 hours (documented failover runbook)
- DR test: quarterly full failover drill
- Chaos engineering: monthly fault injection
- BCP reviewed annually by exec committee
- Vendor risk register: NIMC API SLA monitoring
- Degraded-mode: USSD fallback for NIN lookup
- Manual override: human review SLA 2 business days
Architect & CTO Questions
Common technical due diligence questions from enterprise clients and government agencies.
NINs are hashed with bcrypt-12 immediately on receipt and the plaintext is discarded. The hash alone is useless without the original — it cannot be reversed. Additionally, Zero-Knowledge Proofs mean NINs are verified without ever transmitting them to agencies. In the event of a database breach, no usable NINs can be extracted.
Ready to Integrate?
Request a technical integration package, API sandbox credentials, or a live architecture walkthrough with the IdentityFlow engineering team.