Tumani Fitness Gym

Project Objectives

The platform was developed to solve several operational challenges commonly faced by fitness centers.

Business Goals

• Eliminate manual membership tracking

• Automate M-Pesa payment verification

• Prevent subscription expiry errors

• Improve financial reporting

• Increase online member acquisition

• Reduce administrative overhead

Key Features

Public Website

• SEO optimized marketing pages

• Online member registration

• Dynamic pricing

• Contact forms

• Service showcase

Member Management

• Member profiles

• Membership lifecycle tracking

• Subscription management

• Automated renewals

• Status monitoring

Payment System

• M-Pesa STK Push integration

• Webhook processing

• Automatic payment verification

• Subscription stacking

• PDF receipt generation
  

Administration

• Revenue dashboard

• Membership analytics

• Plan management

• Payment monitoring

• Financial reports

System Architecture

flowchart TB
    subgraph ClientLayer["Client Layer (Browser)"]
        PublicWeb["Public Marketing Site\n(/, /about, /contact, /nutrition)"]
        MemberReg["Public Member Registration\n(/register)"]
        AdminDash["Admin Dashboard\n(/dashboard/*)"]
    end

    subgraph SecurityLayer["Security & Gateway Layer"]
        Middleware["Next.js Middleware\n(RBAC & JWT Validation)"]
        NextAuth["NextAuth.js\n(Credentials Auth & Session Token)"]
    end

    subgraph AppLayer["Next.js 15 App Server"]
        ApiPublic["Public APIs\n(POST /api/members, /api/contact)"]
        ApiProtected["Protected Admin APIs\n(/api/members, /api/payments, /api/dashboard)"]
        MpesaEngine["M-Pesa Integration Engine\n(STK Push & Callback Handler)"]
    end

    subgraph DatabaseLayer["Data & Persistence Layer"]
        PrismaORM["Prisma ORM Client"]
        PostgresDB[("PostgreSQL Database\nUsers, Members, Plans, Payments")]
    end

    subgraph ExternalServices["External Cloud Services"]
        MpesaApi["Safaricom Daraja API\n(STK Push Gateway)"]
        ResendApi["Resend Email API\n(Contact Form Dispatcher)"]
    end

    PublicWeb --> Middleware
    MemberReg --> Middleware
    AdminDash --> Middleware

    Middleware -->|Public Access| ApiPublic
    Middleware -->|Admin / Auth Validated| ApiProtected
    Middleware --> NextAuth

    ApiPublic --> ResendApi
    ApiPublic --> PrismaORM
    ApiProtected --> MpesaEngine
    ApiProtected --> PrismaORM

    MpesaEngine <-->|STK Push & Webhook Callback| MpesaApi
    MpesaEngine --> PrismaORM

    PrismaORM <--> PostgresDB

Entity Relational Diagram

erDiagram
    User ||--o| Member : "has profile"
    User ||--o{ Account : "owns"
    User ||--o{ Session : "maintains"
    User ||--o{ Payment : "initiates"

    Member ||--o{ MembershipSubscription : "subscribes via"
    Member ||--o{ Payment : "makes"

    MembershipPlan ||--o{ MembershipSubscription : "defines plan"
    MembershipPlan ||--o{ Payment : "purchased via"

    Payment ||--o| MembershipSubscription : "activates"

    User {
        String id PK
        String email UK
        String username UK
        String firstName
        String lastName
        UserRole role "ADMIN | MEMBER"
        String password
        DateTime createdAt
    }

    Member {
        String id PK
        String userId FK
        String membershipNumber UK
        MembershipStatus membershipStatus "ACTIVE | INACTIVE | SUSPENDED | EXPIRED"
        String emergencyContactName
        String emergencyContactPhone
        String healthConditions
        String fitnessGoals
    }

    MembershipPlan {
        String id PK
        String name
        Int duration "Days"
        Float price "KES"
        Boolean isActive
        String[] features
    }

    MembershipSubscription {
        String id PK
        String memberId FK
        String membershipPlanId FK
        DateTime startDate
        DateTime endDate
        Boolean isActive
        Boolean autoRenew
        String paymentId FK
    }

    Payment {
        String id PK
        Float amount
        PaymentMethod method "CASH | CARD | BANK_TRANSFER | MOBILE_MONEY"
        PaymentStatus status "PENDING | COMPLETED | FAILED | REFUNDED"
        String transactionRef UK "M-Pesa Receipt / Ref"
        String memberId FK
        String membershipPlanId FK
        DateTime paidAt
    }

Engineering Highlights

Automated M-Pesa Payment Processing

Designed a fully automated payment workflow using Safaricom's Daraja API.

Features

• STK Push initiation

• Secure webhook callbacks

• Transaction verification

• Automatic membership activation

• PDF receipt generation

• Idempotent transaction processing

Intelligent Subscription Engine

Implemented a subscription stacking mechanism that preserves remaining membership days during early renewals.

Instead of replacing an active subscription, the system extends the expiration date, ensuring members never lose paid days

Real-Time Business Dashboard

Developed an administrative dashboard providing:

• Revenue analytics

• Active membership tracking

• Payment monitoring

• Subscription insights

• Member lifecycle management

Performance & User Experience

Optimized the application through:

• Server-side rendering

• React Server Components

• Client-side caching

• Optimistic UI updates

• Lightweight PDF generation

• Responsive design

Challenges & Solutions

1. Duplicate M-Pesa callbacks: Implemented idempotent webhook processing inside Prisma transactions

2. Membership renewal conflicts: Developed subscription stacking logic to preserve remaining membership days

3. Server-side PDF overhead: Moved receipt generation to the browser using jsPDF

4. Secure public registration: Applied route-level middleware with role-based access control

Results

The completed platform delivers:

• Automated payment reconciliation

• Real-time membership management

• Secure authentication

• Responsive administration tools

• SEO-optimized public website

• Integrated business analytics

• Streamlined gym operations

Skills Demonstrated

This project highlights experience in:

• Full Stack Development

• Software Architecture

• Payment Gateway Integration

• REST API Development

• Authentication & Authorization

• Database Design

• Cloud-Ready Application Development

• Performance Optimization

• Business Process Automation

• Enterprise Dashboard Development

Project Impact

Tumaini Fitness transformed traditional gym administration into a centralized digital platform by automating payment verification, membership management, and operational reporting. The result is a scalable solution that reduces manual work, improves financial accuracy, and delivers a modern experience for both gym staff and members.