3.0 Sponsorship - FatinaAlTaherr/HopeConnect GitHub Wiki

Overview

The Sponsorship Management System facilitates the sponsorship of orphans by donors, with features for creating, managing, and tracking sponsorship relationships. It includes payment integration via Stripe and implements role-based access control for sponsors, orphanage owners, and administrators.

Models

Sponsorship

Represents a sponsorship relationship between a user and an orphan.

  • Attributes:
    • id: Unique identifier (auto-generated)
    • user: Sponsoring user (many-to-one relationship)
    • orphan: Sponsored orphan (many-to-one relationship)
    • startDate: Sponsorship commencement date (required)
    • endDate: Sponsorship conclusion date (optional)
    • status: Current status (enum: PENDING, ACCEPTED, COMPLETED, CANCELLED)

SponsorshipStatus

Enum representing sponsorship lifecycle states.

  • Values:
    • PENDING: Awaiting orphanage approval
    • ACCEPTED: Approved and active
    • COMPLETED: Successfully concluded
    • CANCELLED: Terminated prematurely

DTOs (Data Transfer Objects)

SponsorshipRequest

Used for creating new sponsorships.

  • Fields:
    • userEmail: Sponsor's email
    • orphanId: ID of orphan to sponsor
    • startDate: Sponsorship start date
    • endDate: Sponsorship end date

StripeResponse

Contains payment processing information.

  • Fields:
    • sessionId: Stripe checkout session ID
    • url: Payment URL for sponsor

Services

SponsorshipService

Handles core sponsorship business logic and payment processing.

  • Methods:
    • getUnacceptedByOrphanage(orphanageId): Gets pending sponsorships for specific orphanage
    • acceptSponsorship(sponsorshipId): Approves a sponsorship request
    • createSponsorship(request): Creates new sponsorship record
    • getUnacceptedSponsorships(): Lists all pending sponsorships
    • getAll(): Retrieves all sponsorships
    • getByUser(email): Gets sponsorships by sponsor email
    • getByOrphan(orphanId): Gets sponsorships by orphan ID
    • endSponsorship(sponsorshipId): Marks sponsorship as completed
    • deleteSponsorship(sponsorshipId): Removes sponsorship record
    • initiatePayment(sponsorshipId, sponsorEmail): Starts Stripe payment process
    • calculateAmount(sponsorship): Computes sponsorship cost based on duration

Controllers

SponsorshipController

Handles HTTP requests for sponsorship operations.

  • Endpoints:
    • PUT /HopeConnect/api/sponsorships/{id}/accept: Approves sponsorship (ORPHANAGE_OWNER/ADMIN)
    • GET /HopeConnect/api/sponsorships/unaccepted: Lists unaccepted sponsorships (ADMIN)
    • POST /HopeConnect/api/sponsorships/{id}/pay: Initiates payment (SPONSOR)
    • GET /HopeConnect/api/sponsorships/unaccepted/orphanage/{orphanageId}: Gets orphanage-specific pending sponsorships (ADMIN/ORPHANAGE_OWNER)
    • POST /HopeConnect/api/sponsorships: Creates new sponsorship (SPONSOR)
    • GET /HopeConnect/api/sponsorships: Lists all sponsorships
    • GET /HopeConnect/api/sponsorships/user/{email}: Gets user's sponsorships (ADMIN/ORPHANAGE_OWNER)
    • GET /HopeConnect/api/sponsorships/orphan/{orphanId}: Gets orphan's sponsorships (ADMIN/ORPHANAGE_OWNER)
    • PUT /HopeConnect/api/sponsorships/{id}/end: Completes sponsorship (ADMIN/ORPHANAGE_OWNER)
    • DELETE /HopeConnect/api/sponsorships/{id}: Deletes sponsorship (ADMIN/ORPHANAGE_OWNER)

Workflow

  1. Sponsorship Creation:

    • SPONSOR submits request via POST endpoint
    • System creates PENDING sponsorship record
    • Orphanage owner/admin reviews request

  2. Approval Process:

    • ORPHANAGE_OWNER/ADMIN accepts via PUT endpoint
    • Status changes to ACCEPTED
    • Sponsor receives notification

  3. Payment Processing:

    • SPONSOR initiates payment via Stripe
    • System calculates duration-based amount
    • Redirects to Stripe checkout

  4. Sponsorship Management:

    • Owners/admins can view all related sponsorships
    • Can complete or cancel sponsorships as needed
    • All changes are auditable

Security

  • Role-based access control:
    • SPONSOR: Can create sponsorships and make payments
    • ORPHANAGE_OWNER: Can manage their orphanage's sponsorships
    • ADMIN: Full management privileges
  • JWT authentication required for all endpoints
  • Payment authorization checks ensure sponsors only pay for their own sponsorships

Payment Calculation

  • Fixed monthly rate of $30 (3000 cents)
  • Duration calculated from start to end date
  • Minimum charge of 1 month
  • Example: 6 month sponsorship = $180