# Airpero SaaS - Internal Developer Guide

Welcome to the Airpero SaaS platform development guide. This document provides an overview of the system architecture, core components, and integration logic.

## 1. System Overview
Airpero is a multi-tenant Fintech SaaS platform that allows merchants to manage customer virtual accounts, collect deposits, and initiate payouts using the 9PSB banking infrastructure.

### Core Features:
- **Multi-tenancy**: Merchants are isolated and have their own customers and transaction history.
- **Virtual Accounts**: Automated creation of 9PSB virtual accounts for both merchants (funding) and customers.
- **Fee Management**: Centralized fee calculation (0.5% cap ₦100 for deposits, ₦20 for payouts).
- **Webhooks**: Outgoing notifications to merchants for real-time activity updates.

## 2. Technical Stack
- **Runtime**: Node.js (ES Modules)
- **Framework**: Express.js
- **Database**: MySQL (via Sequelize ORM)
- **Authentication**: JWT (Dashboard) & API Keys (External Integrations)
- **Service Integration**: Axios for 9PSB and Webhook calls.

## 3. Directory Structure
- `src/models/`: Sequelize models defining the database schema.
- `src/controllers/`: Logic for handling API requests.
- `src/routes/`: API endpoint definitions and middleware mapping.
- `src/services/`: Reusable business logic (e.g., `WebhookService`).
- `src/thirdParties/`: External API integrations (e.g., `PsbService`).
- `src/middlewares/`: Authentication and authorization logic.
- `src/migrations/`: Database versioning scripts.

## 4. Models & Relationships
- **Admin**: Platform-wide supervisors (SuperAdmin vs Admin).
- **Merchant**: The SaaS tenants. Each merchant has a `publicKey`, `privateKey`, and a `merchantAccountNumber` (funding account).
- **Customer**: Users belonging to a Merchant. Each customer has a unique 9PSB virtual account.
- **Transaction**: Records of all financial activities (deposits and payouts).
  - Linked to both a `Merchant` and a `Customer` (if applicable).

## 5. 9PSB Integration Flow
The system interacts with two 9PSB APIs:
1. **IVA API**: Used for "Static" accounts (e.g., `PsbService.createStaticAccount`) for long-term funding or customer accounts.
2. **WaaS API**: Used for "Wallet" operations (e.g., payouts, requeries, and bank lookups).

### Incoming Deposits (Webhooks)
1. 9PSB sends a POST request to `/api/v1/webhooks/9psb`.
2. `TransactionController.handleWebhook` validates the session.
3. The system credits the Customer's balance and records a Transaction.
4. `WebhookService` notifies the Merchant's configured `webhookUrl`.

## 6. Authentication Strategy
### Dashboard (Frontend)
Merchants and Admins log in via email/password to receive a **JWT**. This token must be sent in the `Authorization: Bearer <token>` header.

### External API (Server-to-Server)
Merchants use their `publicKey` and `privateKey` in headers:
- `X-Public-Key`: `pk_...`
- `X-Private-Key`: `sk_...`

## 7. Environment Variables
Ensure your `.env` file contains:
- Database credentials.
- `JWT_SECRET`.
- 9PSB Live Keys (`PSB_PUBLIC_KEY`, `PSB_PRIVATE_KEY`).
- 9PSB WaaS Keys (`PSB_WAAS_*`).
- `PSB_BASE_URL` and `PSB_WAAS_BASE_URL`.

---
*Generated by Antigravity AI on 2026-03-28.*