MKAASH Database - Tajneed & Membership Management System

A unified Tajneed and Membership Management System for Majlis Khuddamul Ahmadiyya (MKAASH) - Ashanti Region

Production-ready • Secure • Real-time • Mobile-responsive

Features • Quick Start • Architecture • Contributing

Overview

MKAASH Database is a comprehensive member and organizational management platform designed specifically for Majlis Khuddamul Ahmadiyya. It provides a unified system for managing members, tracking contributions, coordinating regional activities, and distributing communications across the Ashanti Region.

Key Capabilities:

Member directory and detailed member profiles with granular permission controls
Payment tracking with automatic receipt generation and archival
Multi-level organizational hierarchy (Zones, Circuits, Khadim, Tifl)
Advanced analytics and reporting dashboards
Real-time broadcast messaging and member communications
Secure admin controls with role-based access (Regional Admin, Zonal QAid, Circuit QAid)

Status: Production-ready • Actively maintained • Version 1.0+

Screenshots

Landing Page

Dashboard preview and system overview

Authentication

Secure admin-only authentication with The Khuddam Pledge

Features

Member Management

Create, view, edit, and archive member records
Auto-calculated membership tiers (Khadim, Atfal, Tifl)
Support for AIMS number tracking and Waqfe Nau status
Bulk import/export with CSV templates
Member search and advanced filtering
Personal details including occupation, marital status, emergency contacts
Member activity history and audit trail

Payment & Contributions

Record contributions tied to contribution types
Payment history with full reconciliation
Automatic PDF receipt generation and printing
Receipt templates with organization branding
Payment export for accounting systems
Multi-user payment entry with validation

Organizational Structure

Manage Zones and Circuits with hierarchy
Define contribution types and categories
Track organizational metrics (membership by tier, payment distribution)
Region-wide statistics and health metrics
GDPR-compliant data archival

Admin Dashboard

Real-time member and payment metrics
Membership growth charts and trends
Contribution analysis by type and period
Graduation list management
User management and role assignment
Complete settings configuration panel

Zonal & Circuit Operations

Zonal-specific dashboards with scoped data
Circuit-level member management
Regional broadcast coordination
Localized reporting and analytics

Broadcast Messaging

Compose SMS broadcasts to member groups
Integration with Arkesel for SMS delivery
Delivery status tracking
Message template library
Scheduled broadcasting (queue-based)

Security & Compliance

Supabase Auth with secure session management
Role-based access control (RBAC) with RLS policies
Session timeout with inactivity tracking
Password change and login history
Activity logging and audit trail
GDPR data export and deletion compliance

Tech Stack

Layer	Technology	Purpose
Frontend	React 19 • Vite • TypeScript	UI and routing
Styling	Tailwind CSS v4 • Shadcn/ui	Design system and components
State	TanStack React Query • SWR	Data fetching and caching
Backend	Supabase PostgreSQL	Database and auth
Real-time	Supabase Realtime	Live data updates
PDF	jsPDF + jsPDF-AutoTable	Receipt generation
SMS	Arkesel API	Broadcast messaging
Error Tracking	Sentry	Observability
Mobile	Capacitor	Android native packaging

Quick Start

Prerequisites

Node.js 18+ and npm 9+
Supabase account (free tier sufficient)
Git

Installation

Clone the repository

git clone https://github.com/Partey123/mkaashdatabase.git
cd mkaashdatabase

Install dependencies
```
npm ci
```

Configure environment

cp .env.example .env

Add your Supabase credentials:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

Start development server
```
npm run dev
```
Open http://localhost:5173 in your browser.

Environment Variables

Required:

VITE_SUPABASE_URL          # Supabase project URL
VITE_SUPABASE_ANON_KEY     # Supabase anonymous key

Optional:

VITE_SENTRY_DSN            # Sentry error tracking
VITE_ARKESEL_API_KEY       # SMS gateway credentials
VITE_APP_VERSION           # App version for UI display

Note: Never commit .env files. Use secure CI/CD secrets for sensitive keys.

Project Structure

mkaashdatabase/
├── src/
│   ├── pages/
│   │   ├── landing/              # Public landing page
│   │   ├── auth/                 # Sign in/sign up flows
│   │   └── dashboard/
│   │       ├── admin/            # Admin dashboard pages
│   │       │   ├── admindashboard.tsx
│   │       │   ├── members-page.tsx
│   │       │   ├── payments-page.tsx
│   │       │   ├── broadcasts-page.tsx
│   │       │   ├── reports-page.tsx
│   │       │   ├── analytics-page.tsx
│   │       │   ├── users-page.tsx
│   │       │   └── settings-page.tsx
│   │       └── zonal/            # Zonal dashboard pages
│   ├── components/
│   │   ├── ui/                   # Reusable UI components
│   │   ├── forms/                # Form components
│   │   └── dashboard/            # Dashboard-specific components
│   ├── lib/
│   │   ├── queries.ts            # React Query configuration
│   │   ├── receipt-generator.ts  # PDF generation
│   │   ├── format.ts             # Data formatting utilities
│   │   ├── sentry-init.ts        # Error tracking
│   │   └── ...                   # Other utilities
│   ├── integrations/
│   │   ├── supabase/             # Supabase client
│   │   └── arkesel/              # SMS gateway client
│   └── App.tsx                   # Router and auth setup
├── supabase/
│   └── migrations/               # Database schema migrations
├── android/                      # Capacitor Android project
└── docs/                         # Documentation and guides

Key Features Deep Dive

Member Tiers

Members are automatically classified based on age and Quranic knowledge:

Tifl: Age 7-16, beginning Quranic studies
Khadim: Age 16-40, active membership
Atfal: Age 40+, senior membership
Auto-graduated: System auto-promotes members based on age

Payment System

Flexible contribution types (regular, special, donations)
Per-member and per-circuit payment tracking
Multi-currency support (GHS, USD, EUR)
PDF receipt generation with member details and tax codes
Payment reconciliation and audit trail

Role-Based Access

Role	Permissions
Regional Admin	Full system access, user management, all operations
Zonal QAid	Zone-scoped operations, member management, payments
Circuit QAid	Circuit-scoped member management and payments

Real-Time Updates

Live member list updates across all clients
Real-time payment confirmations
Broadcast delivery status updates
Admin activity notifications

Development

Available Scripts

npm run dev          # Start development server
npm run build        # Build production bundle
npm run preview      # Preview production build
npm run lint         # Run ESLint
npm run format       # Format code with Prettier
npm run test         # Run Vitest tests
npm run type-check   # Check TypeScript types

Mobile Development (Capacitor)

npm run cap:sync     # Sync web assets to native project
npm run cap:open     # Open Android Studio
npm run cap:build    # Build and sync for native packaging

Database Migrations

Migrations are versioned SQL files in supabase/migrations/:

# Run migrations (via Supabase CLI)
supabase db push

# Create new migration
supabase migration new add_feature_name

Performance & Optimization

Frontend

Production build: 1.02s compile time
Navigation: <50ms (96% faster than previous implementation)
Code-splitting with lazy-loaded routes
Image optimization and responsive assets
Automatic caching with React Query

Backend

PostgreSQL full-text search for members
Row-level security (RLS) for data isolation
Connection pooling via Supabase
Indexed queries for fast lookups

Rendering

Server-side Suspense boundaries with skeleton loaders
No global spinners (component-level loading states)
Distributed vertical sidebar layout (no scrollbars)
Responsive design for desktop, tablet, mobile

Database Schema

Core Tables

users - Supabase Auth integration
user_roles - Role assignments for RBAC
members - Member records
payments - Payment transactions
zones - Geographic organization units
circuits - Sub-zones within zones
contribution_types - Payment categories
organization_settings - System configuration
user_sessions - Active session tracking
login_history - Security audit trail

Security

Row-level security (RLS) policies on all sensitive tables
Automatic updated_at timestamps
Soft deletes for audit compliance
Encrypted sensitive fields
User UUID isolation for multi-tenancy

See supabase/migrations/ for complete schema.

Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel deploy --prod

Environment Variables: Configure in Vercel project settings.

Self-Hosted

npm run build
# Deploy dist/ folder to any static host

Mobile (Android)

Build production web assets: npm run build
Sync to native: npm run cap:build
Open Android Studio: npm run cap:open
Build APK/AAB through Android Studio

Contributing

We welcome contributions! Please follow these guidelines:

Create a feature branch

git checkout -b feature/your-feature-name

Make changes and test

npm run lint          # Check code quality
npm run format        # Format code
npm run test          # Run tests

Commit with clear messages

git commit -m "feat: Add member import from CSV"

Push and create a Pull Request

git push origin feature/your-feature-name

Pull Request Checklist

Tests pass (npm run test)
Linter passes (npm run lint)
Code is formatted (npm run format)
TypeScript types are correct (npm run type-check)
Changes are documented
Database migrations included (if applicable)

Roadmap

Phase 1 (Complete)

Core member management
Payment tracking and receipts
Admin dashboard and analytics
SMS broadcasting
Multi-role access control

Phase 2 (In Progress)

Session timeout enforcement
Advanced notification preferences
Organization settings UI
Data backup and export
Password change and security
Login history tracking

Phase 3 (Planned)

Two-factor authentication (2FA)
API key management for integrations
Advanced audit logging
Webhook support
Mobile app release (iOS)
Offline mode with sync

Phase 4 (Future)

AI-powered member insights
Predictive analytics
Multi-region deployment
White-label options
Advanced scheduling

Troubleshooting

Build Issues

# Clear dependencies and reinstall
rm -rf node_modules package-lock.json
npm ci

# Check Node version (requires 18+)
node --version

Database Connection

Ensure .env has valid Supabase credentials:

VITE_SUPABASE_URL=https://xxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...

Port Conflicts

Dev server defaults to port 5173. Change with:

npm run dev -- --port 3000

Authentication Issues

Clear browser cookies and localStorage
Verify user has proper role in user_roles table
Check RLS policies in Supabase dashboard

Security

Best Practices

All database access uses Row-Level Security (RLS)
Session tokens expire after 30 minutes of inactivity
Passwords hashed with Supabase Auth
API keys never committed to version control
HTTPS enforced in production
CORS configured for allowed origins

Reporting Security Issues

If you discover a security vulnerability, please email security@mkaash.org instead of opening a public issue.

Performance Metrics

Frontend

Metric	Before	After	Improvement
Navigation Speed	2-3s	<50ms	96% faster
Build Time	1.5s	936ms	38% faster
Route Load	2500ms	<100ms	96% faster

Backend

Metric	Value
Auth Check	<10ms
Member Query	<50ms
Payment Sync	<100ms
Report Generation	<500ms

License

For licensing inquiries, contact: admin@mkaash.org

Support

Getting Help

Documentation: See docs/ directory
Issues: Open a GitHub issue for bugs and feature requests
Email: admin@mkaash.org
Slack: Contact regional coordinator

Community

Contributors: See CONTRIBUTING.md
Changelog: See CHANGELOG.md for version history

Credits

Built with ❤️ by the MKAASH Development Team

Tech Sponsors:

Vercel - Hosting and deployment
Supabase - Database and auth
Sentry - Error tracking
Arkesel - SMS gateway

Design & UX:

Shadcn/ui - Component library
Tailwind CSS - Styling

Version 1.0 • Changelog • License

Made with care for MKAASH Ashanti Region

Name		Name	Last commit message	Last commit date
Latest commit History 254 Commits
.builder		.builder
.github/workflows		.github/workflows
android		android
data		data
docs		docs
src		src
supabase		supabase
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONVERSION_SUMMARY.txt		CONVERSION_SUMMARY.txt
FEATURES_SUMMARY.txt		FEATURES_SUMMARY.txt
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
capacitor.config.ts		capacitor.config.ts
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
mkaash-members-converted.csv		mkaash-members-converted.csv
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

MKAASH Database - Tajneed & Membership Management System

Overview

Screenshots

Landing Page

Authentication

Features

Member Management

Payment & Contributions

Organizational Structure

Admin Dashboard

Zonal & Circuit Operations

Broadcast Messaging

Security & Compliance

Tech Stack

Quick Start

Prerequisites

Installation

Environment Variables

Project Structure

Key Features Deep Dive

Member Tiers

Payment System

Role-Based Access

Real-Time Updates

Development

Available Scripts

Mobile Development (Capacitor)

Database Migrations

Performance & Optimization

Frontend

Backend

Rendering

Database Schema

Core Tables

Security

Deployment

Vercel (Recommended)

Self-Hosted

Mobile (Android)

Contributing

Pull Request Checklist

Roadmap

Phase 1 (Complete)

Phase 2 (In Progress)

Phase 3 (Planned)

Phase 4 (Future)

Troubleshooting

Build Issues

Database Connection

Port Conflicts

Authentication Issues

Security

Best Practices

Reporting Security Issues

Performance Metrics

Frontend

Backend

License

Support

Getting Help

Community

Credits

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages