Skip to main content

Development Setup Guide

Overview​

This guide provides step-by-step instructions for setting up the Toto ecosystem development environment.

📘 Project-Specific Setup: For detailed setup instructions for individual projects, see:

Prerequisites​

Required Software​

  • Node.js: Version 18.0.0 or higher
  • npm: Version 9.0.0 or higher (comes with Node.js)
  • Git: Version 2.30.0 or higher
  • Firebase CLI: Version 12.0.0 or higher
  • Code Editor: VS Code recommended with extensions

System Requirements​

  • RAM: Minimum 8GB, recommended 16GB
  • Storage: Minimum 10GB free space
  • OS: Windows 10+, macOS 10.15+, or Ubuntu 18.04+

Initial Setup​

1. Clone Repository​

git clone https://github.com/DataTom7/toto.git
cd toto

2. Install Dependencies​

# Install root dependencies
npm install

# Install dependencies for each project
cd toto-bo && npm install
cd ../toto-landing && npm install
cd ../toto-investors && npm install
cd ../toto-app && npm install
cd ../toto-ai-hub && npm install
cd ..

📘 Project-Specific Setup: For detailed setup instructions for individual projects, see:

3. Firebase Configuration​

# Login to Firebase
firebase login

# Set up projects (if not already configured)
firebase projects:list
firebase use <project-id>

Environment Configuration​

1. Create Environment Files​

# toto-bo
cp toto-bo/.env.example toto-bo/.env.local

# toto-landing
cp toto-landing/.env.example toto-landing/.env.local

# toto-investors
cp toto-investors/.env.example toto-investors/.env.local

2. Configure Environment Variables​

toto-bo (.env.local)​

# NextAuth Configuration
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:5000

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
FIREBASE_WEB_API_KEY=your_firebase_web_api_key
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_PRIVATE_KEY=your_private_key
FIREBASE_CLIENT_EMAIL=your_client_email

toto-landing (.env.local)​

# Google Analytics
NEXT_PUBLIC_GA_ID=G-9NMXQTSQT6

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

toto-investors (.env.local)​

# Google Analytics
NEXT_PUBLIC_GA_ID=G-7ZYW5LDG0T

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

Development Servers​

1. Start Development Servers​

toto-bo (Port 5000)​

cd toto-bo
npm run dev

URL: http://localhost:5000

toto-landing (Port 9001)​

cd toto-landing
npm run dev -- -p 9001

URL: http://localhost:9001

toto-investors (Port 9002)​

cd toto-investors
npm run dev -- -p 9002

URL: http://localhost:9002

2. Verify All Servers​

Open your browser and verify:

  • http://localhost:5000 - Backoffice (toto-bo)
  • http://localhost:9001 - Donor landing (toto-landing)
  • http://localhost:9002 - Investor landing (toto-investors)

Database Setup​

1. Firestore Configuration​

# Navigate to Firebase Console
# https://console.firebase.google.com

# Create collections:
# - users (for user management)
# - cases (for pet rescue cases)

2. Security Rules​

// Firestore security rules for investors collection
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /investors/{investorId} {
      allow read, write: if request.auth != null && 
        (request.auth.token.role == 'admin' || 
         request.auth.token.role == 'staff');
    }
  }
}

3. Indexes​

Create the following Firestore indexes:

  • investors collection: email (unique)
  • investors collection: status + createdAt (composite)
  • investors collection: type + createdAt (composite)

Development Workflow​

1. Code Structure​

toto/
├── toto-bo/                 # Backoffice application
│   ├── src/
│   │   ├── app/            # Next.js app router
│   │   ├── components/     # React components
│   │   ├── lib/            # Utilities and services
│   │   └── types/          # TypeScript interfaces
│   └── server.js           # Custom server
├── toto-landing/           # Donor landing page
│   ├── src/
│   │   ├── app/            # Next.js app router
│   │   ├── components/     # React components
│   │   └── lib/            # Utilities
├── toto-investors/         # Investor landing page
│   ├── src/
│   │   ├── app/            # Next.js app router
│   │   ├── components/     # React components
│   │   └── lib/            # Utilities
└── toto-docs/              # Documentation

2. Development Commands​

Building​

# toto-bo
cd toto-bo && npm run build

# toto-landing
cd toto-landing && npm run build

# toto-investors
cd toto-investors && npm run build

Testing​

# Run tests (if configured)
npm test

# Run linting
npm run lint

# Run type checking
npm run type-check

Development Tools​

# Start all servers concurrently
npm run dev:all

# Build all projects
npm run build:all

# Deploy to development
npm run deploy:dev

🔗 Related Resources​

Common Issues & Solutions​

1. Port Conflicts​

# Check what's using a port
netstat -ano | findstr :5000

# Kill process using port
taskkill /PID <process_id> /F

2. Firebase Authentication Issues​

# Re-authenticate Firebase
firebase logout
firebase login

# Check project configuration
firebase projects:list
firebase use <project-id>

3. Environment Variable Issues​

# Verify environment files exist
ls -la .env*

# Check variable loading
echo $NEXTAUTH_SECRET

4. Database Connection Issues​

# Verify Firestore rules
firebase deploy --only firestore:rules

# Check security rules in Firebase Console
# https://console.firebase.google.com/project/<project-id>/firestore/rules

Performance Optimization​

1. Development Performance​

# Use development mode
NODE_ENV=development npm run dev

# Enable Fast Refresh
FAST_REFRESH=true npm run dev

# Optimize TypeScript compilation
npm run dev -- --turbo

2. Build Optimization​

# Analyze bundle size
npm run build -- --analyze

# Optimize images
npm run build -- --optimize-images

# Enable compression
npm run build -- --compress

Deployment Preparation​

1. Environment Variables​

# Production environment
cp .env.local .env.production

# Update production values
NEXTAUTH_URL=https://bo.betoto.pet
NEXT_PUBLIC_FIREBASE_API_KEY=prod_key

2. Build Verification​

# Build all projects
npm run build:all

# Verify build outputs
ls -la toto-bo/.next
ls -la toto-landing/.next
ls -la toto-investors/.next

3. Firebase Configuration​

# Update firebase.json for production
firebase use production

# Deploy to production
firebase deploy

Development Best Practices​

1. Code Quality​

  • Use TypeScript for all new code
  • Follow ESLint rules
  • Write meaningful commit messages
  • Test components before committing

2. Git Workflow​

# Create feature branch
git checkout -b feature/new-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/new-feature

3. Component Development​

  • Use functional components with hooks
  • Implement proper TypeScript interfaces
  • Follow component naming conventions
  • Use proper error boundaries

4. API Development​

  • Implement proper error handling
  • Use consistent response formats
  • Add input validation
  • Implement rate limiting

Monitoring & Debugging​

1. Development Tools​

  • React DevTools: Browser extension for React debugging
  • Redux DevTools: For state management debugging
  • Network Tab: Monitor API calls
  • Console: Check for errors and warnings

2. Logging​

// Add logging to components
console.log('Component rendered:', props);

// Add logging to API endpoints
console.log('API called:', request.body);

// Add error logging
console.error('Error occurred:', error);

3. Performance Monitoring​

// Measure component render time
console.time('Component render');
// ... component logic
console.timeEnd('Component render');

// Monitor API response times
const start = performance.now();
const response = await fetch('/api/investors');
const end = performance.now();
console.log(`API call took ${end - start}ms`);

Support & Resources​

1. Documentation​

2. External Resources​

3. Team Support​

  • Development Team: Through toto-bo system
  • Technical Issues: GitHub repository issues
  • Feature Requests: Project management system

Last Updated: January 2024
Version: 2.0.0
Status: Production Ready