1. System Context Diagram_Architecture

GiveHope Platform: System Context Documentation

1. System Context Diagram

A high-level bird's-eye view of the GiveHope platform and everything it interacts with. It identifies the four key human actors — Guest Donor, Registered Donor, Organisation Donor, and Administrator — alongside five external systems including Stripe, PayPal, Google Auth, Email Provider, and the Database. This diagram answers the question: who uses the system and what does it connect to?

Diagram: System Context Diagram.png

This diagram is a System Context Diagram (often referred to as a Level 0 DFD or C4 Context Diagram) for the GiveHope Platform. Its primary goal is to show the platform as a "black box" and illustrate how it interacts with external users (actors) and third-party systems.

The platform is specialized for Islamic charity, specifically handling Zakat and Sadaqah compliance, which implies high requirements for financial transparency and specific distribution logic.

2. Primary Actors (The Users)

These entities interact directly with the webapp to perform specific goals:

• Guest Donor: A non-authenticated user who can browse campaigns and make one-off donations without the friction of account creation.

• Registered Donor: A full account holder with a dashboard. They can manage recurring donation schedules and view their historical impact.

• Organisation Donor: Represents corporate or institutional entities. They have features for bulk giving and the option to remain anonymous.

• Platform Administrator: The internal "power user" who manages the operational side—creating campaigns, configuring platform settings, and monitoring transaction health.

3. External System Integrations

The diagram highlights five key external dependencies that the platform relies on to function:

Financial & Payments

• Stripe: Handles the heavy lifting for credit/debit card processing and webhooks (real-time payment status updates). Crucially, it manages split-payment scheduling, which is vital for distributing funds between different causes.

• PayPal: Provides an alternative checkout flow, supporting multiple global currencies (USD, EUR, GBP, SEK).

Infrastructure & Security

• Email Service: The communication hub. It triggers transactional emails like donation receipts, "abandoned cart" reminders for donors who didn't finish, and internal admin alerts.

• Google Auth: Uses OAuth 2.0 for Single Sign-On (SSO). This streamlines the "Registered Donor" experience by allowing them to log in with existing Google accounts.

• Database: The "source of truth" for the entire system. It stores structured data for donors, campaigns, transaction logs, and the specific objectives of various causes.

4. Key Data Flows

The arrows indicate how information moves between the components:

• Input (Inbound Arrows): Users send requests to the platform (e.g., "Donate," "Manage Schedule," "Configure Settings").

• Output (Outbound Arrows): The platform sends instructions to external services (e.g., "Charge Card" to Stripe, "Send Receipt" to Email Service).

• Bi-directional (Two-way Arrows): The connection to the Database and Google Auth involves a constant exchange—reading existing data and writing new updates.

Summary Table: Component Responsibilities

🏗️ Architecture Review: Critical Considerations

Since you are building this for a charity specifically handling Zakat and Sadaqah, there are three "hidden" technical risks in this architecture that you should point out to your developers immediately.

1. The "Niyyah" (Intent) & Fund Tagging

In your Database and GiveHope Core logic, the developers must ensure that funds are "tagged" at the moment of entry.

• The Requirement: Zakat funds cannot usually be mixed with Sadaqah or general operational funds in the same bank sub-account.

• Developer Note: "Ensure the database schema supports strict Fund Accounting. Every transaction must have a category_id that is immutable once the payment is captured by Stripe."

2. The Stripe/PayPal "Split-Payment" Logic

Your description mentions "split-payment scheduling." This is a sophisticated feature.

• The Risk: If a donor gives $100 ($90 for a well in Africa and $10 for admin fees), the system must be able to report on those two amounts separately.

• Developer Note: "We need to use Stripe Connect or Transfer Groups. If the platform takes a 'platform fee' to keep the lights on, this must be calculated server-side before the data hits the database to ensure the donor's receipt matches the religious intent."

3. Identity vs. Privacy (The "Organisation Donor")

You mentioned that Organisation Donors have the "option to remain anonymous."

• The Requirement: In many charity regulations, "Anonymous" means anonymous to the public, but not to the Administrator (due to Anti-Money Laundering/AML laws).

• Developer Note: "The 'Anonymous' toggle should be a UI-level mask. The database must still capture the full KYC (Know Your Customer) data for the Platform Administrator to view in the backend for audit purposes."

📊 Visualizing the System Context

🛠️ Refined Component Responsibility Table

I've added a "Compliance" column to your table—this is what your developers need to stay focused on.