Zerax - Seller Financing Ecosystem

Team Zerax - Hackathon Project

A comprehensive digital ecosystem enabling SME sellers to access financing, manage inventory, process orders, and grow their businesses through an integrated platform connecting sellers, lenders, suppliers, and field agents.

Team

Team Zerax

• Adisa Naheem Olaide - Frontend Developer
• Treasure Uvietobore - Backend Developer
• Enoch Idowu - Backend / AI Engineer
• Olatunji Oluwashola - Product Manager

Overview

Zerax is a multi-stakeholder platform designed to bridge the financing gap for small and medium enterprises (SMEs) in emerging markets. By connecting sellers with lenders, suppliers, and field agents, Zerax creates a complete ecosystem that facilitates:

• Access to Capital: Quick loan applications and approvals
• Inventory Management: Product catalog and stock tracking
• Supply Chain: Direct supplier connections and order fulfillment
• Field Operations: Agent-assisted onboarding and collections
• AI-Powered Insights: Business intelligence and conversational commerce

System Architecture

graph TD
    A[Landing Page] --> B[User Registration]

    B --> C[Seller Dashboard]
    B --> D[Lender Portal]
    B --> E[Supplier Portal]
    B --> F[Agent Portal]

    C --> G[Seller Backend]
    D --> H[Lenders Backend]
    E --> H
    F --> G

    G --> I[Services Backend]
    H --> I

    I --> J[MongoDB Database]
    I --> K[Redis Cache]
    I --> L[Cloudflare R2]
    I --> M[Gemini AI]
    I --> N[WhatsApp API]

    G --> O[Email Service]
    G --> P[SMS Service]

Loading

Platform Components

Frontend Applications

1. Landing Page

• Purpose: Marketing and user acquisition
• Technology: Next.js 16, React 19, TypeScript
• Features:
  • Hero section and value proposition
  • Feature highlights
  • Multi-portal registration flows
  • Interactive storefront demo
  • Seller dashboard integration
  • Lender portal integration
  • Responsive design

2. Agent Portal

• Purpose: Field agent operations
• Technology: Next.js 16, React 19, TypeScript
• Features:
  • Seller onboarding
  • Loan origination
  • KYC verification
  • Collections management
  • Offline sync capabilities
  • Mobile-first design

3. Lenders Portal

• Purpose: Loan management and portfolio monitoring
• Technology: Next.js 16, React 19, TypeScript
• Features:
  • Loan product creation
  • Application processing
  • Approval workflows
  • Disbursement tracking
  • Repayment management
  • Portfolio analytics
  • Risk assessment

4. Suppliers Portal

• Purpose: B2B marketplace and supply management
• Technology: Next.js 16, React 19, TypeScript
• Features:
  • Product catalog management
  • Inventory tracking
  • Order fulfillment
  • Supply-demand matching
  • Quote management
  • Delivery tracking
  • Payment processing

Backend Services

1. Seller Backend

• Purpose: Core seller platform APIs
• Technology: Node.js, Express, TypeScript, MongoDB
• Features:
  • Authentication and authorization
  • Business onboarding
  • KYC processing
  • Loan applications
  • Product catalog
  • Order management
  • AI-powered product imports
  • Trust score calculation
  • WhatsApp integration
  • Voice assistant

2. Services Backend

• Purpose: Shared services and integrations
• Technology: Node.js, Express, TypeScript, MongoDB
• Features:
  • WhatsApp Business API
  • AI conversational agent
  • File upload and storage (Cloudflare R2)
  • Shared database models
  • Intent recognition
  • Cart management
  • Order processing via chat

Technology Stack

Frontend

• Framework: Next.js 16 with App Router
• Language: TypeScript 5.9
• UI Library: React 19
• Styling: Tailwind CSS 4
• Components: shadcn/ui with Radix UI
• State Management: Zustand 5.0
• Data Fetching: TanStack Query 5.9
• Forms: React Hook Form with Zod
• Tables: TanStack Table 8.21
• Charts: Recharts 2.15
• Icons: Iconify, Lucide React
• Package Manager: pnpm

Backend

• Runtime: Node.js
• Framework: Express 4.19+
• Language: TypeScript 5.4+
• Database: MongoDB 8.6+ with Mongoose
• Cache/Queue: Redis with BullMQ
• Authentication: JWT
• Validation: express-validator
• File Storage: Cloudflare R2
• AI: Google Gemini AI
• Email: Nodemailer
• Security: Helmet, bcrypt, CORS

Project Structure

zerax/
├── landing-page/           # Marketing and registration portal (includes dashboard & lenders)
├── agent-frontend/         # Field agent management application
├── lenders-frontend/       # Lender operations portal
├── suppliers-frontend/     # Supplier B2B marketplace
├── merchant-backend/       # Seller platform API
└── services/               # Shared services and integrations

Core Workflows

1. Seller Onboarding Flow

sequenceDiagram
    participant S as Seller
    participant LP as Landing Page
    participant SB as Seller Backend
    participant DB as Database
    participant D as Dashboard

    S->>LP: Visit Landing Page
    LP->>S: Display Features & Value Prop
    S->>LP: Click "Get Started"
    LP->>S: Show Registration Form
    
    S->>LP: Submit Registration
    LP->>SB: POST /api/auth/signup
    SB->>DB: Create User Account
    DB->>SB: User Created
    SB->>S: Send OTP
    
    S->>LP: Enter OTP
    LP->>SB: POST /api/auth/verify-otp
    SB->>DB: Verify OTP
    DB->>SB: Verification Success
    SB->>LP: JWT Tokens
    
    LP->>D: Redirect to Dashboard
    D->>S: Show Onboarding Flow
    
    S->>D: Complete Business Profile
    D->>SB: POST /api/onboarding/business-profile
    SB->>DB: Save Profile
    
    S->>D: Upload KYC Documents
    D->>SB: POST /api/onboarding/kyc/upload-document
    SB->>DB: Save Documents
    
    S->>D: Submit Onboarding
    D->>SB: POST /api/onboarding/submit
    SB->>DB: Calculate Trust Score
    SB->>D: Onboarding Complete
    D->>S: Show Dashboard

Loading

2. Loan Application Flow

sequenceDiagram
    participant S as Seller
    participant D as Dashboard
    participant SB as Seller Backend
    participant LB as Lenders Backend
    participant LP as Lender Portal
    participant L as Lender
    participant DB as Database

    S->>D: View Loan Offers
    D->>SB: GET /api/loans/offers
    SB->>LB: Fetch Available Loans
    LB->>SB: Loan Products
    SB->>D: Display Offers
    D->>S: Show Loan Options
    
    S->>D: Select Loan & Apply
    D->>SB: POST /api/loans/apply
    SB->>DB: Calculate Trust Score
    SB->>DB: Check Eligibility
    SB->>LB: Submit Application
    LB->>DB: Save Application
    LB->>SB: Application ID
    SB->>D: Application Submitted
    D->>S: Show Status

    LP->>LB: Fetch Applications
    LB->>LP: Application Queue
    L->>LP: Review Application
    L->>LP: Approve/Reject

    alt Approved
        LP->>LB: Approve
        LB->>SB: Notify Approval
        SB->>DB: Update Wallet
        SB->>D: Disbursement Notification
        D->>S: Show Disbursement Complete
    else Rejected
        LP->>LB: Reject
        LB->>SB: Notify Rejection
        SB->>D: Rejection Notification
        D->>S: Show Application Rejected
    end

Loading

3. Supply Chain Flow

sequenceDiagram
    participant S as Seller
    participant SB as Seller Backend
    participant SP as Supplier Portal
    participant SU as Supplier
    participant DB as Database

    S->>SB: Create Purchase Order
    SB->>DB: Save Order
    SB->>SP: Broadcast Demand

    SP->>SU: Show Opportunity
    SU->>SP: Submit Quote
    SP->>SB: Send Quote
    SB->>S: Display Quotes

    S->>SB: Select Supplier
    SB->>SP: Confirm Order
    SP->>DB: Update Order
    SP->>SU: Notify Order

    SU->>SP: Process Order
    SU->>SP: Update Status
    SP->>SB: Sync Status
    SB->>S: Track Delivery

    SU->>SP: Mark Delivered
    SP->>DB: Complete Order
    SP->>SB: Trigger Payment

Loading

4. WhatsApp Commerce Flow

sequenceDiagram
    participant C as Customer
    participant WA as WhatsApp
    participant SVC as Services Backend
    participant AI as Gemini AI
    participant DB as Database

    C->>WA: Send Message
    WA->>SVC: Webhook Event
    SVC->>DB: Get Conversation
    SVC->>AI: Analyze Intent
    AI->>SVC: Intent & Response

    alt Browse Products
        SVC->>DB: Fetch Products
        SVC->>WA: Show Products
    else Add to Cart
        SVC->>DB: Update Cart
        SVC->>WA: Cart Updated
    else Place Order
        SVC->>DB: Create Order
        SVC->>WA: Order Confirmed
    end

    WA->>C: Deliver Response

Loading

Key Features

For Sellers

• Digital business profile and storefront
• Quick loan applications with AI-powered eligibility
• Product catalog management
• Bulk product import from marketplaces (Jumia, Jiji)
• Order and inventory tracking
• WhatsApp-based commerce
• Voice assistant for business insights
• Offline transaction capability
• Trust score tracking

For Lenders

• Custom loan product creation
• Automated application processing
• Multi-step approval workflows
• Portfolio management and analytics
• Disbursement and repayment tracking
• Collections management
• Risk assessment tools
• Compliance reporting

For Suppliers

• B2B marketplace access
• Product catalog management
• Real-time demand matching
• Quote management system
• Order fulfillment workflow
• Delivery tracking
• Payment reconciliation
• Seller relationship management

For Field Agents

• Mobile-first seller onboarding
• KYC document collection
• Loan origination
• Collections queue
• Commission tracking
• Offline data sync
• Performance analytics

AI-Powered Features

Gemini AI Integration

• Product Import: Automated extraction from marketplace URLs
• Voice Assistant: Natural language business queries
• WhatsApp Bot: Conversational commerce
• Intent Recognition: Customer service automation
• Business Insights: AI-generated recommendations
• Trust Scoring: Machine learning-based creditworthiness

Supported Capabilities

• Natural language understanding
• Context-aware conversations
• Product categorization
• Sentiment analysis
• Predictive analytics

Getting Started

Prerequisites

• Node.js 18+ (recommended: Node.js 20+)
• MongoDB 5.0+
• Redis 6.0+ (for BullMQ)
• pnpm (for frontend projects)
• Yarn or npm (for backend projects)

Environment Setup

Each project has its own environment configuration. Refer to individual project READMEs:

• Landing Page
• Agent Portal
• Lenders Portal
• Suppliers Portal
• Seller Backend
• Services Backend

Quick Start

1. Clone the repository:

git clone <repository-url>
cd zerax

2. Install dependencies for all projects:

cd landing-page && pnpm install && cd ..
cd agent-frontend && pnpm install && cd ..
cd lenders-frontend && pnpm install && cd ..
cd suppliers-frontend && pnpm install && cd ..
cd merchant-backend && yarn install && cd ..
cd services && yarn install && cd ..

3. Set up environment variables for each project (see individual README files)

4. Start MongoDB and Redis:

mongod
redis-server

5. Start all services:

Backend Services:

cd merchant-backend && yarn dev &
cd services && yarn dev &

Frontend Applications:

cd landing-page && pnpm dev &
cd agent-frontend && pnpm dev &
cd lenders-frontend && pnpm dev &
cd suppliers-frontend && pnpm dev &

Development Ports

Service	Port	URL
Landing Page	3000	http://localhost:3000
Agent Portal	3001	http://localhost:3001
Lenders Portal	3002	http://localhost:3002
Suppliers Portal	3003	http://localhost:3003
Seller Backend	8001	http://localhost:8001
Services Backend	3006	http://localhost:3006

API Documentation

Seller Backend

• Base URL: http://localhost:8001/api
• Authentication: JWT Bearer token
• Key endpoints: /auth, /onboarding, /loans, /products, /orders

Services Backend

• Base URL: http://localhost:3006/api
• Authentication: API Key + JWT
• Key endpoints: /whatsapp, /agent, /upload

Security

Authentication & Authorization

• JWT-based authentication across all services
• Role-based access control (RBAC)
• API key authentication for inter-service communication
• Two-factor authentication (2FA) support

Data Protection

• Password hashing with bcrypt
• Input validation and sanitization
• CSRF protection
• Helmet security headers
• CORS configuration
• File upload restrictions
• Rate limiting

Compliance

• GDPR considerations
• Data encryption at rest and in transit
• Audit logging for critical operations
• KYC/AML compliance

Design System

Visual Guidelines

All frontend applications follow a consistent design system:

• Minimalist, flat design without shadows
• Thin borders (1px) for subtle separation
• Consistent padding (p-4) throughout
• Semibold typography with tight letter spacing
• Uniform icon sizing (size-4, size-5)

Component Standards

• Reusable UI components via shadcn/ui
• Consistent form patterns with React Hook Form
• Standardized data tables with TanStack Table
• Accessible modals and dialogs
• Mobile-responsive layouts

Performance Optimization

Frontend

• Next.js 16 App Router with automatic code splitting
• React 19 Server Components
• React Compiler for automatic optimization
• Image optimization with Next.js Image
• Lazy loading for heavy components
• TanStack Query for efficient data caching

Backend

• MongoDB connection pooling
• Redis caching for frequently accessed data
• BullMQ for background job processing
• Async/await for non-blocking I/O
• Request rate limiting
• Database indexing

Testing

Each project includes testing setup:

• Unit tests for business logic
• Integration tests for API endpoints
• E2E tests for critical user flows
• Component tests for UI elements

Deployment

Frontend Applications

• Next.js applications can be deployed to any Node.js hosting platform
• Static export option available for static hosting
• Environment variables configuration required

Backend Services

• Node.js runtime required for backend services
• MongoDB connection string configuration
• Redis connection for queue management
• Environment variables for API keys and secrets

Database & Storage

• MongoDB database (local or cloud-hosted)
• Redis instance for caching and queues
• Cloudflare R2 for file storage

Monitoring & Logging

• Application logs with Winston
• Error tracking with Sentry (recommended)
• Performance monitoring with New Relic (recommended)
• Uptime monitoring with Uptime Robot
• Analytics with Google Analytics

Future Enhancements

• Mobile applications (iOS/Android)
• Advanced analytics dashboard
• Credit scoring machine learning model
• Blockchain-based transaction verification
• Multi-currency support
• API marketplace for third-party integrations
• Seller community features
• Loyalty and rewards program

Contributing

1. Create a feature branch from main
2. Follow the existing code style and conventions
3. Write tests for new features
4. Ensure all tests pass and linting is clean
5. Submit a pull request with detailed description

License

This project is private and proprietary.

Support & Contact

For support, questions, or collaboration inquiries, please contact the Team Zerax:

• Technical Lead: Adisa Naheem Olaide
• Backend Lead: Treasure Uvietobore
• AI/ML Lead: Enoch Idowu
• Product Lead: Olatunji Oluwashola

---

Built with innovation and dedication by Team Zerax.