Musafir Charity Platform

1.Introduction

Charitable giving is an act of trust. Donors extend financial resources to organisations they believe will steward those funds responsibly and direct them toward causes that genuinely need support. The problem is not the willingness to give. It is the absence of a mechanism to verify, independently and conclusively, that the money reached where it was promised to go.

The Musafir Charity Platform was conceived to close this gap. Built within and for the Musafir community, it provides a structured system through which donors submit proof of payment, administrators verify those submissions, and funds are transparently allocated to named causes, with every step recorded, timestamped, and queryable by any interested party.

This document describes the technical design of the platform: its data model, operational protocols, security architecture, and the mechanisms by which auditability is guaranteed.

2.The Transparency Problem

Informal community charity pools, common across diaspora communities worldwide, typically operate through a single trusted individual or group who collects funds, decides on causes, and distributes money. This model has three structural weaknesses:

• Single point of failure. If the custodian is unavailable, corrupted, or simply disorganised, the entire operation is compromised.
• No audit trail. Without formal records, donors cannot trace whether their contribution was received, verified, or used.
• Trust-dependent accountability. Accountability exists only insofar as trust in a specific person exists. It does not survive personnel changes.

The Musafir Charity Platform replaces these trust assumptions with protocol assumptions. Every action (donation, verification, allocation) is recorded in a relational database with immutable audit logs. The protocol itself becomes the guarantor of integrity; not any individual person.

3.System Overview

The platform is a web application built on Next.js (App Router) and hosted on Vercel's global edge network. All persistent state lives in a PostgreSQL database managed by Supabase, which also provides authentication, file storage, and row-level security enforcement.

Architecture

Requests flow through four distinct layers before reaching persistent storage. Each layer enforces its own security guarantees independently of the others.

Participants

The system recognises three participant roles, each with a distinct scope of permitted actions:

Public Transparency

In addition to authenticated participants, the platform exposes a public Transparency Dashboard at /transparency where any visitor, without logging in, can view aggregated donation statistics, recent verified donations, and fund allocation records. This ensures that community accountability does not depend on being a registered user.

4.Donation Protocol

A donation in the Musafir system is not a simple payment record. It is a structured protocol with defined states, required evidence, and an explicit lifecycle that terminates only when the funds are fully allocated and the donor has been notified.

Submission

The donor initiates a donation outside the platform using one of the supported payment channels: JazzCash, Easypaisa, or direct bank transfer. After completing the off-platform payment, the donor submits the following evidence through the platform dashboard:

• Donation amount (numeric, PKR)
• Payment method (JazzCash / Easypaisa / Bank Transfer)
• Transaction reference number
• Payment screenshot (PNG, JPEG, or WebP; max 5 MB)

The screenshot is stored in an isolated Supabase Storage bucket (donation-screenshots) with a sanitised path keyed to the donation record. The platform performs server-side MIME type validation and size enforcement before accepting the upload.

Donation States

Every donation record carries a verification_status field which progresses through one of two possible paths. The state transitions are irrevocable once an administrator acts on a submission.

A donation enters the pending state immediately upon submission. It remains there until an administrator reviews it. Once reviewed, it moves irrevocably to either approved or rejected. Approved donations are eligible for fund allocation; rejected donations are preserved in the audit log with a stated reason.

Public Identifiers

Each donation is assigned a public_id: a short, human-readable unique identifier that serves as a donation receipt reference. Donors can share this identifier with third parties to independently verify their contribution through the public receipt endpoint at /donation/[public_id], without exposing their private account information.

5.Verification System

Verification is the critical control step. Before any funds enter the pool, an administrator must manually review the submitted payment evidence and confirm that the stated transaction occurred.

Verification Review

Administrators access the verification queue through a protected admin dashboard, secured by Supabase session authentication, a server-issued HTTP-only cookie, and optional time-based two-factor authentication (TOTP, RFC 6238). The queue shows all pending donations with the submitted screenshot, stated amount, payment method, and transaction reference.

The administrator makes a binary decision: approve or reject. If rejecting, a reason must be recorded. Both actions are atomic; they update the donation record and create a verification_logs entry in a single database operation.

Audit Immutability

The verification_logs table is an append-only audit trail. It records:

• The donation reference (donation_id)
• The action taken (approved or rejected)
• The reason (mandatory for rejections)
• The identity of the verifying administrator (verified_by)
• A precise UTC timestamp (created_at)

This log cannot be modified or deleted by any authenticated user, including super administrators. It represents a permanent record of every governance decision made on the platform.

Email Notification

Upon verification, the system dispatches an email notification to the donor informing them of the outcome. The notification event is recorded in the email_events table, providing an audit trail for communication as well as funds.

6.Fund Pooling and Allocation

Approved donations do not flow directly to a cause in real time. Instead, they enter a managed pool. This design reflects a practical reality: causes have variable funding requirements, and matching individual donations to causes in real time would create operational complexity without commensurate benefit to donors.

The Pooled Fund

The pool is the aggregate of all approved, unallocated donations. Its size at any moment equals the sum of all amount values where verification_status = 'approved' and allocated_at IS NULL. Administrators can inspect this balance through the admin analytics dashboard. The platform does not custody funds; it records and verifies off-platform transactions and their allocation.

Cause Allocation

When administrators are ready to fund a cause, they create a fund_allocations record specifying the target cause and the amount to be transferred. The system enforces that the allocation amount does not exceed the available pool balance.

Each fund allocation is linked back to the individual donations that funded it, through the donation_allocations junction table. This mapping is computed at allocation time and is permanent. Its existence is what makes the accountability graph possible.

Donor Notification

After funds are allocated, the platform sends an allocation notification email to every donor whose contribution was included. The email references the specific cause funded, the amount of the donor's contribution included in the allocation, and the allocation timestamp.

7.Accountability Graph

The core differentiator of the Musafir platform is its accountability graph: a traversable chain of relational records linking every donor, through their donation, through the allocation, to the specific cause it funded.

Every edge in the graph is a foreign key constraint enforced at the database level. No link in this chain can be broken or forged by any application-layer action, including a compromised admin account.

A donor wishing to verify their contribution can query this graph using their donation's public_id, traversing from their record through allocations to the cause funded. The public Transparency Dashboard exposes aggregated versions of this data; authenticated donors can access their personal allocation trail from the donation history view in their dashboard.

8.Security Model

Row Level Security

Every database table is protected by PostgreSQL Row Level Security (RLS) policies enforced by Supabase. Donors can read and write only their own records. Admins have elevated read access across all donations but are constrained to write-access patterns that match their role. The database enforces these constraints independently of application-layer code; a compromised application cannot bypass them.

Server-Side Token Verification

All server actions verify the caller's identity by calling supabase.auth.getUser() with the provided JWT, which performs a live validation against Supabase Auth. Actions that require admin privileges additionally query the users table to confirm role IN ('admin', 'super_admin') before proceeding. This means role claims in a token are never trusted without database confirmation.

Admin Session Security

Admin sessions are reinforced with a dedicated HTTP-only, SameSite-strict cookie (admin_auth_verified) issued by a server action only after successful authentication and role verification. This cookie is validated by the Next.js middleware on every request to any /admin route. Middleware-level enforcement means access control is applied before any route handler executes.

Administrators may optionally enable time-based two-factor authentication (TOTP) in accordance with RFC 6238. The TOTP secret is stored in a separate admin_security table. The 2FA verification page is intentionally excluded from the middleware cookie check, as the cookie does not yet exist at that stage of the login flow.

Security Headers

All responses carry a comprehensive set of HTTP security headers enforced at the edge by Next.js middleware: Content Security Policy, X-Frame-Options (DENY), X-Content-Type-Options (nosniff), Referrer-Policy, Strict-Transport-Security (HSTS with one-year max-age and subDomain inclusion), and a restrictive Permissions-Policy disabling camera, microphone, and geolocation APIs.

Rate Limiting

Authentication endpoints (/login, /signup) are rate-limited to 5 requests per IP per 60-second window. The public receipt endpoint is limited to 20 requests per IP per 60-second window. These limits are enforced at the middleware layer before any handler code executes.

File Upload Validation

Payment screenshot uploads are validated server-side for MIME type (PNG, JPEG, WebP only) and file size (maximum 5 MB). File storage paths are sanitised to prevent path traversal. These checks are performed independently of client-supplied metadata and cannot be bypassed from the browser.

9.Threat Model

The system is designed to mitigate the following threat categories:

• Fraudulent donation submissions (fake receipts)
• Unauthorized access to administrative routes
• Privilege escalation attempts
• Data tampering at the application layer
• File upload attacks (malicious payloads)
• Denial-of-service attempts on public endpoints

These threats are mitigated through layered controls including verification workflows, Row Level Security enforcement, middleware-based rate limiting, and strict input validation.

10.System Limitations

• Payments occur outside the platform and cannot be cryptographically verified
• Verification relies on human administrative review
• The platform does not custody funds; it records and verifies off-platform transactions
• Infrastructure availability depends on third-party services (Supabase, Vercel)

11.Data Architecture

The platform uses a PostgreSQL relational database with seven core tables. The schema is designed for auditability: every significant event produces a record that can be independently queried.

Three database views (transparency_stats, recent_donations, and recent_allocations) provide pre-computed aggregations for the public Transparency Dashboard, enabling fast read access without exposing raw table data.

12.Technical Stewardship

This contribution reflects a belief that charitable infrastructure should be engineered to the same standard as commercial software, with formal data models, explicit security assumptions, and end-to-end auditability. The decision to release this as a pro-bono contribution means that community funds are directed entirely toward causes, not toward platform costs.

13.Conclusion

The Musafir Charity Platform is a practical implementation of a simple principle: charitable giving should be as transparent as the donors deserve. By encoding every material event (donation, verification, allocation) into an immutable, relational audit trail, the platform creates a system where accountability is structural, not aspirational.

Trust in individuals is minimized and constrained by protocol. It requires only that the database constraints, the Row Level Security policies, the middleware-enforced security headers, and the server-side token verification all behave as specified, and any engineer can verify this by inspecting the published codebase.

That is the standard the platform holds itself to. It is the only standard worth holding.