Database Management Scripts

🎯 Overview

This guide covers the database management scripts for the Toto platform, including seeding sample data, cleaning, auditing, and deploying enriched cases optimized for AI conversation responses.

📁 File Structure

🔧 Main Scripts

• db-manager.js - Unified Node.js database manager
• deploy-db.ps1 - PowerShell interface for Windows users
• package.json - Dependencies for the scripts

📊 Data Files

• enriched-sample-cases.json - Rich case data with detailed stories and medical info optimized for AI responses

📖 Documentation

• README.md - Comprehensive guide
• ENRICHED_CASES_README.md - Detailed documentation for enriched cases

🚀 Quick Start

Windows PowerShell (Recommended)

# Check current database status
.\deploy-db.ps1 status

# Deploy enriched cases (recommended)
.\deploy-db.ps1 deploy

# Full reset with enriched data
.\deploy-db.ps1 reset -Force

Direct Node.js Usage

# Install dependencies
npm install

# Show available commands
node db-manager.js

# Deploy enriched cases
node db-manager.js deploy

# Check status
node db-manager.js status

📋 Available Commands

Command	Description	Data Impact
status	Show current database state	Read-only
reset	Full reset + deploy enriched data	⚠️ Deletes all data
deploy	Deploy enriched sample cases	⚠️ Cleans existing cases
clean	Clean database only	⚠️ Deletes collections
clean-storage	Clean storage only	⚠️ Deletes uploaded files
users	Add/update users only	Minimal impact

🎨 Enriched Cases Features

✨ What Makes These Cases Special

• 🏥 Specific Medical Details: "Artritis en caderas y codos" instead of generic "necesita ayuda"
• ⏰ Exact Timeframes: "24 horas", "72 horas", "12 horas" instead of vague urgency
• 🚫 Anti-Repetition System: No more "segura y transparente" in every AI response
• 💝 Emotional Connection: Unique pet personalities and visual details
• 🎯 Platform Awareness: No redundant "visita el sitio web" messages
• 🇦🇷 Argentine Context: Localized locations and culturally appropriate content

🐕 Case Examples

• Luna: Terrier mix, malnutrition emergency (24h timeframe)
• Rusty: Pointer mix, abandoned hunting dog, rehabilitation needed
• Shadow: Shepherd mix, arthritis treatment (72h timeframe)
• Coal: Labrador mix, behavioral training for protective instincts
• Daisy: Poodle mix, eye infection emergency (12h critical timeframe)
• Brutus: Pitbull mix, challenging breed stereotypes
• Goldie: Golden retriever, lost pet with disorientation
• Whisper: Greyhound mix, retired racer transitioning to home life
• Jax: Boxer mix, ear surgery needed (48h timeframe)
• Granny: Chihuahua mix, senior care needs (24h timeframe)

🛠️ Prerequisites

Required Software

• Node.js 18+ (20+ recommended)
• PowerShell 5.1+ (for Windows users)

Required Files

• Firebase authentication: Uses default credentials or environment variables
• Case images in: ../public/sample_cases_images/
• Enriched cases data: enriched-sample-cases.json

Auto-Installed Dependencies

• firebase-admin - Firebase database and auth
• @google-cloud/storage - Image upload and storage
• sharp - Image optimization and conversion

📖 Detailed Usage

1. Check Database Status

.\deploy-db.ps1 status

Shows current document counts and case details.

2. Deploy Enriched Cases (Recommended)

.\deploy-db.ps1 deploy

What it does:

• ✅ Creates demo guardian auth user
• 🗑️ Cleans existing database collections
• 👥 Adds sample users (3 users)
• 🐕 Processes and uploads 10 enriched cases
• 🖼️ Optimizes images to WebP format (5 images per case)
• 📊 Includes realistic medical histories and social metrics

3. Full Reset

.\deploy-db.ps1 reset -Force

Use when: Starting completely fresh or after major changes What it does: Everything from deploy + cleans storage completely

4. Clean Operations

.\deploy-db.ps1 clean          # Database only
.\deploy-db.ps1 clean-storage  # Storage only

🎯 Recommended Workflow

For Development

1. Initial Setup: .\deploy-db.ps1 reset -Force
2. Regular Updates: .\deploy-db.ps1 deploy
3. Check State: .\deploy-db.ps1 status

For Testing AI Improvements

1. Before Changes: .\deploy-db.ps1 status (document current state)
2. Deploy Enhanced Data: .\deploy-db.ps1 deploy
3. Test Conversations: Verify AI responses are specific and non-repetitive
4. Verify Improvements: Check that responses mention specific medical conditions

For Production Preparation

1. Clean Deploy: .\deploy-db.ps1 reset -Force
2. Verify: .\deploy-db.ps1 status
3. Test All Features: Cases, donations, updates, AI conversations

🤖 AI Agent Integration

The enriched cases are specifically designed to work with the improved DialogAgent:

Before (Generic Responses)

USER: "¿Por qué Luna es urgente?"
AGENT: "Luna necesita ayuda urgentemente. En Toto podés donar de forma segura y transparente..."

After (Enriched Cases)

USER: "¿Por qué Luna es urgente?"
AGENT: "Luna tiene desnutrición severa y posible hipotermia. Su peso está 40% por debajo del normal y necesita atención veterinaria en las próximas 24 horas para evitar complicaciones fatales."

More Examples

USER: "¿Qué le pasa a Shadow?"
AGENT: "Shadow sufre artritis en caderas y codos que le causa dolor significativo. Necesita tratamiento en las próximas 72 horas para evitar deterioro irreversible de sus articulaciones."

USER: "¿Por qué Daisy es crítica?"
AGENT: "Daisy tiene infecciones oculares severas que pueden causar pérdida de visión permanente. Es crucial actuar en las próximas 12 horas para salvar su vista."

🚨 Troubleshooting

Common Issues

1. "enriched-sample-cases.json not found"

# Check file exists
Test-Path "enriched-sample-cases.json"

2. "Images not found"

# Check images directory
Get-ChildItem "../public/sample_cases_images" -Filter "*.png"

3. "Sharp installation failed"

# Manual Sharp installation
npm install --include=optional sharp

4. Permission errors

# Run as Administrator or check PowerShell execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Debug Mode

# Verbose output for debugging
.\deploy-db.ps1 deploy -Verbose

📊 What Gets Created

Database Collections

• users (3 docs): Demo guardian + sample users
• cases (10 docs): Enriched pet rescue cases with full details
• updates (auto-generated): Contextual progress updates for each case
• donations (auto-generated): Realistic donation histories

Storage Structure

enriched_cases/
├── luna_main.webp           # Main case images
├── luna_1.webp             # Gallery images
├── luna_2.webp
├── luna_3.webp
├── luna_4.webp
├── rusty_main.webp
├── rusty_1.webp
└── ...

Medical Categories Covered

• Malnutrition & Emergency Care: Luna, Daisy
• Arthritis & Senior Care: Shadow, Granny
• Behavioral & Training: Coal, Brutus
• Surgical Needs: Jax (ear surgery)
• Lost Pet Recovery: Goldie
• Breed Transitions: Whisper (racing), Rusty (hunting)

📞 Support

Need Help?

1. Check Status: .\deploy-db.ps1 status
2. Verbose Mode: .\deploy-db.ps1 deploy -Verbose
3. Review Logs: Check console output for specific error messages
4. Documentation: Read ENRICHED_CASES_README.md for detailed case information

Common Success Indicators

• ✅ "Operation completed successfully!"
• ✅ "Added 10 enriched cases"
• ✅ "Uploaded and optimized: [image]"
• ✅ "Added 3 users"
• ✅ Case details showing specific locations and medical conditions

Next Steps After Deployment

1. Test Frontend: Check that cases display correctly with optimized images
2. Test AI Agent: Try conversations about specific medical conditions
3. Verify Images: Ensure all case images load properly
4. Test Urgency: Check that timeframes are displayed correctly

🎯 Toto Admin CLI

This CLI tool manages Firestore and Storage for the Toto platform, including seeding sample data, cleaning, auditing, and deploying enriched cases.

Usage

Run the CLI from the scripts directory:

node toto-admin.js <command> [options]

Commands

seed

Seeds users and enriched sample cases into Firestore.

Options:

• --data, -d Path to the enriched sample cases JSON file (default: enriched-sample-cases.json)

Example:

node toto-admin.js seed --data enriched-sample-cases.json

clean

Cleans Firestore collections and Storage buckets used by the platform.

Example:

node toto-admin.js clean

audit

Audits image references in Firestore against Storage to find orphaned or missing images.

Example:

node toto-admin.js audit

deploy

Deploys enriched sample cases to Firestore.

Options:

• --data, -d Path to the enriched sample cases JSON file (default: enriched-sample-cases.json)

Example:

node toto-admin.js deploy --data enriched-sample-cases.json

Data Validation

The CLI validates the structure of your sample data file before seeding or deploying. If the data does not match the expected schema, the operation will abort with an error.

Requirements

• Node.js
• Firebase Admin SDK credentials (see project setup)
• All dependencies installed (npm install in the scripts directory)

Notes

• You can still use the original db-manager.js for advanced or legacy operations.
• For more details on enriched sample cases, see ENRICHED_CASES_README.md.

---

🎉 The enriched database management system provides specific, engaging, and medically accurate content optimized for AI conversations and user engagement!