# NCVSI Laravel Backend: Development Progress & Architecture Overview

## Executive Summary
The NCVSI backend has been successfully ported from NestJS to a robust, scalable **Laravel 12** architecture. Beyond simple parity, the system has been upgraded with a **Multi-Tenant Infrastructure**, a **Consent Management Engine**, and an advanced **Verification Workflow System** to support various stakeholders including Institutions, Regulatory Councils, and Employers.

---

## 1. Core Architecture Upgrades

### **Multi-Tenancy Framework**
- **Data Isolation**: Implemented a global `BelongsToTenant` trait and `TenantScope` to ensure strict data separation between organizations.
- **Dynamic Resolution**: Middleware-based tenant identification via `X-Tenant-Id` or `X-Tenant-Slug` headers.
- **Organization Types**: Native support for `INSTITUTION`, `COUNCIL`, `EMPLOYER`, `VERIFICATION_BODY`, and `AGENT`.

### **Identity & Security**
- **Identity Verification**: New module for multi-factor verification:
    - Email & Phone OTP flows.
    - ID Document upload and manual verification queue.
- **Audit Trail**: Tenant-aware logging system tracking every critical action (`action`, `entity`, `metadata`, `IP`, `UserAgent`).
- **JWT + RBAC**: Secure authentication with Role-Based Access Control scoped to both the user role and their tenant organization.

---

## 2. Verification & Credential Ecosystem

### **Unified Workflow Engine**
- **Status Lifecycle**: Centralized routing for different verification types (`ACADEMIC`, `LICENSE`, `CERTIFICATE`, `ATTENDANCE`).
- **Workflow Steps**: Granular tracking of progress from submission to completion, including automated transitions.

### **Consent Management Engine**
- **Candidate Control**: Verification requests now trigger a consent flow where candidates must approve the release of their data.
- **Legal Compliance**: Full audit trail of IP addresses and timestamps for every consent given or revoked.

### **Credential Vault**
- **Institution-Controlled Vault**: Secure storage for verified transcripts and certificates.
- **Record Reusability**: Allows for instant re-verification of previously validated credentials, reducing turnaround time.

### **Advanced Report Generator**
- **Dynamic Templates**: Support for Education, License, and Combined verification reports.
- **Security Features**: Automated generation of unique **Reference Numbers**, **QR Codes** for instant validation, and **Secure Watermarking**.

---

## 3. Transmission & Delivery

### **Secure Transmission System**
- **Multi-Channel Delivery**: Support for Secure Links, Portal-based access, and Direct delivery.
- **Lifecycle Tracking**: Monitor when a report is sent, delivered, and accessed.
- **Flagging System**: Ability to flag irregularities or fraudulent attempts during the transmission process.

---

## 4. Stakeholder Dashboards (RBAC)

Custom-tailored experiences for every user type:
- **Candidate**: Personal verification history, request tracking, and profile management.
- **Institution**: Student enrollment management, pending verification queues, and revenue analytics.
- **Council**: License validation workflows and regulatory oversight tools.
- **Employer**: Consent status monitoring and bulk verification management.
- **Super Admin**: Global system health, tenant management, and comprehensive audit logs.

---

## 5. Billing & Pricing Engine
- **Tenant-Specific Pricing**: Ability to set custom rates for specific institutions or organization types.
- **Service-Based Costs**: Flexible pricing configuration for different verification categories.
- **Currency Support**: Native support for NGN/USD paypal integration, stripe integration with extensible currency architecture.

---

## 6. Technical Milestones Completed
- [x] Full Parity with legacy NestJS endpoints.
- [x] Database Migration to PascalCase schema with PostgreSQL optimizations.
- [x] Implementation of CUID-based primary keys for enhanced security and decentralization.
- [x] Repository initialized and synced with [ncvsi-laravel-backend](https://github.com/OJPTECHNOLOGIESLTD/ncvsi-laravel-backend).

---

## Next Steps
- Implementation of the **Unified API Architecture refactor** for partner integrations.
- Development of the **Automated Notification Dispatcher** (Email/SMS/Push).
- Finalizing **Analytics & Reporting** export tools.