A community-based lending platform with blockchain integration for transparent and secure loan management in African communities.

Chamaa.API is an open-source platform enabling community-driven savings groups (chamas) with transparent ledger systems, blockchain-secured transactions, and mobile-first access. The project implements a full-stack monorepo with a Spring Boot backend and Android mobile application.

• User Management - Registration, authentication, and profile management
• Group Management - Create and manage community lending groups (chamas)
• Loan System - Request, approve, and track loans within groups
• Wallet & Transactions - Deposit, withdraw, and transaction history
• Blockchain Integration - Polygon network integration for transparent transactions
• Android Mobile App - Native Android application with offline support
• Payment Integration - M-Pesa, Airtel Money, PayPal support (planned)

chamaa.api/
├── apps/
│   ├── backend/                    # Spring Boot REST API
│   │   ├── src/main/java/com/chamaa/
│   │   │   ├── blockchain/         # Blockchain integration (Web3j)
│   │   │   ├── common/            # Shared utilities & exceptions
│   │   │   ├── config/            # Configuration classes
│   │   │   ├── controllers/       # REST API endpoints
│   │   │   ├── entities/          # JPA entities
│   │   │   ├── repositories/      # Data access layer
│   │   │   └── services/          # Business logic
│   │   └── pom.xml
│   │
│   └── android/
│       └── ChamaApp/              # Android mobile app
│           └── app/
│               └── src/main/java/com/example/chama/
│                   ├── network/   # Retrofit + OkHttp client
│                   ├── models/    # Data models
│                   └── ui/        # Jetpack Compose screens
│
├── docs/                          # Documentation
│   ├── api-spec.md               # API specification
│   ├── architecture.md           # Architecture overview
│   ├── blockchain.md             # Blockchain integration guide
│   ├── DATABASE_SETUP.md         # Database configuration
│   ├── DOCKER_GUIDE.md           # Docker deployment guide
│   └── CI_CD_PIPELINE.md         # CI/CD documentation
│
├── infra/                        # Infrastructure configurations
├── .github/                      # GitHub Actions workflows
├── README.md                     # This file
├── ROADMAP.md                    # Project roadmap
├── CONTRIBUTING.md               # Contribution guidelines
└── LICENSE                       # MIT License

1. Clone the repository

   git clone https://github.com/flow-pie/chamaa.api.git
   cd chamaa.api

2. Configure environment variables

   cp .env.example .env
   # Edit .env with your configuration

3. Run the backend

   cd apps/backend
   ./mvnw spring-boot:run

   The API will be available at http://localhost:8080/api

4. Run tests

   cd apps/backend
   ./mvnw clean test

1. Open in Android Studio

   apps/android/ChamaApp
   

2. Build the debug APK

   cd apps/android/ChamaApp
   ./gradlew assembleDebug

3. Install on emulator/device

   ./gradlew installDebug

   Note: For emulator, the app connects to host machine at 10.0.2.2:8080

# Backend only with H2 (development)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Full stack with PostgreSQL
docker-compose up

See DOCKER_GUIDE.md for detailed Docker configuration.

# Create a user
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+254712345678"
  }'

# Create a group
curl -X POST http://localhost:8080/api/groups \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Community Savings",
    "description": "Monthly savings group",
    "creatorId": 1,
    "targetAmount": 10000.0
  }'

# Request a loan
curl -X POST http://localhost:8080/api/loans \
  -H "Content-Type: application/json" \
  -d '{
    "borrowerId": 1,
    "groupId": 1,
    "amount": 5000.0,
    "durationInMonths": 12,
    "purpose": "Business expansion"
  }'

# Development (H2 in-memory)
./mvnw spring-boot:run

# Production (PostgreSQL)
SPRING_PROFILES_ACTIVE=prod ./mvnw spring-boot:run

See .env.example for all available configuration options.

• Backend: Follows Spring Boot conventions, Google Java Style
• Android: Kotlin coding conventions, Jetpack Compose guidelines

# Backend unit tests
cd apps/backend
./mvnw test

# Backend tests with coverage report
./mvnw clean test jacoco:report

# Run specific test class
./mvnw test -Dtest=UserServiceTest

# Run specific test method
./mvnw test -Dtest=UserServiceTest#testCreateUser

The application uses the following core entities:

• User - User accounts with authentication
• Group - Community lending groups
• Loan - Loan records within groups
• Wallet - User wallet with balance tracking
• Transaction - Transaction history

See DATABASE_SETUP.md for detailed schema documentation.

We welcome contributions! Please read our Contributing Guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run tests and ensure code quality
5. Commit with conventional commits: git commit -m "feat: add new feature"
6. Push and create a Pull Request

We follow Conventional Commits:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat(wallet): add transaction history endpoint
fix(api): resolve user authentication bug
docs(readme): update setup instructions

The project is organized into 8 phases. See ROADMAP.md for detailed progress and future plans.

• 📖 API Documentation
• 🏗️ Architecture Guide
• ⛓️ Blockchain Integration
• 🐳 Docker Guide
• 📊 Database Setup
• 🔄 CI/CD Pipeline

• 💬 Discord
• 💻 GitHub Discussions
• 🐛 Issue Tracker

This project is licensed under the MIT License - see LICENSE for details.

• Spring Boot
• Jetpack Compose
• Web3j
• All contributors and community members

Built with ❤️ by the Chamaa community