Skip to main content

Project Requirements & Specifications

🎯 Project Overview​

Toto is an advanced pet rescue platform that combines social media engagement with intelligent AI conversations to connect pets in need with potential adopters, donors, and volunteers.

Mission Statement​

To save pet lives through technology by creating meaningful connections between rescue organizations and the community, while providing intelligent assistance throughout the entire rescue journey.

🚀 Vision: Proactive, Collaborative, and Self-Improving AI​

  • Collaborative Agent Model: Multiple agents can contribute to a single, unified response, enabling nuanced, multi-intent conversations (e.g., empathy + donation guidance in one reply).
  • MetaAgent/AnalystAgent: Automated system learning and insight generation. Monitors agent performance, detects weaknesses, and synthesizes actionable improvement suggestions.
  • Disambiguation Mode: The Orchestrator asks clarifying questions when user intent is ambiguous, empowering users and reducing misrouting.
  • Proactive State-Aware Guidance: Agents (e.g., AdoptionAgent) provide users with clear progress updates and next steps, improving navigation and reducing confusion.
  • Trackable Links: SharingAgent integrates with URL shorteners to provide users with feedback on the impact of their shares.
  • Full Gemini Context Window: Leverages Gemini 1.5's million-token context window for deep conversational memory and continuity.
  • Retrieval-Augmented Generation (RAG): Answers are grounded in a trusted, up-to-date knowledge base, reducing hallucinations and repetition.

Development Environment Information​

🔧 System Details:

  • Operating System: Windows
  • Shell: PowerShell (C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe)
  • Workspace Path: /c%3A/Users/tcost/VS/toto

⚠️ Important Note: All commands in this document should use PowerShell syntax, not Unix/Linux commands.

🤖 AI System​

Current System: The Toto AI system is toto-ai-hub - a clean, focused AI agent system built specifically for the Toto pet rescue platform. For complete documentation, see the AI System Documentation.

Current AI System (toto-ai-hub)​

  • CaseAgent: Case-specific user interactions and information
  • TwitterAgent: Monitors guardian Twitter accounts and analyzes tweets
  • Deployment: Firebase App Hosting
  • Architecture: Case-focused, clean rewrite with no legacy code
  • Technology: Google Gemini AI, TypeScript, Firebase integration

Intelligence Capabilities​

  • Intent Detection: 11 categories with 95%+ accuracy, now with disambiguation mode
  • Emotional Intelligence: 5 emotional tone categories
  • Context Awareness: Pet-specific information integration, full Gemini context window
  • Bilingual Support: Spanish (Argentina) and English
  • Anti-Repetition: Dynamic content generation, RAG for grounded answers

📋 Implementation Status and Roadmap​

Completed Features​

  • ✅ Multi-agent AI system with emotional intelligence
  • ✅ Advanced intent detection (11 categories)
  • ✅ Image gallery with full-screen preview and navigation
  • ✅ Bilingual support (Spanish/English)
  • ✅ Firebase integration (Auth, Firestore, Functions, Storage)
  • ✅ Role-based access control (User, Guardian, Admin)
  • ✅ Responsive UI with dark/light theme switching
  • ✅ Comprehensive testing suite
  • ✅ Guardian invitation system
  • ✅ Case management workflows
  • ✅ Automated deployment pipeline
  • ✅ Firebase Integration: Project fully integrated with Firebase Authentication, Firestore, and Storage
  • ✅ User Authentication: Email and password authentication with Firebase
  • ✅ Role-Based Access System: Defined roles (user, guardian, admin) with appropriate permissions
  • ✅ Firestore Data Models: Structured data models for users, pets, donations, posts, invitations
  • ✅ Security Rules: Implemented Firestore security rules to enforce permissions
  • ✅ Case Browsing: Basic interface for viewing pet rescue cases
  • ✅ Case Creation: Form for guardians to create new rescue cases
  • ✅ Dashboard UI: Responsive dashboard with role-based navigation
  • ✅ Theme Support: Light/dark mode with system preference detection
  • ✅ Notifications UI: Interface for displaying system notifications
  • ✅ Account Management: Separated profile and settings functionality
  • ✅ Cloud Vision Integration: Automatic pet detection and image processing
  • ✅ Testing Infrastructure: Comprehensive Jest and RTL setup for frontend components
  • ✅ Invitation Code Validation: Verification of invitation codes during signup
  • ✅ Messaging System: Complete inbox interface with conversation management
    • ✅ Responsive Inbox Component: Full and compact modes for different screen sizes
    • ✅ Real-time Search: Filter conversations by case name or message content
    • ✅ Conversation Management: Archive, select, and navigate conversations
    • ✅ Visual Indicators: Unread message badges and status indicators
    • ✅ Auto-selection: Pre-select conversations via case ID for seamless navigation
    • ✅ Professional UI: Chevron navigation, 2-line message previews, and polished styling
    • ✅ Message Display: Full conversation view with message threading and timestamps

🚧 In Progress​

  • 🔄 Stripe payment integration for donations
  • 🔄 Real-time notification system
  • 🔄 Advanced analytics dashboard
  • 🔄 Enhanced social media sharing
  • 🔄 Guardian Invitation Admin Panel: Interface for admins to generate and manage invitation codes
  • 🔄 Social Posts Management: Interface for guardians to track and share social media posts about cases

⏳ Planned Features​

  • ⏳ Collaborative agent response composition
  • ⏳ MetaAgent/AnalystAgent for automated insight analysis and system learning
  • ⏳ Disambiguation mode for ambiguous/multi-intent user inputs
  • ⏳ Proactive, state-aware guidance in AdoptionAgent and other flows
  • ⏳ Trackable links and impact feedback in SharingAgent
  • ⏳ Full Gemini context window for deep conversational memory
  • ⏳ Retrieval-Augmented Generation (RAG) for grounded, non-repetitive, and safe responses

🛣️ Development Roadmap​

Q1 2025 - Intelligence Enhancement​

  • Collaborative Agent Responses: Multi-agent input for unified, nuanced replies
  • MetaAgent/AnalystAgent: Automated insight analysis and system learning
  • Conversation Memory: Persistent user preferences and history (full Gemini context window)
  • Multi-turn Context: Complex conversation management
  • Voice Integration: Speech capabilities
  • Image Analysis: Gemini Vision for pet photos

Q2 2025 - Platform Expansion​

  • Trackable Links: SharingAgent integration with URL shorteners
  • RAG: Retrieval-Augmented Generation for grounded, non-repetitive answers
  • Payment Gateway: Complete Stripe integration
  • Mobile Application: React Native cross-platform
  • Volunteer Portal: Volunteer matching system
  • Advanced Analytics: Detailed insights dashboard

Q3-Q4 2025 - Scale & Growth​

  • Multilingual Support: Portuguese and French
  • API Ecosystem: Public APIs for shelters
  • Community Features: User-to-user communication
  • Advanced Workflows: Automated case updates

2026+ - Innovation & AI​

  • Predictive Analytics: Adoption success prediction
  • AI Training Pipeline: Continuous learning
  • Global Expansion: Multi-country rescue network
  • Blockchain Integration: Transparent donation tracking

🏗️ Technical Architecture​

Frontend Stack​

  • Next.js 15: React framework with SSR/SSG
  • TypeScript: Full type safety
  • Tailwind CSS + shadcn/ui: Modern styling
  • Zustand: State management
  • Firebase Auth: Authentication

Backend Infrastructure​

  • Firebase Firestore: NoSQL database
  • Firebase Functions: Serverless backend
  • Firebase Storage: Media storage
  • Google Gemini: AI language models
  • toto-ai-hub: AI agent system (deployed service)

AI System​

  • Current Implementation: toto-ai-hub (Firebase App Hosting)
  • Architecture: Case-focused agents (CaseAgent, TwitterAgent, InstagramAgent)
  • Deployment: Firebase App Hosting
  • Capabilities: Case-specific interactions, social media monitoring, conversational AI
  • Note: The AI system is toto-ai-hub, deployed via Firebase App Hosting. See AI System Documentation for details.

📊 Performance Metrics​

Current Performance​

  • AI Response Time: <2s average
  • Intent Accuracy: 95%+ with confidence >0.7
  • Page Load Time: <3s initial load
  • Test Coverage: 85%+ across modules
  • Uptime Target: 99.9%

AI Intelligence​

  • Language Support: Spanish (Argentina) + English
  • Context Awareness: Full pet and case integration
  • Emotional Recognition: 5 emotional tone categories
  • Agent Specialization: 6 specialized conversation types

🔒 Security & Privacy​

Current Security​

  • Firebase Security Rules: Comprehensive access control
  • Role-based Permissions: User, Guardian, Admin
  • API Key Management: Secure environment variables
  • Data Encryption: At-rest and in-transit

Privacy Features​

  • Data Minimization: Only necessary context processed
  • User Privacy: No personal data stored in AI responses
  • Audit Trails: All interactions logged
  • GDPR Compliance: European data protection standards

📈 Success Metrics & KPIs​

User Engagement​

  • Active Users: Monthly and daily active users
  • Conversion Rate: Visitor to donor/adopter conversion
  • Session Duration: Average platform engagement time
  • Retention Rate: User return patterns

Platform Impact​

  • Adoption Success: Pets successfully placed
  • Fundraising Efficiency: Donation conversion rates
  • AI Effectiveness: Conversation satisfaction scores
  • Platform Growth: User base and case volume growth

📋 Additional Firebase Collections​

Implemented Collections​

  • users: User profiles and authentication data
  • pets/cases: Rescue case information
  • donations: Donation records and payment info
  • sharedPosts: Links to social media posts
  • invitations: Guardian invitation codes

Planned Collections​

  • notifications: User-specific system notifications
  • analytics: System-wide metrics and statistics
  • settings: Application configuration settings

📋 Testing Infrastructure​

Implemented Testing​

  • ✅ Unit Testing: Jest and React Testing Library for component tests
  • ✅ Auth Component Tests: Comprehensive testing of authentication flows
  • ✅ Mocking: Firebase service mocks for isolated component testing

Planned Testing​

  • 🔄 Integration Tests: Testing interactions between multiple components
  • ⏳ E2E Tests: End-to-end testing of critical user flows
  • ⏳ Firebase Rules Tests: Testing security rule enforcement

Testing Strategy​

  • Unit Testing: Jest with 85%+ coverage
  • Integration Testing: API and database testing
  • E2E Testing: Complete user workflow validation
  • AI Testing: Conversation accuracy and intent recognition
  • Performance Testing: Load and stress testing

Quality Standards​

  • TypeScript: Strict mode enabled
  • Code Review: All changes reviewed
  • Accessibility: WCAG 2.1 AA compliance
  • Performance: Lighthouse score >90

🔄 Automated Cloud Functions Deployment​

  • All Google Cloud Functions must be deployed using a Linux environment to ensure native modules (e.g., sharp) are built for compatibility with Google Cloud Functions runtime.
  • Docker Desktop is required for this workflow. Install Docker Desktop and ensure it is running before deploying.
  • Use the provided deploy-functions.ps1 script in the project root to automate the build and deploy process:
# From the project root (where firebase.json is):
./deploy-functions.ps1

  • The script will:

    • Mount your project into a Node 20 Linux Docker container
    • Clean and reinstall dependencies for Linux (including native modules)
    • Install the Firebase CLI
    • Deploy functions using your Firebase CI token

  • Firebase CI Token:

    • The script uses the FIREBASE_TOKEN environment variable for authentication. You can set this in your environment or edit the script to include your token.
    • To generate a token, run firebase login:ci on your host and copy the token into your environment or the script.

  • This workflow ensures that all native modules are built for Linux and prevents deployment issues on Google Cloud Functions.

Sample Data Coverage Checklist​

  • All new fields in the Firestore data model are added to the sample data script and JSON.
  • Edge cases (refunded donations, expired invitations, incomplete profiles) are represented in the sample data.
  • Sample data for new collections (e.g., notifications, analytics) is created as soon as those features are implemented.
  • Frontend and backend gracefully handle missing or optional fields in both sample and production data.

Limitations of Sample Data​

  • Some fields present in the production model (e.g., originalStoragePath, additionalImages, paymentIntentId, donorEmail, completedAt) may be missing or empty in sample data.
  • Planned collections (notifications, analytics, settings) are not yet included in the sample data.
  • Edge cases (e.g., refunded donations, expired invitations) may not be fully represented.

Recommendation: Keep the sample data in sync with the production model and update it whenever new fields or collections are added.

📋 Project Status Summary​

🎯 Current Version: toto-ai-hub (v1.0.0) - Clean rewrite, case-focused architecture
📅 Last Updated: January 2025
🚀 Development Status: Active with enhanced AI capabilities
📊 Platform Maturity: Production-ready with advanced features

Key Achievements​

  1. Advanced AI System: Multi-agent architecture with emotional intelligence
  2. Complete UI/UX: Modern, responsive design with accessibility
  3. Robust Backend: Scalable Firebase infrastructure
  4. Security: Comprehensive access control and data protection
  5. Testing: Thorough quality assurance processes

Next Milestones​

  1. Payment Integration: Complete Stripe implementation
  2. Mobile App: React Native cross-platform application
  3. Advanced Analytics: Comprehensive insights dashboard
  4. AI Enhancement: Conversation memory and voice integration

This document serves as the authoritative guide for Toto platform development, ensuring alignment across all stakeholders and providing a clear roadmap for future enhancements.