Mosque Management System (MMS)

A comprehensive management system for mosques, built with Django and Wagtail.

Features

• Membership Management: Track families, members, and vital records (Nikah, Janazah, etc.).
• Finance: Manage donations, expenses, and membership dues.
• Education: Manage classes, teachers, and student enrollments.
• Operations: Prayer times, auditorium bookings, and digital signage.
• Home/Dashboard: Executive dashboard with key metrics.

User Roles

The system categorizes users into several roles across different modules:

System User Types

Primary roles for dashboard and module management:

• Administrator: Full system access.
• Executive Board Member: High-level oversight and reporting.
• Department Manager: Specific module management (Finance, HR, etc.).
• Staff Member: Standard operational access.
• Volunteer: Restricted access for specific tasks.

Staff Positions (HR)

Specific roles for mosque employees:

• Imam / Assistant Imam
• Muazzin
• Teacher
• Administrator
• Maintenance / Cleaner
• Security Guard

Trustee & Committee Roles

Leadership and governance roles:

• Trustees: President, Vice President, Secretary, Treasurer.
• Committee: Chairperson, Secretary, Minute Taker.

Setup Instructions

Follow these steps to set up the project on a new machine.

Prerequisites

• Python 3.10+
• Git

1. Clone the Repository

git clone <repository-url>
cd mms_v1

2. Set Up Virtual Environment

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Environment Configuration

The project uses django-environ for configuration. Create a .env file in the project root:

cp .env.example .env  # Or create it manually

Update your .env with your local database credentials.

5. Setup Database

The system uses PostgreSQL for both local development and production. It supports switching between multiple database environments (e.g., local-dev, remote-dev1).

1. Configure Database Credentials: Update DATABASE_URL in .env for your local database:

DATABASE_URL=postgres://postgres:Password1!@127.0.0.1:5432/mms_v1

2. Switching Environments: The application defaults to local-dev. To switch to a different database (e.g., remote-dev1), set the SELECTED_DATABASE environment variable in your .env file or shell:

# In .env file
SELECTED_DATABASE=remote-dev1

3. Apply Migrations: Ensure you apply migrations to the selected database:

# Example: Apply migrations to the currently selected database (from .env)
python manage.py migrate

# Example: One-off command for a specific database
SELECTED_DATABASE=remote-dev1 python manage.py migrate

4. MySQL Configuration (Optional): To use MySQL instead of PostgreSQL:

1. Install MySQL server and create a database:

   CREATE DATABASE mms_v1 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. Add MYSQL_DB_URL to your .env file:

   MYSQL_DB_URL=mysql://username:password@localhost:3306/mms_v1

3. Switch to MySQL by setting:

   SELECTED_DATABASE=mysql-dev

4. Install the MySQL client library:

   pip install mysqlclient

Seed Sample Data:

python manage.py populate_sample_data

6. Database Migrations

When you make changes to models, you need to create and apply migrations to update your database schema.

1. Create Migrations: Generate migration files based on your model changes:

python manage.py makemigrations

2. Apply Migrations: Apply the generated migrations to the selected database:

python manage.py migrate

3. Check Status (Optional): To see which migrations have been applied:

python manage.py showmigrations

7. Create Admin User

# Superuser credentials are pre-configured if using sample data:
# Username: admin / Password: adminpassword
python manage.py createsuperuser  # To create a new one

8. Run the Server

python manage.py runserver

Deployment & Production

For detailed instructions on deploying to Google Cloud Run and Cloud SQL, refer to the walkthrough.md.

PythonAnywhere (quick deploy)

# 1) Pull latest code
git pull

# 2) Activate venv
source ~/.virtualenvs/<your-venv-name>/bin/activate
eg:- source /home/shajeebsh/.virtualenvs/.env/bin/activate

# 3) Install deps (if changed)
pip install -r requirements.txt

# 4) Apply DB migrations
python manage.py migrate

# 5) Static files
python manage.py collectstatic --noinput

Then go to the Web tab in PythonAnywhere and click Reload.

Accessing the Application

• Website: http://127.0.0.1:8000
• Admin Panel: http://127.0.0.1:8000/cms/

Running Tests

The project includes comprehensive test suites for models, views, and business logic. Here's how to run them:

Run All Tests

python manage.py test

Run Tests for a Specific App

# Run all membership tests
python manage.py test membership

# Run all finance tests
python manage.py test finance

Run Specific Test Files

# Run model tests
python manage.py test membership.tests

# Run view integration tests
python manage.py test membership.test_views

# Run business logic tests
python manage.py test membership.test_business_logic

Run Specific Test Classes or Methods

# Run a specific test class
python manage.py test membership.tests.FamilyModelTest

# Run a specific test method
python manage.py test membership.tests.FamilyModelTest.test_family_creation

Test Options

Verbose Output (recommended for seeing test details):

python manage.py test membership --verbosity=2

Keep Test Database (faster for repeated test runs):

python manage.py test membership --keepdb

Run Tests in Parallel (faster execution):

python manage.py test membership --parallel

Run Tests with Coverage (if coverage.py is installed):

coverage run --source='.' manage.py test membership
coverage report
coverage html  # Generates HTML report in htmlcov/

Test Structure

The test suite includes:

• Unit Tests (membership/tests.py, finance/tests.py): Test individual model functionality, validations, and properties
• Integration Tests (membership/test_views.py): Test view functionality, HTTP requests, and user interactions
• Business Logic Tests (membership/test_business_logic.py): Test critical business logic like payment processing and dues calculations
• Automated E2E Tests (tests/e2e/): Browser-based testing using Playwright and Pytest

Running Automated E2E Tests (Playwright)

The system includes automated browser tests for end-to-end verification covering CRUD operations for all major modules:

• Membership (Families, Members)
• Finance (Donations, Expenses)
• Accounting (Chart of Accounts, Ledger)
• Billing (Invoices, Payments)
• Education (Teachers, Classes)
• Assets (Shops, Property Units)
• Operations (Bookings, Prayer Times)
• HR (Staff, Positions)
• Committee (Committees, Trustees)
• Sample Data

1. Install Test Dependencies:

   pip install pytest-playwright
   playwright install chromium

2. Run E2E Tests: Ensure the development server is running in another terminal (python manage.py runserver), then run the full suite:

   pytest tests/e2e/

   Or run specific module tests:

   pytest tests/e2e/test_membership.py
   pytest tests/e2e/test_finance.py
   # ...and so on for other modules

3. Generate Test Report

To generate a comprehensive HTML report of the test results:

pytest tests/e2e/ --html=report.html

This will create a report.html file in the project directory which you can open in your browser.

Configuration

• Membership Dues: Go to Settings > System settings in the admin panel to configure the default monthly dues amount.

Testing New Features

Non-member Donations

1. Start the development server:

   python manage.py runserver

2. Create a Non-member Donation:

   • Go to CMS admin: http://localhost:8000/cms/
   • Navigate to Finance > Donations > Add New Donation
   • Leave the "Member" field blank
   • Enter a name in the "Donor Name" field (e.g., "John Smith")
   • Fill in amount, category, donation type, and date
   • Save the donation
   • Verify the donation appears in the list with the donor name displayed

3. Create a Member Donation:

   • Add another donation but select a Member from the dropdown
   • Leave "Donor Name" blank
   • Save and verify the member's name is displayed in the list

4. Verify Donation List Display:

   • Go to Finance > Donations
   • Confirm both member and non-member donations display correctly
   • Search for the non-member donor name to verify search functionality

Pending Course Fees Report

1. Setup Test Data (if not already present):

   • Create a Class with a course fee (Education > Classes > Add)
   • Enroll a student in the class (Education > Student Enrollments > Add)
   • Set payment status to "Pending" or "Partial"

2. View Pending Fees Report:

   • Navigate to Education > Pending Course Fees
   • Verify student names display correctly in the table
   • Check that the following columns show proper data:
     • Student Name (should show full name, not object reference)
     • Class name
     • Total Fee, Paid amount, Balance
     • Payment status (Pending/Partial)
     • Contact phone number

3. Test with Partial Payment:

   • Add a fee payment for a student (Education > Student Fee Payments > Add)
   • Pay less than the total course fee
   • Refresh the Pending Fees report
   • Verify the student shows "Partial" status with updated Paid and Balance amounts

4. Test Full Payment:

   • Add another payment to complete the full fee
   • Verify the student no longer appears in the Pending Fees report