AMANI J. Africa Foundation - Donation USSD System

A programmable USSD application for receiving donations to communities within the AMANI J. Africa Foundation. This system enables donors to contribute to specific communities through an interactive USSD menu, supporting multiple donation purposes including Development, Education, Health, Water & Sanitation, Legal Aid, Disability, Chief's Gift, and Missions.

🌟 Features

• Interactive USSD Menu Flow: Simple 3-step donation process via USSD
• Community-Based Donations: Donors can specify which community receives their donation using reference codes
• Multiple Donation Purposes: Support for 8 different donation categories
• Payment Integration: Seamless integration with Hubtel payment gateway
• Transaction Tracking: Complete audit trail of all donations and transactions
• SMS Notifications: Automatic SMS confirmations upon successful donations
• RESTful API: Full API for managing communities and viewing donations
• Secure Authentication: JWT-based authentication for admin endpoints

📱 USSD Donation Flow

The donation process follows a simple 3-step flow:

Step 1: Community Selection

AMANI J. Africa Foundation

Donate to which Community?
1. *Enter the community Reference code*...

Step 2: Donation Purpose

Donation is for:
1. Development
2. Education
3. Health
4. Water & Sanitation
5. Legal Aid
6. Disability
7. Chief's Gift
8. Missions

Step 3: Amount Entry & Confirmation

Enter Amount: [User enters amount]

[Summary Display]
Community: [Community Name]
Purpose: [Selected Purpose]
Amount: GH [Amount]

1. Confirm
2. Cancel

Success Message

You have successfully donated to your community. Thank you.

🛠️ Tech Stack

• Framework: NestJS (Node.js)
• Database: MongoDB with Mongoose ODM
• Authentication: JWT (JSON Web Tokens)
• Payment Gateway: Hubtel USSD API
• SMS Service: Integrated SMS provider
• Language: TypeScript
• Validation: class-validator, class-transformer

📋 Prerequisites

• Node.js >= 18.0.0
• MongoDB instance (local or cloud)
• Hubtel USSD account credentials
• SMS service credentials

🚀 Installation

1. Clone the repository

   git clone <repository-url>
   cd ngo-ussd

2. Install dependencies

   npm install

3. Configure environment variables Create a .env file in the root directory:

   # Database
   MONGODB_URI=mongodb://localhost:27017/ngo-ussd
   
   # JWT
   JWT_SECRETE=your-jwt-secret-key
   JWT_EXPIRY=500s
   
   # Hubtel
   HB_CALLBACK_URL=https://your-callback-url.com/api/v1/flow/ussd/callback
   HUB_ACCESS_TOKEN=your-hubtel-access-token
   
   # SMS Service
   SMS_URL=https://your-sms-provider-url
   SMS_CLIENT_ID=your-sms-client-id
   SMS_CLIENT_SECRET=your-sms-client-secret
   SMS_SENDER=your-sender-id

4. Build the project

   npm run build

5. Run the application

   # Development
   npm run start:dev
   
   # Production
   npm run start:prod

📡 API Endpoints

USSD Endpoints

• POST /api/v1/flow/ussd - Handle USSD requests (Hubtel callback)
• POST /api/v1/flow/ussd/callback - Handle payment completion callbacks

Community Management

• GET /api/v1/communities - List all communities (optional query: ?isActive=true)
• GET /api/v1/communities/:referenceCode - Get community by reference code
• POST /api/v1/communities - Create new community (Admin only)
• PATCH /api/v1/communities/:id - Update community (Admin only)
• POST /api/v1/communities/:id/delete - Delete community (Admin only)

Donation Management

• GET /api/v1/donations - List all donations with optional filters (Admin only)
  • Query parameters: status, communityReferenceCode, donorMobile, sessionId, hubtelOrderId
• GET /api/v1/donations/:id - Get donation by ID (Admin only)

Health Check

• GET /api/v1/health - Application health status

📊 Database Schema

Community

• name: Community name
• referenceCode: Unique reference code (uppercase, indexed)
• description: Optional description
• isActive: Active status flag

Donation

• sessionId: USSD session identifier
• community: Reference to Community
• purpose: Donation purpose (enum)
• amount: Donation amount
• donorMobile: Donor's mobile number
• donorName: Donor's name
• status: Donation status (enum)
• transactionId: Related transaction ID

Transaction

• Complete payment transaction details from Hubtel
• Includes payment status, amounts, dates, and customer information

🔐 Authentication

The API uses JWT-based authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Public Endpoints (No authentication required):

• USSD endpoints
• Health check
• Community listing (read-only)

Protected Endpoints (Require authentication):

• Community management (create, update, delete)
• Donation management (admin only)

🏗️ Project Structure

src/
├── configs/          # Guards and authentication strategies
├── controllers/      # API route handlers
├── models/
│   ├── dto/         # Data transfer objects
│   └── schemas/     # MongoDB schemas and enums
├── services/        # Business logic
└── utils/           # Utility functions and helpers

🧪 Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

📝 Scripts

• npm run build - Build the project
• npm run start - Start the application
• npm run start:dev - Start in development mode with watch
• npm run start:debug - Start in debug mode
• npm run start:prod - Start in production mode
• npm run lint - Run ESLint

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the UNLICENSED License.

👥 About AMANI J. Africa Foundation

AMANI J. Africa Foundation is an NGO with 12 member executives in every subscribed community, dedicated to making a positive impact through various development initiatives including education, health, water & sanitation, legal aid, disability support, and missions.

📞 Support

For support and inquiries, please contact the development team.

---

Note: This system is designed specifically for the AMANI J. Africa Foundation's donation collection needs. Ensure all environment variables are properly configured before deployment.