Sequence Diagram 3: Claiming Rewards from the Leaderboard - bounswe/bounswe2025group2 GitHub Wiki

Claiming reward through leaderboard use case diagram

Legend β€” Sequence Diagram: Claiming Rewards from the Leaderboard

Participants / Components

  • User
    The end user who clicks the claim button in the UI.

  • Frontend (UI)
    Browser/mobile client that collects user input and displays status messages.

  • Backend API
    Central server endpoint orchestrating the claim flow and coordinating services.

  • Leaderboard Service (LS)
    Service/module responsible for computing eligibility, ranks, and retrieving leaderboard data.

  • Reward Service (RS)
    Service/module that handles reward inventory, reservation, and redemption records.

  • Database (DB)
    Persistent store for users, leaderboards, rewards, reservations, and transactions.

  • Notification Service (NS)
    Service that sends in-app notifications, push messages, and emails.

Normal Flow

  1. User β†’ Frontend: Clicks β€œClaim Reward” with rewardId.
  2. Frontend β†’ Backend: POST /api/rewards/claim { userId, rewardId }.
  3. Backend β†’ Leaderboard Service: Validate eligibility (GET /eligibility?userId=...).
  4. Leaderboard Service β†’ DB: Query user's rank/points/completions.
  5. Leaderboard Service β†’ Backend: Returns { eligible: true }.
  6. Backend β†’ Reward Service: Request reservation (check stock, lock item).
  7. Reward Service β†’ DB: Begin transaction; reserve item and insert reservation.
  8. Reward Service β†’ Backend: Return reservation success and reservationId.
  9. Backend β†’ DB: Deduct user points and insert redemption record.
  10. Backend β†’ Notification Service: Notify user (push/email).
  11. Notification Service β†’ User: Deliver confirmation.
  12. Backend β†’ Frontend: Respond 200 OK { status: "claimed", reservationId }.
  13. Frontend β†’ User: Show success and redemption instructions.

Alternate Flow

  • If Leaderboard Service returns { eligible: false }, Backend returns 403 Forbidden to Frontend with reason; Frontend shows error to User.

Error / Rollback Cases

  • If reservation fails (no stock) the Reward Service returns error β†’ Backend rolls back any DB changes and returns failure to Frontend; optionally notify user about stock shortage.
  • If Notification Service fails after successful reservation, the claim may still be considered complete; Backend should log the notification failure and retry.

Important Messages & Semantics

  • GET /eligibility β€” authoritative check for rank/points/completions.
  • POST /rewards/reserve β€” must be transactional to prevent race conditions.
  • DB transactions should ensure atomicity: either reservation + point deduction + redemption record succeed together or all are rolled back.

Notes for Implementers

  • Use optimistic locking or DB transactions in the Reward Service to avoid overselling.
  • Provide idempotent endpoints (e.g., claim retries should not double-deduct points).
  • Log and surface clear error messages for audit and support (reservationId, transactionId).
  • Include accessibility considerations: confirmations must be accessible (readable by screen readers and not rely on color alone).