Skip to main content

Data Models Quick Reference

Quick reference for developers working with Toto ecosystem data models. For complete documentation, see Data Models & Database Schema.

📋 Core Types at a Glance​

User Management​

type UserRole = 'user' | 'guardian' | 'admin' | 'investor' | 'partner';
type UserStatus = 'active' | 'inactive' | 'pending' | 'waitlist';

interface User {
  id: string;                    // Normalized ID
  email: string;                 // User email
  name: string;                  // Display name
  role: UserRole;                // User role
  status: UserStatus;            // Account status
  imageUrl?: string;             // Profile picture
  createdAt: string;             // ISO 8601 timestamp
}

Case Management​

type CaseStatus = 'active' | 'urgent' | 'completed' | 'draft';
type CasePriority = 'urgent' | 'normal';
type CaseCategory = 'rescue' | 'surgery' | 'treatment' | 'transit' | 'foster';

interface Case {
  id: string;                    // Normalized ID
  name: string;                  // Case title
  description: string;           // Case description
  imageUrl: string;              // Primary image
  status: CaseStatus;            // Current status
  guardianId: string;            // Guardian's user ID
  donationGoal: number;          // Target amount (cents)
  donationsReceived: number;     // Current amount (cents)
  createdAt: string;             // ISO 8601 timestamp
}

Donation System​

type DonationStatus = 'pending' | 'completed' | 'failed' | 'refunded';
type PaymentMethod = 'credit_card' | 'stellar' | 'other';

interface Donation {
  id: string;                    // Unique identifier
  caseId: string;                // Related case ID
  donorId?: string;              // Donor's user ID
  amount: number;                // Amount in cents
  status: DonationStatus;        // Payment status
  paymentMethod: PaymentMethod;  // Payment method
  createdAt: string;           // ISO 8601 timestamp
}

🔗 Key Relationships​

  • User → Cases (one-to-many, as guardian)
  • User → Donations (one-to-many, as donor)
  • Case → Updates (one-to-many)
  • Case → Donations (one-to-many)
  • Donation → Case (many-to-one)

🚨 Common Queries​

// Get user's cases
const userCases = await getDocs(
  query(collection(db, 'cases'), 
  where('guardianId', '==', userId))
);

// Get case donations
const caseDonations = await getDocs(
  query(collection(db, 'donations'), 
  where('caseId', '==', caseId))
);

// Get case updates (ordered)
const caseUpdates = await getDocs(
  query(collection(db, 'updates'), 
  where('caseId', '==', caseId),
  orderBy('createdAt', 'desc'))
);

🔐 Security Rules Summary​

  • Users: Read/write own data, read public cases, create donations
  • Guardians: Read/write own cases, read case donations, create/update updates
  • Admins: Full access to all data

📊 Data Validation​

  • Amounts: Always in cents (integers)
  • Dates: ISO 8601 strings
  • IDs: Normalized format (e.g., usr_, cas_)
  • Status: Predefined enum values only

🚀 Performance Tips​

  • Create compound indexes for complex queries
  • Index frequently queried fields: status, guardianId, createdAt
  • Use pagination for large result sets

📚 For complete data model documentation, see Data Models & Database Schema