Skip to main content

Entity Review Summary - Complete Data Model Standardization

Overview​

This document summarizes the comprehensive review and standardization of all data models across the Toto ecosystem. The goal was to establish a single source of truth for each entity that all applications can extend, rather than having disparate definitions.

Entities Reviewed​

✅ 1. Cases​

Status: Complete Base Model: toto-docs/app/docs/architecture/case-base-model.ts Key Changes:

  • Removed donationGoal and animalType fields
  • Added optional social media URLs (instagramUrl, twitterUrl, facebookUrl)
  • Standardized status, priority, and category types
  • Denormalized guardianName and guardianImageUrl removed (fetch from users collection)

UI Connections:

  • ✅ toto-app: Home screen (CaseCard), CaseChatModal, CaseFullScreenModal, GuardianDetailsModal
  • ✅ toto-bo: Dashboard cases management, case creation/editing

Missing Fields in UI: None identified

✅ 2. Users​

Status: Complete Base Model: toto-docs/app/docs/architecture/user-base-model.ts Key Changes:

  • Removed department field
  • Standardized lastActive (string), timeSinceJoined (number)
  • Made address, rating, reviews optional
  • Added updatedAt (required)
  • Made firebaseUid optional
  • Changed contactInfo to optional object with phone
  • Standardized socialLinks as typed object
  • Added stars rating system (rating, reviewsCount, reviews)

UI Connections:

  • ✅ toto-app: Profile screen, GuardianDetailsModal
  • ✅ toto-bo: User management dashboard

Missing Fields in UI:

  • ⚠️ rating and reviews not displayed in UI (should be added to profile/guardian details)

✅ 3. Donations​

Status: Complete Base Model: toto-docs/app/docs/architecture/donation-base-model.ts Key Changes:

  • Removed Stellar-related fields (originalAmount, convertedAmount, paymentProvider, partnerTransactionId)
  • Simplified to bank transfers only (paymentMethod: 'bank_transfer')
  • Added proofUrl (optional) for donation proof
  • Simplified status to 'pending' | 'verified'
  • Added updatedAt and verifiedAt timestamps
  • caseId or guardianId required (one of both)

UI Connections:

  • ✅ toto-app: Profile screen (shows verified donations count)
  • ✅ toto-bo: Donations management dashboard

Missing Fields in UI:

  • ⚠️ proofUrl not displayed/uploaded in UI (should be added for donation submission)
  • ⚠️ verifiedAt not displayed in donation history

✅ 4. Follows​

Status: Complete Base Model: toto-docs/app/docs/architecture/follow-base-model.ts Key Changes:

  • Standardized on composite keys for IDs (${userId}_${caseId} or ${userId}_${guardianId})
  • Added notificationsEnabled: true default
  • Added updatedAt (optional, set to createdAt on creation)
  • followType is array (currently ['like'])
  • caseId or guardianId required (one of both)

UI Connections:

  • ✅ toto-app: CaseCard (like button), GuardianDetailsModal (follow button)
  • ✅ toto-bo: Follows management (if exists)

Missing Fields in UI:

  • ⚠️ notificationsEnabled toggle not available in UI (should be added to settings)

✅ 5. Case Updates​

Status: Complete Base Model: toto-docs/app/docs/architecture/case-update-base-model.ts Key Changes:

  • Removed type field
  • Added updatedAt (required)
  • Clarified that status/previousStatus track case status changes, not update status
  • Implemented Firebase Auth for updatedBy and updatedByName

UI Connections:

  • ✅ toto-app: CaseFullScreenModal (displays updates)
  • ✅ toto-bo: Case updates management, API route with Firebase Auth

Missing Fields in UI: None identified

✅ 6. Conversations​

Status: Complete Base Model: toto-docs/app/docs/architecture/conversation-base-model.ts Key Changes:

  • Changed isActive → isArchived (more explicit)
  • Added updatedAt field
  • Standardized timestamps to ISO 8601 strings
  • Added actionTaken as optional field
  • Removed platform from messages (kept only at conversation level)
  • Always generate message IDs

UI Connections:

  • ✅ toto-app: Inbox screen, CaseChatModal
  • ❌ toto-bo: Not connected (conversations are mobile-app only)

Missing Fields in UI:

  • ⚠️ actionTaken not displayed in conversation list (could show badges for donations/shares)
  • ⚠️ isArchived toggle not available in UI

✅ 7. Support Tickets​

Status: Complete Base Model: toto-docs/app/docs/architecture/support-ticket-base-model.ts Key Changes:

  • Fixed critical field name inconsistency: requesterId → userId, requesterEmail → userEmail
  • Standardized collection name to support_tickets (snake_case)
  • Made userId optional (require at least one of userId or userEmail)
  • Added caseId and guardianId optional fields for related entities
  • Included 'cancelled' status in type definitions

UI Connections:

  • ❌ toto-app: Not connected (support tickets are backoffice-only)
  • ✅ toto-bo: Support hub dashboard, ticket management

Missing Fields in UI:

  • ⚠️ caseId and guardianId not displayed/selectable when creating tickets
  • ⚠️ Related case/guardian not shown in ticket details

⏭️ 8. Audit Logs​

Status: Skipped (Backoffice Infrastructure) Reason: Audit logs are admin-only, backoffice infrastructure, not user-facing entities. They don't need cross-app standardization.

UI Connections:

  • ❌ toto-app: Not connected (admin-only)
  • ✅ toto-bo: Audit logs dashboard

Firestore Collections Structure​

Active Collections (Used in Code)​

Core Collections​

  1. users - User accounts and profiles

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps

  2. cases - Pet rescue cases

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps
    • Subcollection: cases/{caseId}/updates

  3. donations - Donation records

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps

  4. follows - User subscriptions (likes/follows)

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps

  5. updates - Case updates (top-level)

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps
    • Note: Also exists as subcollection cases/{caseId}/updates

  6. conversations - AI chat conversations

    • ✅ Used in: toto-app only
    • ✅ Rules defined in toto-app

  7. support_tickets - Support ticket management

    • ✅ Used in: toto-bo only
    • ✅ Rules defined in both apps (for future mobile support)

  8. notifications - User notifications

    • ✅ Used in: toto-app, toto-bo
    • ✅ Rules defined in both apps

  9. audit_logs - System audit trail

    • ✅ Used in: toto-bo only (admin-only)
    • ✅ Rules defined in toto-bo

Twitter Bot Collections (Backoffice Only)​

  1. guardians - Guardian management (Twitter bot)

    • ✅ Used in: toto-bo only
    • ✅ Rules defined in toto-bo

  2. guardianTweets - Guardian tweets

    • ✅ Used in: toto-bo only
    • ✅ Rules defined in toto-bo

  3. twitterBotConfig - Twitter bot configuration

    • ✅ Used in: toto-bo only
    • ✅ Rules defined in toto-bo

Other Collections​

  1. partners - Business partners
    • ✅ Used in: toto-app (read-only for marketing)
    • ✅ Rules defined in toto-app

Potentially Unused Collections​

Based on Firestore rules and codebase search, these collections may be unused:

  1. waitlist - Mentioned in init script cleanup but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used in Cloud Functions or external services

  2. analytics - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for analytics tracking

  3. chats - Mentioned in init script but not in rules

    • ⚠️ Likely replaced by conversations - can be removed
    • Action: Verify no legacy code references this

  4. analytics_cache - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for caching analytics data

  5. accounts - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for account management

  6. sessions - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for session management

  7. verification_tokens - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for email verification

  8. collaborators - Mentioned in init script but not in rules

    • ⚠️ Check if still needed or can be removed
    • Action: Verify if used for collaboration features

Collections Used But Not in Rules​

  1. socialMediaPosts - Used in API routes but not in Firestore rules
    • ⚠️ Action Required: Add Firestore rules for this collection
    • Location: toto-bo/src/app/api/social-media/posts/route.ts

UI Connection Summary​

Entities Connected to Both UIs​

  • ✅ Cases - toto-app (home, details) + toto-bo (management)
  • ✅ Users - toto-app (profile) + toto-bo (management)
  • ✅ Donations - toto-app (profile stats) + toto-bo (management)
  • ✅ Follows - toto-app (like/follow buttons) + toto-bo (if exists)
  • ✅ Case Updates - toto-app (case details) + toto-bo (management)
  • ✅ Notifications - toto-app (inbox) + toto-bo (management)

Entities Connected to Single UI​

  • ✅ Conversations - toto-app only (inbox, chat)
  • ✅ Support Tickets - toto-bo only (support hub)
  • ✅ Audit Logs - toto-bo only (admin dashboard)

Critical Issues Found​

⚠️ Field Name Inconsistency - FIXED​

Donations: App Firestore rules used donorId but model uses userId

  • Status: ✅ Fixed in toto-app/firebase/firestore.rules
  • Impact: Rules now match the standardized model

Missing Fields in UI - Action Items​

High Priority​

  1. Donations - proofUrl

    • Where: toto-app donation flow
    • Action: Add file upload for donation proof
    • Impact: Required for donation verification

  2. Support Tickets - caseId/guardianId

    • Where: toto-bo ticket creation form
    • Action: Add dropdown to link ticket to case/guardian
    • Impact: Better ticket organization and tracking

  3. Users - rating and reviews

    • Where: toto-app profile screen, GuardianDetailsModal
    • Action: Display star rating and reviews
    • Impact: User trust and transparency

Medium Priority​

  1. Follows - notificationsEnabled

    • Where: toto-app settings or follow details
    • Action: Add toggle to enable/disable notifications for follows
    • Impact: Better user control

  2. Conversations - actionTaken

    • Where: toto-app inbox/conversation list
    • Action: Show badges (e.g., "Donation Made", "Shared")
    • Impact: Visual feedback on conversation outcomes

  3. Conversations - isArchived

    • Where: toto-app inbox
    • Action: Add archive/unarchive functionality
    • Impact: Better conversation management

  4. Donations - verifiedAt

    • Where: toto-app profile donation history
    • Action: Display verification timestamp
    • Impact: Transparency on verification status

Low Priority​

  1. Support Tickets - Related case/guardian display
    • Where: toto-bo ticket details view
    • Action: Show linked case/guardian information
    • Impact: Better context for ticket resolution

Next Steps​

  1. Clean Up Unused Collections

    • Review and remove: waitlist, analytics, chats, analytics_cache, accounts, sessions, verification_tokens, collaborators
    • Verify they're not used in Cloud Functions or other services

  2. Implement Missing UI Fields

    • Prioritize high-priority items (donation proof, ticket linking, user ratings)
    • Add medium-priority features incrementally
    • Document low-priority items for future consideration

  3. Migration Script

    • Create migration script to update existing Firestore documents to match new base models
    • Test migration on staging before production

  4. Documentation Updates

    • Update API documentation with new field names
    • Update developer guides with base model references
    • Create migration guide for existing data

Files Created/Updated​

Base Models (Single Source of Truth)​

  • toto-docs/app/docs/architecture/case-base-model.ts
  • toto-docs/app/docs/architecture/user-base-model.ts
  • toto-docs/app/docs/architecture/donation-base-model.ts
  • toto-docs/app/docs/architecture/follow-base-model.ts
  • toto-docs/app/docs/architecture/case-update-base-model.ts
  • toto-docs/app/docs/architecture/conversation-base-model.ts
  • toto-docs/app/docs/architecture/support-ticket-base-model.ts

Analysis Documents​

  • toto-docs/app/docs/architecture/user-model-analysis.md
  • toto-docs/app/docs/architecture/donation-model-analysis.md
  • toto-docs/app/docs/architecture/follow-model-analysis.md
  • toto-docs/app/docs/architecture/case-update-model-analysis.md
  • toto-docs/app/docs/architecture/conversation-model-analysis.md
  • toto-docs/app/docs/architecture/support-ticket-model-analysis.md

Implementation Summaries​

  • toto-docs/app/docs/architecture/conversation-model-summary.md
  • toto-docs/app/docs/architecture/support-ticket-model-summary.md

Conclusion​

All major user-facing entities have been reviewed, standardized, and documented. Each entity now has:

  • ✅ A base model as single source of truth
  • ✅ Consistent field names and types
  • ✅ Proper validation and constraints
  • ✅ Clear documentation

The remaining work focuses on:

  • UI implementation of missing fields
  • Cleanup of unused collections
  • Migration of existing data
  • Testing and validation