Donation Data Model Analysis

Current State Comparison

Documentation vs Seeding Script vs API

Field	Documentation	Seeding Script	API Route	Legacy App	Status
id	✅ Required	✅ Required	✅ Auto-generated	✅ Required	✅ Match
caseId	✅ Required	⚠️ Optional (70%)	✅ Required	✅ Required	⚠️ INCONSISTENT
guardianId	✅ Required	⚠️ Optional (30%)	❌ Missing	❌ Missing	⚠️ INCONSISTENT
userId	✅ Optional	✅ Required	❌ Missing	❌ Missing	⚠️ INCONSISTENT
donorId	❌ Not in docs	❌ Missing	✅ Required	✅ Optional	⚠️ INCONSISTENT
userName	✅ Optional	✅ Optional	❌ Missing	❌ Missing	⚠️ INCONSISTENT
donorName	❌ Not in docs	❌ Missing	❌ Missing	✅ Optional	⚠️ INCONSISTENT
userEmail	✅ Optional	✅ Optional	❌ Missing	❌ Missing	⚠️ INCONSISTENT
donorEmail	❌ Not in docs	❌ Missing	❌ Missing	✅ Optional	⚠️ INCONSISTENT
amount	✅ Required	✅ Required	✅ Required	✅ Required	✅ Match
currency	✅ Required	✅ Required	✅ Optional (default ARS)	❌ Missing	⚠️ INCONSISTENT
originalAmount	✅ Required	✅ Required	❌ Missing	❌ Missing	⚠️ INCONSISTENT
convertedAmount	✅ Required	✅ Required	❌ Missing	❌ Missing	⚠️ INCONSISTENT
paymentProvider	✅ Required	✅ Required	❌ Missing	❌ Missing	⚠️ INCONSISTENT
paymentMethod	❌ Not in docs	❌ Missing	✅ Required	✅ Required	⚠️ INCONSISTENT
transactionId	✅ Required	✅ Required	❌ Missing	❌ Missing	⚠️ INCONSISTENT
partnerTransactionId	✅ Required	✅ Optional	❌ Missing	❌ Missing	⚠️ INCONSISTENT
paymentIntentId	❌ Not in docs	❌ Missing	❌ Missing	✅ Optional	⚠️ INCONSISTENT
status	✅ Required	✅ Required	✅ Required	✅ Required	⚠️ VALUE MISMATCH
isAnonymous	✅ Required	✅ Required	❌ Missing	✅ Required	⚠️ INCONSISTENT
message	✅ Optional	✅ Optional	❌ Missing	✅ Optional	✅ Match
createdAt	✅ Required	✅ Required	✅ Required	✅ Required	✅ Match
updatedAt	❌ Missing	❌ Missing	✅ Required	❌ Missing	❌ MISSING
completedAt	✅ Optional	❌ Missing	❌ Missing	✅ Optional	⚠️ INCONSISTENT

Issues Identified

1. Field Naming Inconsistencies

• userId vs donorId: Different names for the same concept
• userName/userEmail vs donorName/donorEmail: Different naming conventions
• paymentProvider vs paymentMethod: Different concepts or same?

2. Required vs Optional Conflicts

• caseId and guardianId: Docs say both required, but logically should be either/or
• userId/donorId: Required in seeding, optional in docs/legacy (for anonymous)
• currency: Required in docs/seeding, optional in API (defaults to ARS)

3. Missing Fields

• updatedAt: Present in API, missing in seeding/docs
• completedAt: Present in docs/legacy, missing in seeding/API

4. Stellar Integration Fields

• originalAmount and convertedAmount: Present in seeding/docs for Stellar conversion
• Not present in API - is Stellar integration still used?

5. Payment Processing Fields

• paymentProvider (seeding/docs): 'moonpay' | 'stellar' | 'manual'
• paymentMethod (API/legacy): 'credit_card' | 'paypal' | 'other' | 'unknown'
• transactionId: Internal transaction ID
• partnerTransactionId: Partner transaction ID
• paymentIntentId: Payment provider reference (legacy)

6. Status Value Mismatch

• Most use: 'pending' | 'completed' | 'failed' | 'refunded'
• Some use: 'cancelled' instead of 'refunded'

Questions to Resolve

1. Donation target: Can donations be to cases OR guardians directly?

   • Option A: Only to cases (simpler, caseId required)
   • Option B: Either to cases or guardians (caseId OR guardianId)
   • Recommendation: Only to cases (guardian can be derived from case)

2. Field naming: Standardize on userId/userName/userEmail or donorId/donorName/donorEmail?

   • Recommendation: userId/userName/userEmail (consistent with user model)

3. Stellar integration: Are originalAmount and convertedAmount still needed?

   • If yes: Keep them
   • If no: Remove them
   • Recommendation: Keep if Stellar is still used, otherwise remove

4. Payment fields: Which payment fields are actually used?

   • paymentProvider vs paymentMethod - which is correct?
   • transactionId vs paymentIntentId - which is used?
   • Recommendation: Need to check actual implementation

5. Status values: Include 'cancelled' or only 'refunded'?

   • Recommendation: Use 'refunded' (cancelled = failed before completion)

6. Timestamps: Should we have updatedAt and completedAt?

   • Recommendation: Yes to both - updatedAt for any change, completedAt for completion

7. Anonymous donations: How are anonymous donations handled?

   • userId should be optional for anonymous
   • userName/userEmail should be optional (not stored if anonymous)