3. Component Diagram_Architecture

3. Component Diagram Breaks the backend apart into nine internal modules — Auth, Campaign, Donation, Schedule, Cause & Objective, Donor, Notification, Payment, and Admin. Each module is further divided into its Controller, Service, and Repository layers with all REST endpoints documented. This diagram answers the question: what does the backend look like on the inside? 

Diagram: Component Diagram.png 

This third diagram is a Detailed Component Diagram (C4 Level 3). While the previous diagram showed the "what" (services), this one shows the "how" by zooming into the specific software components, controllers, and logic providers that live inside those services.

It maps out the internal code structure, showing how requests are routed from an entry point down to the data access layer.

1. The Gateway & Orchestration Layer

At the very top, we see the API Gateway / Entry Point. This acts as the single "front door" for the frontend apps.

• Request Routing: It receives HTTP requests and directs them to the appropriate internal controller.

• Shared Logic: Components like the Auth Guard or Validator sit high up to ensure only "clean," authorized requests reach the deeper business logic.

2. Service-Specific Component Breakdowns

The diagram groups logic into vertical stacks. Here are the most critical "inner workings" identified:

The Donation Engine (Center-Left)

This is the most complex cluster. It contains:

• Donation Controller: Handles incoming API calls for money movement.

• Calculation Engine: Specifically manages the Zakat/Sadaqah math. Since these have different religious and legal distribution requirements, this logic is isolated to ensure precision.

• Routing Logic: Determines how a single payment might be split across multiple causes or "Add-ons."

The Scheduling & Recurring Logic (Far Left)

• Schedule Manager: Manages the state of a recurring donation (Active, Paused, Canceled).

• Job Processor: Likely a background worker (like a cron job or Celery/BullMQ task) that wakes up daily to check which donations are due for a charge.

Campaign & Admin Modules (Center-Right)

• Campaign Manager: Handles the CRUD (Create, Read, Update, Delete) operations for fundraisers.

• Audit Logger: A specialized component within the Admin stack that records every action taken by staff for financial transparency and compliance.

3. The Data Access Layer (DAL)

At the bottom of each service stack, you see smaller boxes representing Repositories or Data Mappers:

• These components are the only ones allowed to "talk" to the Database or Cache.

• This pattern (Repository Pattern) ensures that if you ever switch from a SQL database to a NoSQL one, you only have to change the code in these specific bottom-layer components rather than the entire system.

4. Key Takeaways for Developers

• Standardized Flow: Every service follows a similar pattern: Controller → Service/Logic → Repository → Database. This makes the codebase predictable and easier for new developers to navigate.

• Tight Security: By having Auth and Validation as the first stop after the Gateway, the diagram confirms a "Security by Design" approach.

• Modular Scalability: Because the components are so clearly separated, a bug in the "Notification Component" won't crash the "Donation Component."

Summary of the Three-Diagram Hierarchy

To put this in perspective for your documentation:

1. Context Diagram: The "What" (The platform vs. The World).

2. High-Level Architecture: The "Where" (The Services and Infrastructure).

3. Component Diagram (This one): The "How" (The Classes and Internal Logic).

This Component Diagram (C4 Level 3) evaluation is the most critical for your developers because it defines the Internal Design Patterns.

By enforcing a Controller → Service → Repository (Layered Architecture), you are ensuring that the code isn't "spaghetti." If a bug happens in the Zakat calculation, the developer knows exactly which file to open (the CalculationEngine in the Service layer) without digging through database code or UI code.

🏗️ Component Phase Evaluation: The "Charity Stress Test"

While the logic is sound, here is how you ensure this specific internal structure stays "perfect" for GiveHope:

1. The Calculation Engine (Precision & Auditing)

• The Strength: Isolating the Zakat/Sadaqah math into a standalone Calculation Engine is brilliant. It allows you to update religious tax rates or distribution rules without touching the "Payment" logic.

• The "Perfect Build" Check: This engine should be Unit Tested with 100% coverage.

• Developer Note: "We need a suite of test cases for the Calculation Engine that covers edge cases like: What happens if the donation is $0.50 but the transaction fee is $0.30? How is the Zakat portion rounded?"

2. The Job Processor (The "Silent" Failure)

• The Strength: Using a background worker for recurring donations ensures the website stays fast for new users.

• The "Perfect Build" Check: What happens if the Job Processor fails halfway through a list of 1,000 monthly donors?

• Developer Note: "The Schedule Manager must implement Atomic Transactions. If the server crashes during a bulk charge, it must be able to resume exactly where it left off without double-charging anyone."

3. The Audit Logger (Compliance)

• The Strength: Having an Audit Logger in the Admin module is non-negotiable for a charity.

• The "Perfect Build" Check: It shouldn't just log who logged in; it must log changes to financial data.

• Developer Note: "The Audit Logger must record the 'Before' and 'After' state of a campaign's total funds whenever an Admin manually adjusts a balance."

📊 Visualizing the Layered Component Flow

🛠️ The "Developer's Handshake" Table

Use this table to confirm with your lead dev that the internal "layers" are doing their jobs correctly.