5. Sequence Diagram_Architecture

GiveHope Platform: Sequence Diagram Documentation

5. Sequence Diagram

The Sequence Diagram serves as the "screenplay" for your architecture. While the previous diagrams showed static structures (how things are built), this one shows runtime behavior—specifically how a user's request travels through the system over time.

It details 5 sequential phases—from browsing a campaign, through personal info, cause and objective selection, payment configuration, summary, card entry, confirmation, all the way to receipt delivery and recurring schedule execution. Every service-to-service call, database operation, and external API interaction is shown in order. This diagram answers the question: what happens step by step when a donor makes a donation?

Diagram: Sequence Diagram.png

1. Lifelines (The Vertical Columns)

Each column represents a component from your earlier diagrams, acting in real-time. From left to right, we see the flow moving across:

• The Actor: (e.g., Guest or Registered Donor) initiating the action.

• Frontend/UI: (The Web App/Wizard) capturing the user input.

• API Gateway/Controllers: Validating the initial request.

• Core Services: (Donation Service, Auth Service) applying business logic.

• External Integrations: (Stripe/PayPal, Email Service) handling payments and notifications.

• Database: Persisting the final results.

2. Chronological Flow of Events

The diagram is read from top to bottom. Key phases include:

Phase A: Initiation & Validation

The user submits the donation form. The UI sends a request to the backend. The system first checks for authentication (via the Auth Service) and validates the donation amount and campaign ID.

Phase B: Payment Processing (The External Loop)

This is a critical section of the diagram:

• Handshake: The Donation Service requests a "Payment Intent" from Stripe or PayPal.

• Redirect/Modal: The user interacts with the payment provider's secure interface.

• Callback: Once the payment is authorized, the provider sends a webhook or a redirect back to the platform to confirm the money has been moved.

Phase C: Post-Donation Logic

Once the payment is confirmed, the system triggers a chain reaction:

• Database Update: The transaction status changes to "Success," and the campaign's "Current Progress" is incremented.

• Asynchronous Tasks: The Notification Service is triggered to generate and send the receipt email.

• UI Update: The user is finally shown the "Thank You" or confirmation screen.

3. Logic Gates (Fragments)

The boxes labeled "alt" (alternative) or "opt" (optional) represent logic branches:

• Success vs. Failure: One branch shows what happens if the card is declined (error message), while the other shows the success path.

• Guest vs. Registered: An optional branch might show the system checking if it needs to link the donation to an existing user profile or create a temporary guest record.

4. Why This Matters for Architecture

This diagram bridges the gap between the Component Diagram and the ERD:

• It proves that the components you designed actually have a path to talk to each other.

• It identifies latency points (e.g., waiting for a third-party payment provider).

• It highlights security checkpoints, ensuring that no donation is recorded in the database until the payment provider verifies the funds.

🏗️ Sequence Phase Evaluation: The "Transaction Lifecycle"

If the ERD was the filing cabinet, the Sequence Diagram is the industrial conveyor belt that moves the data from the donor’s hand into that cabinet. A perfectly built charity platform lives or dies by its Error Handling during this sequence.

1. The "Webhook" vs. "Redirect" Trap

• The Strength: You correctly identified the Webhook (Phase B). Many amateur developers rely on the "Success Page" to trigger the donation record.

• The "Perfect Build" Check: If a donor closes their browser tab the second the payment is successful, only a Webhook ensures the transaction is finalized.

• Developer Note: "The Donation Service must listen for the payment_intent.succeeded webhook from Stripe to finalize the transaction, regardless of whether the user sees the 'Thank You' page."

2. The Asynchronous "Chain Reaction"

• The Strength: Triggering the Notification Service after the Database update (Phase C) is the correct architectural pattern.

• The "Perfect Build" Check: Generating a PDF receipt can be "heavy." If the generator crashes, it shouldn't "roll back" the donation.

• Developer Note: "Use a Message Queue (like RabbitMQ or Redis) between the Donation Service and the Notification Service. This ensures that even if the email server is slow, the donor's record is safe."

3. The "Alt" Fragments (Failure Logic)

• The Strength: Your mention of "Success vs. Failure" branches is vital.

• The "Perfect Build" Check: For Zakat, "Failure" also includes "Validation Failure" (e.g., trying to give a $0.00 Zakat).

• Developer Note: "The Auth Guard and Validator must catch invalid inputs before we even talk to Stripe to save on API overhead and provide instant feedback to the donor."

📊 Visualizing the Sequence Logic

🛠️ The "Sequence Success" Checklist

Hand this to your developers to ensure the "Conveyor Belt" never jams:

Total Architecture Summary

You have now documented the platform across all major dimensions:

1. Context: The "Big Picture."

2. High-Level: The "Infrastructure."

3. Component: The "Code Structure."

4. ERD: The "Permanent Data Structure."

5. Sequence: The "Live Process."