4.0 Donation ‐ Core Components - FatinaAlTaherr/HopeConnect GitHub Wiki

Overview

The Donation Management System handles monetary and in-kind donations to orphanages, including payment processing, tracking, and reporting. It integrates with Stripe for payment processing and provides comprehensive tracking of donation status and impact.

Models

Donation

Core donation entity tracking all contributions.

  • Attributes:
    • id: Unique identifier
    • donor: Contributing user
    • orphanage: Beneficiary organization
    • type: MONEY, GOODS, or SERVICES
    • category: GENERAL_FUND, EDUCATION_SUPPORT, etc.
    • amount: Donation value
    • status: PENDING, PROCESSING, COMPLETED, etc.
    • paymentIntent: Stripe payment reference
    • transactionFee: Processing fee amount
    • netAmount: Amount after fees
    • createdAt/updatedAt: Timestamps

DonationItem

For in-kind donations.

  • Attributes:
    • name: Item description
    • quantity: Number of items
    • itemCondition: Condition description
    • size: Relevant for clothing

DeliveryTracking

Package tracking for physical donations.

  • Attributes:
    • trackingNumber: Carrier reference
    • status: PICKED_UP, IN_TRANSIT, etc.
    • checkpoints: List of delivery milestones
    • estimated/actualDelivery: Timestamps

DonationUpdate

Progress updates for donors.

  • Attributes:
    • title: Update headline
    • description: Detailed information
    • imageUrl: Optional visual evidence

Review

Donor feedback system.

  • Attributes:
    • rating: 1-5 scale
    • comment: Written feedback
    • reviewDate: Submission timestamp

Enums

DonationType

  • MONEY
  • GOODS
  • SERVICES

DonationCategory

  • GENERAL_FUND
  • EDUCATION_SUPPORT
  • MEDICAL_AID
  • CLOTHING
  • FOOD
  • EDUCATIONAL_MATERIALS

DonationStatus

  • PENDING
  • PROCESSING
  • COMPLETED
  • DELIVERED
  • CANCELLED

DeliveryStatus

  • PICKED_UP
  • IN_TRANSIT
  • AT_WAREHOUSE
  • OUT_FOR_DELIVERY
  • DELIVERED
  • RETURNED

Services

DonationService

Core donation processing logic.

  • Key Methods:
    • createDonation(): Handles new donations with fee calculations
    • confirmDonationPayment(): Finalizes successful transactions
    • Management methods for items, updates, tracking, and reviews
    • Email notification system for donors/orphanages

DonationPaymentService

Stripe integration handling.

  • Key Methods:
    • createDonationSession(): Sets up Stripe checkout
    • confirmSuccessfulPayment(): Validates completed payments

Controllers

DonationController

Primary donation endpoints.

  • Key Endpoints:
    • POST /donations: Create new donation
    • Payment processing endpoints
    • Donation item management
    • Delivery tracking updates
    • Review submission

FeeConfig

Transaction fee configuration.

  • transactionFeePercentage: Percentage fee
  • minimumFee: Minimum charge
  • maximumFee: Maximum charge cap