# System Architecture Overview

The Nano Lending platform is organized into a **six-layer architecture** that separates user experience, business services, integrations, data, security, and infrastructure. This ensures scalability, compliance, and fast iteration from sandbox to production.



## User Interfaces

This layer serves as the entry point for all user interactions. It provides intuitive, responsive access across devices.

* **Channels**
  * Mobile & Web (LightWay): loan offers view, acceptance, repayment, history/receipts, and notifications center.
  * **Internal Ops Console** (Lightway): customer lookup, loan status, manual overrides (with maker–checker), exception handling, reports.



## Application/Services Layer

**Core Services (LightWay)**

* **Eligibility & Offer Service**: orchestrates call to Interswitch **get-offers**, applies Lightway policy flags, filters by risk.
* **Loan Acceptance Orchestrator**: validates KYC state, checks limits, triggers **accept-offer**, handles disbursement callback expectations.
* **Repayment Processing**: receives **accept-payment-notification**, updates schedules, posts ledger entries, issues receipts.
* **Pricing & Interest Engine**: APR/fees, promo rules, penalties (configurable by tier & product).
* **Customer Profile & Preferences**: stores saved cards/repayment methods, notification preferences.
* **Notifications Service**: email/SMS/push for offer availability, acceptance, due dates, and delinquency alerts.
* **Compliance & Audit Service**: immutable logs, SAR hooks, export packs for regulators.
* **Reporting & Insights**: portfolio KPIs, cohort delinquency, roll rates, NPL, reconciliation views.



## Security Layer

Ensures robust access control, encryption, and policy enforcement to protect sensitive data and system integrity.

* **AuthN/AuthZ**: OAuth2/OIDC for apps; RBAC/ABAC for staff (least privilege).
* **Secrets Management**: KMS/HSM for API keys, tokens; rotation policy.
* **Encryption**: TLS 1.2+ in transit; AES-256 at rest.
* **API Security**: request signing, nonce, idempotency, rate limiting, WAF.
* **Compliance**: CBN guidelines, PCI-DSS for payment data handling, audit trails (tamper-evident).
* **Monitoring & SIEM**: login anomalies, fraud signals, PII access alerts.



## Data Layer

Handles all transactional and analytical data, ensuring integrity, availability, and recoverability.

**Operational Stores**

* **Loans DB**: applications, offers snapshots, acceptance, schedules, status.
* **Repayments DB**: transactions, reconciliation state, chargebacks.
* **Customers DB**: KYC state, preferences, saved instruments/beneficiaries.
* **Audit & Events**: append-only audit log, event bus topics.

**Analytics**

* **Star schemas** for loans/repayments, delinquency snapshots, compliance marts.
* **Data retention & archival** policies aligned to regulation.

**Data Quality**

* Referential integrity, schema versioning, CDC to warehouse, reconciliation tables vs. Interswitch settlement files.



## Integration Layer

Manages external system connections and payment processing.&#x20;

**External Integrations**

* **Interswitch Lending Services (ILS) APIs**
  * `get-offers` (offers retrieval)
  * `accept-offer` (loan acceptance/disbursement)
  * `accept-payment-notification` (repayment callback)
  * (Loan history endpoint excluded in this scope)
* **Payments/Rail Gateway**: card/debit rails for repayments (via Interswitch).
* **KYC/Identity (as applicable)**: BVN/NIN or existing Lightway providers for eligibility guardrails.
* **Comms Providers**: SMS/email/push gateways.

**Internal Integrations**

* **Core Banking/GL** (Lightway): posting, daily EoD batches, settlement & reconciliation.
* **Data Warehouse/BI**: downstream analytics and compliance reporting.



## Infrastructure Layer

* **Environments**: Sandbox → Staging → Production (segregated VPCs/VNETs).
* **Compute**: containerized services (autoscaling), blue/green deploys, health checks.
* **Networking**: private subnets, NAT/egress control, IP whitelisting for partner endpoints.
* **Storage**: managed relational DB for OLTP, object storage for artifacts/exports, warehouse for BI.
* **Observability**: logs, metrics (latency, TPS, error rates), traces; alerting on SLO breaches.
* **Resilience**: multi-AZ, automated backups, PITR, runbooks & DR playbooks.



### Reference Flows (High Level)

**A) Offer Retrieval**

1. Client → Lightway API (customer context)
2. Lightway → ILS `get-offers`
3. Policy filter → Return curated offers to client

**B) Loan Acceptance**

1. Client → Lightway (accept offer + consent)
2. Lightway validations (KYC, limits, affordability)
3. Lightway → ILS `accept-offer`
4. Update Loans DB, notify user, post to GL

**C) Repayment Notification**

1. Interswitch → Lightway webhook `accept-payment-notification`
2. Verify signature → Update repayment + reconcile
3. Notify user, refresh schedules, emit events to BI





This layered architecture ensures that the Nano Lending Platform can handle high transaction volumes securely, maintain regulatory compliance, and scale effectively to meet future demands.&#x20;
