Skip to main content

🐾 Toto App Setup Guide

📋 Overview​

A modern platform connecting users with pets in need through an engaging reels-style feed, secure donations, and intelligent AI-powered assistance.

📘 General Setup: For general ecosystem setup and prerequisites, see the Development Setup Guide.

🚀 Quick Start​

Prerequisites​

  • Node.js 18+
  • Firebase project setup
  • Environment variables configured

Development​

# Install dependencies
npm install

# Start development server (runs on port 4000)
npm run dev

# Run tests
npm test

# Build for production
npm run build

Deployment​

# Deploy to Firebase App Hosting
firebase deploy --only hosting

🏗️ Architecture​

Technology Stack​

  • Frontend: Next.js with TypeScript, Tailwind CSS, shadcn/ui
  • Backend: Next.js API Routes (current implementation)
  • Database: Firebase Firestore
  • Authentication: Firebase Auth
  • Deployment: Firebase App Hosting
  • AI Integration: toto-ai-hub for conversational AI

Key Features​

  • Reels-style Feed: Engaging pet rescue content
  • Secure Donations: Integrated payment processing
  • AI Assistant: Intelligent pet rescue assistance
  • User Management: Complete user account system
  • Case Management: Pet rescue case tracking

🔧 Development Scripts​

Core Scripts​

# Development
npm run dev                    # Start development server (port 4000)
npm run build                  # Build for production
npm run start                  # Start production server
npm run lint                   # Run ESLint

# Testing
npm run test                   # Run Jest tests
npm run test:watch             # Run tests in watch mode
npm run test:coverage          # Generate coverage report
npm run test:e2e               # Run Playwright E2E tests
npm run test:e2e:ui            # Run E2E tests with UI
npm run test:e2e:headed        # Run E2E tests with browser UI
npm run test:e2e:debug         # Run E2E tests in debug mode
npm run test:e2e:report        # Show E2E test report
npm run test:e2e:install       # Install Playwright browsers
npm run test:migration         # Run migration tests

Storybook & Analysis​

npm run storybook              # Start Storybook dev server
npm run build-storybook        # Build Storybook for production
npm run analyze                # Analyze bundle size
npm run analyze:next           # Next.js bundle analysis
npm run bundle:size            # Check bundle size limits

UI & Screenshots​

npm run capture:ui             # Capture UI screenshots
npm run capture:ui:local       # Capture local UI screenshots

🔐 Environment Configuration​

Required Environment Variables​

Firebase Configuration​

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

API Configuration​

GOOGLE_AI_API_KEY=your_google_ai_key
JWT_SECRET=your_jwt_secret
STRIPE_SECRET_KEY=your_stripe_secret_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key

Environment Settings​

NODE_ENV=development|staging|production
NEXT_PUBLIC_ENVIRONMENT=dev|stg|prod

Monitoring Integration​

# Production
NEXT_PUBLIC_TOTO_BO_MONITORING_URL=https://bo.betoto.pet/api/monitoring
NEXT_PUBLIC_TOTO_BO_API_KEY=your_api_key

# Staging
NEXT_PUBLIC_TOTO_BO_MONITORING_URL=https://stg.bo.betoto.pet/api/monitoring
NEXT_PUBLIC_TOTO_BO_API_KEY=your_staging_api_key

# Development
NEXT_PUBLIC_TOTO_BO_MONITORING_URL=http://localhost:5000/api/monitoring
NEXT_PUBLIC_TOTO_BO_API_KEY=your_dev_api_key

🔐 Security Implementation​

Security Headers​

  • HSTS: HTTP Strict Transport Security
  • CSP: Content Security Policy with nonce support
  • X-Frame-Options: Clickjacking protection
  • Permissions Policy: Comprehensive feature restrictions
  • Cross-Origin Policies: COEP, COOP, CORP headers

Rate Limiting​

  • Authentication Endpoints: Strict rate limiting
  • Donation Endpoints: Special rate limiting
  • Case Creation: Special rate limiting
  • API Endpoints: Standard rate limiting

Authentication​

  • Firebase Auth: Secure authentication system
  • JWT Tokens: Secure token-based authentication
  • Session Management: Secure session handling

📊 Performance Features​

Optimization​

  • Image Optimization: Next.js image optimization
  • Code Splitting: Automatic code splitting
  • Bundle Optimization: Optimized bundle sizes
  • CDN Integration: Global content delivery

Monitoring​

  • Performance Monitoring: Real-time performance tracking
  • Error Tracking: Comprehensive error monitoring
  • Analytics: User behavior analytics
  • Health Checks: Application health monitoring

🧪 Testing Strategy​

Test Coverage​

  • Unit Tests: Component and utility testing
  • Integration Tests: API and service testing
  • E2E Tests: End-to-end user journey testing
  • Performance Tests: Performance benchmarking

Test Categories​

  • API Testing: All API endpoint testing
  • Component Testing: React component testing
  • Authentication Testing: Auth flow testing
  • Payment Testing: Payment integration testing

🚀 Deployment​

Environment Setup​

  • Staging: toto-f9d2f-stg project
  • Production: toto-f9d2f project
  • Domain: stg.betoto.pet (staging), betoto.pet (production)

Deployment Process​

  1. Build: Next.js build process
  2. Test: Automated testing suite
  3. Deploy: Firebase App Hosting deployment
  4. Health Check: Post-deployment verification
  5. Monitor: Real-time monitoring activation

Firebase CLI Secrets​

# Production Secrets
toto-f9d2f-jwt-secret
toto-f9d2f-firebase-api-key
toto-f9d2f-firebase-sender-id
toto-f9d2f-firebase-app-id
toto-f9d2f-stripe-secret-key
toto-f9d2f-stripe-publishable-key
toto-f9d2f-google-ai-key

# Staging Secrets
toto-f9d2f-stg-jwt-secret
toto-f9d2f-stg-firebase-api-key
toto-f9d2f-stg-firebase-sender-id
toto-f9d2f-stg-firebase-app-id
toto-f9d2f-stg-stripe-secret-key
toto-f9d2f-stg-stripe-publishable-key
toto-f9d2f-stg-google-ai-key

🔗 Integration​

toto-bo Integration​

  • Monitoring: Real-time monitoring data sent to toto-bo
  • Analytics: User behavior and performance analytics
  • Error Reporting: Error data sent to toto-bo
  • Health Checks: Health status reporting

toto-ai-hub Integration​

  • AI Assistant: Conversational AI for pet rescue assistance
  • Case-Specific Interactions: Intelligent case information and recommendations
  • Social Media Monitoring: Automated Twitter and Instagram monitoring for guardians
  • Chat Support: Intelligent chat support system

toto-wallet Integration​

  • Payment Processing: Secure donation processing
  • Transaction Management: Complete transaction tracking
  • Financial Reporting: Donation and financial analytics

📚 Documentation​

API Documentation​

  • RESTful APIs: Complete API endpoint documentation
  • Authentication: Authentication and authorization guides
  • Payment APIs: Payment processing documentation
  • Error Handling: Error response documentation

User Guides​

  • User Guide: Complete user interface guide
  • Developer Guide: Development and integration guide
  • Deployment Guide: Deployment procedures and troubleshooting
  • Security Guide: Security features and best practices

🔗 Related Projects​

📄 License​

MIT License - see project repository for license details.

For detailed documentation, architecture guides, and deployment instructions, please visit the toto-docs repository.