Skip to main content

🏢 Toto Backoffice (toto-bo) Setup Guide

📋 Overview​

A comprehensive administrative interface for the Toto ecosystem, providing powerful tools for managing rescue cases, users, donations, and platform operations.

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

🚀 Quick Start​

Prerequisites​

  • Node.js 18+
  • Firebase project access
  • Service account credentials

Installation​

# Clone the repository
git clone <repository-url>
cd toto-bo

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Firebase credentials

# Run the development server
npm run dev

Sample Data Population​

# Start the development server first
npm run dev

# Then seed the staging database via API endpoint
# PowerShell
Invoke-WebRequest -Uri "http://localhost:5000/api/init-staging-complete" -Method POST -ContentType "application/json"

# Or using cURL
curl -X POST http://localhost:5000/api/init-staging-complete -H "Content-Type: application/json"

This will create:

  • 50 rescue cases (10 active with images, 40 completed)
  • 200 users including 25 guardians
  • 500 donations with realistic patterns
  • 150 case updates and progress reports
  • 300 user follows and engagements
  • Complete backoffice data (tickets, notifications, audit logs)

🏗️ Architecture​

Firebase Integration​

  • Main Project: toto-f9d2f (read-only access)
  • Backoffice Project: toto-bo (read/write access)
  • Collections: Separated by access level and purpose

Deployment Configuration​

  • Staging: Uses Traditional Firebase Hosting (bypasses organization policy issues)
  • Production: Uses Traditional Firebase Hosting (proven working pattern)
  • Build Output: Next.js build to .next/ directory for optimal hosting performance
  • Status: ✅ Successfully deployed and working in staging environment

Data Flow​

Main App (toto-f9d2f) ←→ Backoffice (toto-bo)
├── Cases, Users, Donations (read-only)
└── Admin data, logs, settings (read/write)

🔧 Development Scripts​

Core Scripts​

# Development
npm run dev                    # Start development server
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:all               # Run all test suites

Specialized Testing​

npm run test:api               # Test API endpoints
npm run test:components        # Test React components
npm run test:utils             # Test utility functions
npm run test:integration       # Test integration scenarios
npm run test:unit              # Test unit functions
npm run test:auth              # Test authentication
npm run test:security          # Test security features

Firebase Setup​

npm run setup:firebase         # Setup Firebase configs
npm run setup:firebase:staging # Setup staging Firebase
npm run setup:firebase:production # Setup production Firebase
npm run setup                  # Setup connections
npm run check-connections      # Check Firebase connections
npm run verify                 # Verify setup

Deployment​

npm run deploy                 # Deploy hosting only
npm run deploy:functions       # Deploy functions only
npm run deploy:all             # Deploy everything
npm run deploy:preview         # Deploy preview channel
npm run deploy:staging         # Deploy to staging
npm run deploy:production      # Deploy to production
npm run deploy:blue-green      # Blue-green deployment

Backup & Maintenance​

npm run backup                 # Backup Firestore
npm run backup:staging         # Backup staging
npm run backup:production      # Backup production
npm run backup:incremental     # Incremental backup
npm run backup:cleanup         # Cleanup old backups
npm run backup:list            # List backups

Analysis & Utilities​

npm run analyze                # Analyze bundle
npm run build:analyze          # Build with analysis
npm run capture:ui             # Capture UI screenshots
npm run capture:ui:local       # Capture local UI
npm run migrate                # Migrate to Firebase

🎯 Key Features​

Administrative Tools​

  • Case Management: Complete case lifecycle management
  • User Management: User accounts, roles, and permissions
  • Donation Tracking: Donation management and analytics
  • Content Moderation: Content review and approval
  • Analytics Dashboard: Comprehensive platform analytics

Security Features​

  • Multi-Factor Authentication: TOTP-based MFA
  • Role-Based Access Control: Admin and user role separation
  • Rate Limiting: IP and user-based rate limiting
  • Security Monitoring: Real-time threat detection
  • GDPR Compliance: Complete data subject rights

Monitoring & Analytics​

  • Real-time Monitoring: Performance and security monitoring
  • Health Checks: Comprehensive health monitoring
  • Performance Analytics: Performance metrics and optimization
  • Security Analytics: Security event monitoring
  • Audit Logging: Complete audit trail

🔐 Security Implementation​

Authentication​

  • NextAuth.js: Session-based authentication
  • Google OAuth: Google provider integration
  • MFA Support: TOTP-based multi-factor authentication
  • Session Security: Secure session management

Authorization​

  • Role-Based Access: Admin and user role separation
  • API Protection: Admin-only endpoint protection
  • Permission Validation: Granular permission checks

Security Headers​

  • HSTS: HTTP Strict Transport Security
  • CSP: Content Security Policy with nonce support
  • X-Frame-Options: Clickjacking protection
  • Permissions Policy: Comprehensive feature restrictions

Rate Limiting​

  • IP-based Limiting: IP-based rate limiting
  • User-based Limiting: User-based rate limiting
  • Endpoint-specific: Different limits per endpoint
  • Brute Force Protection: Failed login attempt monitoring

📊 Performance Features​

CDN Integration​

  • Intelligent Caching: Static assets (1 year), dynamic content (1 hour)
  • Compression: Gzip and Brotli compression
  • Image Optimization: WebP/AVIF formats, responsive images
  • Preloading: Critical resource preloading

Performance Monitoring​

  • Real-time Metrics: Page load, API response, database query tracking
  • Performance Alerts: Automated alerting for slow responses
  • Performance Reports: Comprehensive analytics with trends
  • Bundle Optimization: Code splitting and lazy loading

🧪 Testing Strategy​

Test Coverage​

  • Unit Tests: 95%+ coverage across all components
  • Integration Tests: 45+ test cases for all APIs
  • Security Tests: Authentication, authorization, and vulnerability testing
  • Performance Tests: Load testing and benchmarking
  • E2E Tests: Playwright-based end-to-end testing

Test Categories​

  • API Testing: All API endpoint testing
  • Component Testing: React component testing
  • Security Testing: Authentication and authorization testing
  • Performance Testing: Performance benchmarking
  • Integration Testing: Cross-component testing

🚀 Deployment​

Environment Setup​

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

Deployment Process​

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

Blue-Green Deployment (Future)​

  • Zero Downtime: Instant traffic switching
  • Safe Testing: Test new version in production-like environment
  • Quick Rollback: Instant rollback if issues detected
  • Comprehensive Monitoring: Full deployment monitoring

📚 Documentation​

API Documentation​

  • RESTful APIs: Complete API endpoint documentation
  • Authentication: Authentication and authorization guides
  • Rate Limiting: Rate limiting configuration
  • Error Handling: Error response documentation

User Guides​

  • Admin Guide: Complete administrative interface guide
  • Security Guide: Security features and best practices
  • Performance Guide: Performance optimization guide
  • Deployment Guide: Deployment procedures and troubleshooting

🔗 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.