Mkutano

Comprehensive Application Documentation

Village Savings & Loan Association Management System
with Enterprise NGO/MFI Platform

Version: 0.1.0 (Beta)

Last Updated: February 22, 2026

Deployment: Vercel (Auto-deployed from GitHub)

Repository: dig-software/MKUTANOAPP

Production URL: mkutano-app.vercel.app

Table of Contents

  1. Application Overview
  2. Core Features
  3. System Architecture
  4. Technology Stack
  5. User Roles & Permissions
  6. Data Model
  7. Application Structure
  8. Key Features by Module
  9. Enterprise Edition
  10. Authentication & Security
  11. Offline-First & PWA
  12. Getting Started
  13. Demo Accounts
  14. Deployment & Versioning

Application Overview

Mkutano (meaning "gathering" or "meeting" in Swahili) is an offline-first, mobile-optimized web application designed for women's village savings and loan associations (VSLAs) across Africa.

Core Mission

Enable transparent financial management, accountability, and impact tracking for savings groups through a comprehensive yet intuitive platform that works offline, scales to 1000+ groups, and provides insights for NGO/MFI partners.

Key Statistics

33
Routes in Production
5
User Roles
8+
Dashboard Modules
100%
Progressive Web App

Primary Users

Core Features

Public Marketing Site

Community Dashboard (Savings Groups)

Enterprise Edition (NGO/MFI Platform)

Offline-First Capabilities

Technology Stack

Frontend

Technology Version Purpose
Next.js 14.2.20 React framework with App Router
React 18 UI library
TypeScript 5 Type safety
Tailwind CSS 3.4.1 Styling
Lucide React 0.441.0 Icon library
Recharts 2.12.7 Data visualization
jsPDF 2.5.1 PDF generation

Backend & Database

PWA & Offline

Development Tools

User Roles & Permissions

1. Secretary Role

Primary Responsibility

Manage savings group meetings and member finances

Permissions

  • ✓Create and close meetings
  • ✓Record contributions and loans
  • ✓View all group members
  • ✓Generate reports
  • ✗Cannot manage other groups

Demo Account

Phone: +254700000001

2. Member Role

Primary Responsibility

Track personal savings and loans

Permissions

  • ✓View personal wallet
  • ✓View personal contributions
  • ✓View personal loans
  • ✗Cannot create meetings
  • ✗Cannot edit others' data

Demo Account

Phone: +254700000003

3. NGO Role

Primary Responsibility

Track loan impact across funded groups

Permissions

  • ✓View all funded groups
  • ✓Monitor repayment metrics
  • ✓Access impact analytics
  • ✓View loan portfolio
  • ✗Cannot modify group data

Demo Account

Click "Demo: Maendeleo Foundation" on /enterprise/ngo-login

4. MFI Role

Primary Responsibility

Monitor lending portfolio and disbursement

Permissions

  • ✓View lending portfolio
  • ✓Track disbursements and repayments
  • ✓Monitor group performance
  • ✓View repayment rates
  • ✗Cannot issue loans directly

Demo Account

Click "Demo: Ulinzi MFI for MSMEs" on /enterprise/mfi-login

5. Admin Role

Primary Responsibility

System-wide administration and oversight

Permissions

  • ✓Manage all groups
  • ✓Reset user passwords
  • ✓View complete audit logs
  • ✓System configuration
  • ✓User role assignment

Data Model

Mkutano uses a normalized PostgreSQL database with 12 core tables supporting complete financial tracking.

Core Tables

Table Purpose Key Fields
users User accounts name, phone, email, role
groups Savings groups name, village, secretary_id, member_count
members Group members name, phone, total_saved, wallet_balance
meetings Group meetings date, venue, status, attendance_count
contributions Savings contributions amount, type, member_id, recorded_at
loans Loans issued amount, interest_rate, status, due_date
repayments Loan repayments principal, interest, loan_id, recorded_at
audit_logs Transaction history action, entity, actor_id, timestamp
ngos NGO organizations name, budget, programs
mfis Microfinance institutions name, portfolio_size, active_groups

Data Relationships

users (1) ──── (many) members
                           │
                           └─ (1) groups
                                  │
                                  ├─ (many) meetings
                                  ├─ (many) audit_logs
                                  │
                                  └─ (through MFI relationships)
                                          ngos & mfis

loans ────── (many) repayments
contributions ────── (many) meetings

Security: Row-Level Security (RLS)

All tables are protected by PostgreSQL RLS policies ensuring:

Getting Started

Installation from Source

Prerequisites

Node.js 18+ required
npm --version  # Should be v8 or higher

Clone & Install

git clone https://github.com/dig-software/MKUTANOAPP.git
cd MKUTANO\ APP
npm install

Environment Variables

Create .env.local:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Development Server

npm run dev
# Open http://localhost:3000

Production Build

npm run build
npm start

Deployment on Vercel

  1. Push repository to GitHub
  2. Visit vercel.com and create new project
  3. Select MKUTANOAPP repository
  4. Add environment variables
  5. Click "Deploy"
  6. Automatic deployments on main branch push

✓ Production URL

mkutano-app.vercel.app - Auto-deployed from GitHub main branch

Demo Accounts

Community Savings Group

Role Phone Number Notes
Secretary +254700000001 Creates meetings, manages group
Member +254700000003 Views personal savings/loans

Enterprise Edition

NGO Portal

URL: /enterprise/ngo-login

MFI Portal

URL: /enterprise/mfi-login

Mock Data Included

⚠ Note:

Demo accounts require no password. Click "Demo Account" or "Demo: [Organization]" buttons to login instantly.

Offline-First & Progressive Web App

Progressive Web App (PWA)

Installation

Service Worker

File: public/sw.js

Caching Strategies:

Offline Data Capture

How It Works

  1. User creates meeting with contributions/loans
  2. Data saved to localStorage immediately
  3. Service worker intercepts network request
  4. If online: sync to Supabase
  5. If offline: queue for later
  6. Sync status indicator shows "Offline" or "Synced"

Local Storage Structure

{
  "mkutano_pendingChanges": [
    {
      "type": "contribution",
      "meetingId": "...",
      "groupId": "...",
      "amount": 500,
      "memberId": "...",
      "timestamp": "2026-02-22T10:30:00Z"
    }
  ],
  "mkutano_user": {
    "id": "...",
    "phone": "+254...",
    "role": "secretary",
    "groupId": "..."
  }
}

Demo Mode

Works 100% offline with no authentication:

✓ Works Anywhere

Create savings groups, record meetings, and manage finances even without internet. Data automatically syncs when connection restored.

Enterprise Edition

Dedicated platform for NGOs and Microfinance Institutions to track loan impact, monitor repayment performance, and manage funding allocations.

NGO Portal

Dashboard Home (/dashboard/ngo)

Funded Groups (/dashboard/ngo/groups)

Impact Analytics (/dashboard/ngo/impact)

MFI Portal

Dashboard Home (/dashboard/mfi)

Enterprise Landing Page (/enterprise)

Key Metrics Tracked

Metric NGO Perspective MFI Perspective
Program Budget ✓ Total budget ─ Portfolio size
Funding Allocation ✓ By MFI partner ─ Received from NGO
Repayment Rate ✓ Overall impact ✓ Portfolio performance
Outstanding Balance ✓ By MFI ✓ Total portfolio
Active Borrowers ✓ Across groups ✓ Across portfolio

Authentication & Security

Authentication Methods

Phone-Based (Primary)

Email-Based (Alternative)

Demo Mode

Security Features

Row-Level Security (RLS)

Session Management

Data Protection

Audit Trail

Every action in the system is logged with:

✓ Bank-Grade Security

Mkutano uses enterprise-level security practices with database-level access control, complete audit trails, and secure authentication.

Deployment & Versioning

Current Version

Deployment Environments

Environment URL Deployment
Production mkutano-app.vercel.app Auto-deployed from main branch
Development localhost:3000 Local development server

Build Output

Browser Support

Browser Support
Chrome/Chromium ✅ Full support
Firefox ✅ Full support
Safari (iOS 13+) ✅ Full support
Edge ✅ Full support

Recent Changes

Latest Commit: 4f232a0 (Feb 22, 2026)

Previous Notable Commits

Summary

Mkutano is a comprehensive platform for managing village savings and loan associations with strong offline-first capabilities, enterprise-grade security, and an intuitive interface. The system supports both community groups (VSLA) and enterprise partners (NGO/MFI) through role-based access control and specialized dashboards.

Key Strengths

  • ✓ Offline-first architecture - Works anywhere, anytime
  • ✓ PWA installable - Mobile & desktop app-like experience
  • ✓ Complete audit trail - Full accountability
  • ✓ Multi-platform - Community + Enterprise support
  • ✓ Auto-deployment - Continuous integration from GitHub
  • ✓ Progressive enhancement - Works in any modern browser
  • ✓ Responsive design - Mobile, tablet, desktop
  • ✓ Demo-ready - Test without signup

Getting Started Today

Visit: https://mkutano-app.vercel.app

Login with demo credentials:

For More Information

See specific documentation files in the project root:

© 2026 Dig Software. Mkutano — Empowering Village Savings Communities.

For technical support, visit github.com/dig-software/MKUTANOAPP