# KuvarPay Merchant Dashboard

KuvarPay is a high-performance, secure crypto payment gateway specifically tailored for African businesses. It empowers merchants to accept various cryptocurrencies and receive settlements in local fiat currencies directly into their bank accounts, bridging the gap between global crypto liquidity and local financial systems.

## Product Overview
KuvarPay provides a comprehensive dashboard for merchants to manage their financial operations in the crypto ecosystem. It handles the complexity of blockchain interactions, currency conversions, and local bank payouts, allowing businesses to focus on their core operations.

## Key Features
- **Crypto-to-Fiat Gateway**: Seamlessly receive crypto payments and settle in local fiat (e.g., NGN, GHS, KES).
- **Payment Infrastructure**:
    - **Invoices**: Automated professional billing for customers.
    - **Payment Links**: One-click shareable links for social media or direct sales.
    - **Direct Transfers**: Capabilities for moving funds efficiently across the platform.
- **Settlement & Payouts**: Robust approval workflow for fiat payouts to bank accounts.
- **Team Collaboration**: Advanced Role-Based Access Control (RBAC) to invite team members with granular permissions.
- **Developer First**:
    - **RESTful API**: Comprehensive API for custom integrations.
    - **Webhooks**: Real-time event notifications for payments, settlements, and more.
    - **Sandbox Mode**: Secure environment for testing integrations without real funds.
- **Analytics & Reporting**: Real-time tracking of transactions, revenue trends, and currency aggregates.

## Tech Stack
- **Frontend**: Next.js 16 (React 19), Tailwind CSS, Radix UI, Headless UI.
- **Animations & UX**: GSAP, Motion (framer-motion), Three.js (3D visualizations), Lenis smooth scrolling.
- **Backend/API**: Next.js API Routes, Node.js.
- **Database & ORM**: PostgreSQL, Drizzle ORM.
- **Caching & Async Workflows**: Redis, BullMQ for background jobs (emails, crons).
- **Security**: JWT, NextAuth.js, bcryptjs, 2FA support (OTPLib).
- **Communication**: Nodemailer with DKIM support, Cloudinary for asset management.
- **Processing**: Tesseract.js (OCR), Face-api.js (Identity verification/security), Puppeteer (PDF/document generation).

## Core Data Entities
- **Users**: Core identities with authentication and profile data.
- **Businesses**: Business-level configuration, branding, and ledger settings.
- **Transactions**: Detailed logs of crypto inflows, status tracking, and FX rates.
- **Settlements**: Payout requests and fulfillment records to fiat bank accounts.
- **Invoices & Payment Links**: Customer-facing payment artifacts.
- **Team Members**: Permission mappings between users and businesses.
- **API Keys & Webhooks**: Integration points for third-party developers.

## Project Architecture
- `src/pages/api/v1`: Versioned backend logic and controllers.
- `src/components`: UI library organized by domain (Auth, Dashboard, Shared).
- `src/lib`: Core library for validation (Zod), database interaction, and business logic.
- `src/workers`: Managed background processes for asynchronous tasks.
- `external/db`: Dedicated module for database schema definitions and migrations.
- `docs/`: Technical guides for settlements, webhooks, and infrastructure setup.

---
*Empowering African commerce with blockchain technology.*