Reme Backend API

The Reme Backend API is a robust, monolithic application built with Spring Boot that powers the Reme mobile platform. It handles all business logic, data persistence, payment processing, and user authentication, ensuring a secure and reliable experience for group contributions.

Table of Contents

• Overview
• Key Features
• Technology Stack
• Architecture
• Getting Started
• Configuration
• API Documentation
• Database Schema
• Security

Overview

This application serves as the core engine for Reme, managing:

• User identities and authentication via JWT.
• Wallet creation, management, and archiving.
• Transaction processing and verification with Paystack.
• Real-time notifications and email alerts.
• Data consistency and relational integrity.

Key Features

• Authentication: Secure user registration and login using JWT (JSON Web Tokens) with refresh token rotation.
• Wallet Management: Complete lifecycle management for contribution wallets (create, update, close, archive).
• Payment Processing: Integration with Paystack for seamless deposits, including webhook handling for transaction verification.
• Bank Verification: Verification of user bank accounts to ensure accurate fund disbursement.
• Notifications: Email notifications (via Brevo/SMTP) for key account activities.
• Media Management: Image uploads for user avatars and wallet covers using Cloudinary.
• Rate Limiting: Protection against abuse using Redis-based rate limiting.
• Goal Tracking: Calculations for contribution progress, total amount raised, and remaining balance.
• Transactions & Export: Detailed transaction logging and export capabilities for user records.
• Multi-Wallet Funding: Logic to support users contributing to multiple unique wallets simultaneously.
• Auto-Expiration: Scheduled tasks to automatically close wallets when deadlines are reached.

Technology Stack

• Language: Java 17+
• Framework: Spring Boot 3.x
• Build Tool: Maven
• Database: PostgreSQL (Primary Data Store)
• Caching: Redis (Session management, Rate limiting)
• Payment Gateway: Paystack
• Object Storage: Cloudinary
• Email Service: Brevo / JavaMail

Architecture

The project follows a standard layered architecture:

• Controller Layer: Handles incoming HTTP requests and input validation.
• Service Layer: Contains business logic and transaction management.
• Repository Layer: Manages data access and database interactions using Spring Data JPA.
• Security Layer: Configures filter chains, authentication providers, and authorization rules.

Directory Structure

• src/main/java/com/winnerx0/reme/
  • config: Configuration classes (Security, Swagger, Redis, etc.).
  • controller: REST API endpoints.
  • dto: Data Transfer Objects for requests and responses.
  • model: JPA Entities mapping to database tables.
  • repository: Interfaces for database access.
  • service: Business logic interfaces and implementations.
  • security: JWT filters and user details services.
  • utils: Utility classes and exception handlers.

Getting Started

Prerequisites

• Java Development Kit (JDK) 17 or higher
• Maven
• PostgreSQL running locally or via Docker
• Redis running locally or via Docker

Installation

1. Clone the repository and navigate to the project root.
2. Create a .env file in the root directory (see Configuration).
3. Build the project:

   ./mvnw clean install

4. Run the application:

   ./mvnw spring-boot:run

The server will start on port 8080 by default.

External Access (Ngrok)

To test webhooks (e.g., Paystack) or connect from a physical mobile device, use ngrok to tunnel your local server:

1. Install ngrok.
2. Run the tunnel:

   ngrok http 8080

3. Update your Paystack dashboard with the generated HTTPS URL for webhooks.

Configuration

Create a .env file in the root directory with the following variables:

# Database Configuration
DATABASE_URL=jdbc:postgresql://localhost:5432/reme_db
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=password

# Paystack
PAYSTACK_SECRET=sk_test_...
PAYSTACK_PUBLIC_KEY=pk_test_...

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Cloudinary
CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...

# Email (SMTP/Brevo)
SMTP_HOST=smtp-relay.brevo.com
SMTP_PORT=587
SMTP_USERNAME=...
SMTP_PASSWORD=...
BREVO_API_KEY=...

# JWT Token
JWT_SECRET=...
JWT_EXPIRATION=86400000

API Documentation

The API comes with integrated Swagger UI for exploration and testing. Once the application is running, access the documentation at:

http://localhost:8080/swagger-ui/index.html

Database Schema

The application uses PostgreSQL with the following core entities:

• Users: Stores user profile and authentication credentials.
• Wallets: Represents a contribution group/goal.
• Transactions: Records all payments, withdrawals, and transfers.
• Otps: Manages one-time passwords for verification.
• Notifications: Stores user alerts and messages.

Security

• JWT Authentication: All protected endpoints require a valid Bearer token.
• Password Hashing: User passwords are securely hashed before storage.
• Role-Based Access: Granular permissions for Users and Admins.
• CORS: Configured to allow requests from the mobile application.