🛠️ Development Tools

• 📚 API Documentation: Comprehensive documentation with cURL examples
• 🧪 Testing Framework: Built-in testing capabilities for service validation
• 🔧 Service Management: Individual service configuration and monitoring
• 📈 Analytics Dashboard: Real-time service statistics and user metrics

🏗️ Architecture

• 🎯 Modular Design: Clean separation of concerns with adapter pattern
• ⚡ Spring Boot: Enterprise-grade framework with auto-configuration
• 🎨 Modern UI: Responsive design with Tailwind CSS
• 🗄️ Database Ready: H2 in-memory database with JPA support
• 🔄 Maven Build: Standardized build process and dependency management

🛠️ Quick Start

Prerequisites

• Java 11+ - Oracle JDK or OpenJDK
• Maven 3.6+ - For dependency management and build
• IDE - IntelliJ IDEA, Eclipse, or VS Code with Java extensions

Installation

1. Clone the repository

   git clone https://github.com/arison99/Sparrow.git
   cd Sparrow
   

2. Build the project

   mvn clean compile
   

3. Run the application

   mvn spring-boot:run
   

4. Access the platforms

   • Web Admin Dashboard: http://localhost:8080/admin
   • API Documentation: http://localhost:8080/admin/api-docs
   • USSD Simulator: Run MoMoUSDDApplication.java for traditional USSD interface

Docker Support (Optional)

# Build Docker image
docker build -t sparrow-momo .

# Run container
docker run -p 8080:8080 sparrow-momo

🚀 Usage

Web Admin Dashboard

1. Access the Dashboard: Navigate to http://localhost:8080/admin
2. User Management: Add users, view balances, and manage accounts
3. Service Operations: Process transactions across all mobile money services
4. Transaction Monitoring: View real-time transaction history and analytics
5. API Testing: Use built-in tools to test REST and XML endpoints

Individual Service Management

• Send Money: /admin/service/send-money
• Buy Airtime: /admin/service/buy-airtime
• Pay with MoMo: /admin/service/pay-with-momo
• Pay Bills: /admin/service/pay-bill
• Savings & Loans: /admin/service/savings-loans
• Invest & Insure: /admin/service/invest-insure

API Integration

# Add a new user
curl -X POST http://localhost:8080/admin/addUser \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "phone=+1234567890&pin=1234&balance=1000.00"

# Send money
curl -X POST http://localhost:8080/admin/sendMoney \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "fromPhone=+1234567890&toPhone=+0987654321&amount=100.00"

# Get user balance
curl -X POST http://localhost:8080/api/users/balance \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "phone=+1234567890"

USSD Simulation

1. Run MoMoUSDDApplication.java for traditional USSD interface
2. Navigate through menu options using number selection
3. Perform operations like balance inquiry, money transfer, and PIN management

📂 Project Architecture

Sparrow/
├── src/main/java/
│   ├── adapters/              # Service adapters for different operations
│   │   ├── BackendServiceSendMoneyAdapter.java
│   │   ├── BackendServiceAirtimeAdapter.java
│   │   ├── BackendServicePayWithMoMoAdapter.java
│   │   ├── BackendServicePaymentsAdapter.java
│   │   ├── BackendServiceSavingsLoansAdapter.java
│   │   ├── BackendServiceInvestInsureAdapter.java
│   │   ├── BackendServiceFinancialServicesAdapter.java
│   │   ├── BackendServiceJsonAdapter.java
│   │   └── BackendServiceXmlAdapter.java
│   ├── core/                  # Core business logic
│   │   ├── BackendService.java
│   │   ├── Menu.java
│   │   ├── MenuSystem.java
│   │   └── MenuSystemImpl.java
│   ├── handlers/              # HTTP request handlers
│   │   ├── Rest*Handler.java  # REST endpoint handlers
│   │   └── Xml*Handler.java   # XML endpoint handlers
│   └── ui/                    # User interface controllers
│       ├── AdminController.java
│       ├── BackendServer.java
│       └── MoMoUSDDApplication.java
├── src/main/resources/
│   └── templates/             # Thymeleaf templates
│       ├── admin.html         # Main dashboard
│       ├── users.html         # User management
│       ├── services.html      # Service overview
│       ├── transactions.html  # Transaction management
│       ├── api-docs.html      # API documentation
│       └── [service-name].html # Individual service pages
├── pom.xml                    # Maven configuration
├── API_DOCUMENTATION.md       # Comprehensive API guide
└── README.md                  # This file

Design Patterns

• Adapter Pattern: Service adapters for different operation types
• MVC Pattern: Spring Boot controllers with Thymeleaf templates
• Repository Pattern: Data access abstraction
• Factory Pattern: Service creation and management

🎯 Use Cases

🏦 Financial Institution Testing

• Service Validation: Test mobile money services before production deployment
• Load Testing: Simulate high transaction volumes
• Integration Testing: Validate third-party integrations
• Compliance Testing: Ensure regulatory compliance

🎓 Educational Platform

• Computer Science: Learn about distributed systems and API design
• Fintech Training: Understand mobile money ecosystem
• Software Engineering: Study clean architecture and design patterns
• API Development: Practice RESTful service development

🔧 Development Framework

• Prototype Development: Rapid prototyping of mobile money features
• API Testing: Test client applications against realistic endpoints
• Documentation: Generate comprehensive API documentation
• Mock Services: Development environment for mobile money apps

📊 Research & Analytics

• Transaction Pattern Analysis: Study mobile money usage patterns
• Service Performance: Analyze service response times and reliability
• User Behavior: Understand mobile money user interactions
• Market Research: Simulate different market scenarios

🔧 Configuration

Database Configuration

# H2 Database (default)
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driverClassName=org.h2.Driver
spring.datasource.username=sa
spring.datasource.password=

# MySQL Configuration (production)
spring.datasource.url=jdbc:mysql://localhost:3306/sparrow
spring.datasource.username=your_username
spring.datasource.password=your_password

Application Properties

# Server Configuration
server.port=8080
server.servlet.context-path=/

# Logging
logging.level.org.springframework=INFO
logging.level.ui=DEBUG

# Thymeleaf Configuration
spring.thymeleaf.cache=false
spring.thymeleaf.enabled=true

🔌 API Reference

Authentication

All endpoints support form-based authentication. No API key required for development.

Base URL

http://localhost:8080

Core Endpoints

User Management

• POST /admin/addUser - Create new user
• GET /api/users - Get all users (JSON)
• GET /api/users/xml - Get all users (XML)
• POST /api/users/balance - Get user balance
• POST /api/users/transactions - Get user transactions

Service Operations

• POST /admin/sendMoney - Send money between users
• POST /admin/buyAirtime - Purchase airtime
• POST /admin/payWithMoMo - Pay merchant
• POST /admin/payBill - Pay utility bills
• POST /admin/savingsLoans - Savings and loan operations
• POST /admin/investInsure - Investment and insurance services

For detailed API documentation with examples, visit: /admin/api-docs

🧪 Testing

Unit Tests

mvn test

Integration Tests

mvn verify

API Testing

Use the built-in API documentation page or tools like Postman:

• Import the API collection from /admin/api-docs
• Test all endpoints with sample data
• Validate JSON and XML responses

🚀 Deployment

Production Deployment

1. Build the JAR

   mvn clean package
   

2. Run the application

   java -jar target/sparrow-1.0.0.jar
   

3. Configure production database

   java -jar target/sparrow-1.0.0.jar --spring.datasource.url=jdbc:mysql://localhost:3306/sparrow
   

Cloud Deployment

• AWS: Deploy to Elastic Beanstalk or ECS
• Google Cloud: Use App Engine or Cloud Run
• Azure: Deploy to App Service or Container Instances
• Heroku: Direct deployment with Maven support

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name
   

3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass

   mvn test
   

6. Submit a pull request

Code Standards

• Follow Java naming conventions
• Add JavaDoc comments for public methods
• Write unit tests for new features
• Use consistent code formatting
• Update documentation for API changes

Bug Reports

Please include:

• Java version and OS
• Steps to reproduce
• Expected vs actual behavior
• Stack traces if applicable

📈 Roadmap

Version 2.0 (Upcoming)

• Real-time Notifications: WebSocket support for live updates
• Advanced Analytics: Transaction pattern analysis and reporting
• Multi-currency Support: Handle multiple currencies and exchange ra