2. High-Level Architecture Diagram

GiveHope Platform: High-Level Architecture Documentation

2. High-Level Architecture Diagram

Shows how the GiveHope platform is organised into four major tiers: Client Layer (web app, donor dashboard, donation wizard, admin panel), Application Layer (backend services), Integration Layer (third-party APIs), and Data Layer (database, cache, file storage). This diagram answers the question: what are the major building blocks and how do they stack?

Diagram: High-Level Architecture Diagram.png

This second diagram is a High-Level Architecture (HLA) Diagram, likely following the C4 Level 2 (Container) or Level 3 (Component) style. While the first diagram showed who the platform talks to, this one peels back the lid to show the internal microservices or modules and how they interact to fulfill those requests.

1. Client Layer (The Frontend)

At the top, the diagram breaks the user interface into four distinct functional areas:

• Public Web App: Handles the landing page and campaign discovery (SEO-friendly).

• Donor Dashboard: The authenticated area for recurring gift management.

• Donation Wizard: A specialized, multi-step flow specifically for processing checkout.

• Admin Panel: The interface for staff to manage the backend data.

2. Application Layer (The Backend Services)

The blue central box represents the "GiveHope Platform" broken down into specialized services. This suggests a service-oriented or microservices architecture:

• Campaign Service: Manages the lifecycle of a fundraiser, including progress tracking and "logical" grouping of causes.

• Schedule Service: A dedicated engine for recurring logic. It handles the cron-like tasks of "Daily/Weekly/Monthly" triggers and pause/resume states.

• Auth Service: The gatekeeper. It handles session management and acts as the bridge to Google OAuth 2.0.

• Donation Service: The core "brain" for financial logic. It calculates Zakat/Sadaqah routing, handles "Platform Tips," and coordinates with payment processors.

• Notification Service: A decoupled service that listens for events (like a completed donation) and triggers the external Email Provider.

• Admin Service: Provides high-level data management and reporting tools for the staff.

3. Data & Storage Layer

The diagram introduces a sophisticated storage strategy on the left:

• Primary Database: The relational store for the main entities (Donors, Transactions).

• Cache (Redis/Similar): Used for "Frequently Read Data" and "Session Tokens" to ensure high performance and low latency.

• S3 / Storage: A dedicated object store for "Unstructured Data" like campaign hero images and PDF receipts.

4. Key Architectural Patterns

Based on the connections (arrows), we can see several advanced patterns at play:

• Decoupling: The "Donation Service" triggers the "Notification Service" rather than sending emails directly. This ensures that if the email provider is down, the donation can still be processed.

• Separation of Concerns: "Schedule Service" is separated from "Donation Service." This allows the platform to scale the high-volume donation traffic during peak times (like Ramadan) independently of the background scheduling tasks.

• Third-Party Abstraction: The "Integration Layer" at the bottom (Stripe, PayPal, Google) is abstracted away so the core business logic in the "Donation Service" doesn't have to change if the platform adds a new payment provider.

Comparison: Context vs. High-Level Architecture

🏗️ HLA Phase Evaluation: Strengths & "Missing Links"

This High-Level Architecture (HLA) review is excellent. It demonstrates a sophisticated, "decoupled" approach that is exactly what a high-growth charity needs.

1. The "Donation Wizard" vs. "Donation Service"

• The Strength: Moving the logic into a dedicated Donation Service is smart. It allows the Donation Wizard (Frontend) to stay "dumb" and fast, while the backend handles the complex Zakat calculations and religious routing rules.

• The "Perfect Build" Check: Ensure the Donation Service includes an Idempotency Layer.

• Why? If a donor clicks "Donate" and their internet flickers, you don't want them charged twice. The service should recognize the duplicate request within a few seconds and only process one.

2. The Cache (Redis) & Ramadan Scaling

• The Strength: Including a Cache Layer is vital for a charity.

• The "Perfect Build" Check: Your traffic will likely be "spiky" (e.g., the last ten nights of Ramadan or Giving Tuesday).

• Developer Note: "The Campaign Service should cache campaign progress (e.g., '$10k raised of $50k') so the database isn't hit 1,000 times a minute just to update a progress bar."

3. The "Schedule Service" & Subscription Fatigue

• The Strength: Having a separate service for recurring gifts is a pro-tier move.

• The "Perfect Build" Check: How does the system handle dunning (failed payments)?

• Developer Note: "The Schedule Service must have a 'Retry Logic' and a 'Grace Period' status before it automatically cancels a donor's monthly Sadaqah."

📊 Visualizing the Component Interaction

🛠️ Refined Component Responsibility (HLA Level)

I’ve updated your table to include the "Charity-Specific" technical requirements for each block:

💡 The "Architect's Question" for your Devs

Now that the "Building Blocks" are defined, you should ask the developers:

"In the Integration Layer, are we using a 'Circuit Breaker' pattern?"

Translation: If Stripe goes down, does the whole site show an error, or can the Donation Service automatically hide the Credit Card option and only show PayPal so we don't lose donations?