🌱 TrashTag - Campus Cleanup Gamification App

A modern web application that gamifies campus cleanup efforts by allowing users to capture before/after photos, verify cleanups using image difference algorithms, and compete on a leaderboard.

🚀 Features

• Google Authentication - Secure login with Google OAuth
• Image Capture & Verification - Upload before/after photos with AI-powered verification using pixelmatch
• Points System - Earn points for verified cleanups
• Campus Leaderboard - Compete with other users on campus
• Interactive Map - View all cleanup locations on campus (placeholder for Mapbox integration)
• Profile & Badges - Track your progress and unlock achievements
• Modern UI - Beautiful, eco-inspired design with smooth animations using Framer Motion

🛠️ Tech Stack

• Frontend: React 18 + Vite
• Styling: TailwindCSS
• Animations: Framer Motion
• Routing: React Router v6
• Backend: Firebase (Authentication, Firestore, Storage)
• Image Verification: pixelmatch library

📁 Project Structure

trashtag-ar/
├── public/                 # Static assets
│   └── placeholder/        # Placeholder images for badges, map, etc.
├── src/
│   ├── components/         # Reusable components
│   │   ├── auth/          # Authentication components
│   │   ├── layout/        # Layout components (Navbar, etc.)
│   │   └── ui/            # UI components (Button, Card, Badge)
│   ├── contexts/          # React Context providers
│   │   ├── AuthContext.jsx
│   │   └── UserContext.jsx
│   ├── pages/             # Page components
│   │   ├── Home.jsx
│   │   ├── Capture.jsx
│   │   ├── Leaderboard.jsx
│   │   ├── Map.jsx
│   │   └── Profile.jsx
│   ├── services/          # Business logic & API calls
│   │   ├── cleanupService.js
│   │   └── imageVerification.js
│   ├── config/            # Configuration files
│   │   └── firebase.js
│   ├── App.jsx            # Main app component
│   ├── main.jsx           # Entry point
│   └── index.css          # Global styles
├── package.json
├── vite.config.js
├── tailwind.config.js
└── README.md

🔧 Setup Instructions

Prerequisites

• Node.js (v18 or higher)
• npm or yarn
• Firebase account

1. Clone and Install Dependencies

cd trashtag-ar
npm install

2. Firebase Setup

1. Create a Firebase Project

   • Go to Firebase Console
   • Click "Add project" and follow the setup wizard
   • Enable Google Analytics (optional)

2. Enable Authentication

   • In Firebase Console, go to Authentication > Sign-in method
   • Enable Google as a sign-in provider
   • Add your project's authorized domains

3. Create Firestore Database

   • Go to Firestore Database in Firebase Console
   • Click "Create database"
   • Start in test mode for development (remember to set up security rules for production)
   • Choose a location for your database

4. Set up Storage

   • Go to Storage in Firebase Console
   • Click "Get started"
   • Start in test mode for development
   • Choose the same location as your Firestore database

5. Get Firebase Configuration

   • Go to Project Settings (gear icon) > General
   • Scroll down to "Your apps" section
   • Click the web icon (</>) to add a web app
   • Copy the Firebase configuration object

6. Configure Firebase in the App

   • Open src/config/firebase.js
   • Replace the placeholder values with your Firebase config:

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
  appId: "YOUR_APP_ID",
};

3. Set up Firestore Security Rules

Go to Firestore Database > Rules and update with:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Users can read all user data, but only update their own
    match /users/{userId} {
      allow read: if true;
      allow write: if request.auth != null && request.auth.uid == userId;
    }

    // Cleanups can be read by all, created by authenticated users
    match /cleanups/{cleanupId} {
      allow read: if true;
      allow create: if request.auth != null;
      allow update, delete: if request.auth != null &&
        request.resource.data.userId == request.auth.uid;
    }
  }
}

4. Set up Storage Security Rules

Go to Storage > Rules and update with:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /cleanups/{userId}/{allPaths=**} {
      allow read: if true;
      allow write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

5. Run the Development Server

npm run dev

The app will be available at http://localhost:3000

🚀 Deployment to Firebase Hosting

Prerequisites

• Firebase CLI installed (npm install -g firebase-tools)
• Firebase project created and configured
• Environment variables set in .env file

Deployment Steps

1. Login to Firebase

   firebase login

2. Initialize Firebase Hosting (if not already done)

   firebase init hosting

   • Select your Firebase project (trashtag-ar)
   • Public directory: dist
   • Configure as single-page app: Yes
   • Set up automatic builds: No

3. Build the Production Version

   npm run build

   This creates an optimized production build in the dist folder.

4. Deploy to Firebase Hosting

   firebase deploy --only hosting

5. Your app will be live at:

   https://trashtag-ar.web.app
   

   or

   https://trashtag-ar.firebaseapp.com
   

Environment Variables for Production

For production deployment, you'll need to set environment variables in Firebase Hosting:

1. Option 1: Build-time environment variables (recommended)

   • Keep your .env file local (already in .gitignore)
   • Firebase will use the .env file during build if you deploy through CI/CD
   • Or set them in your deployment script

2. Option 2: Use Firebase Functions (for server-side variables)

   • If you need runtime environment variables, consider Firebase Functions

Custom Domain Setup

1. Go to Firebase Console > Hosting
2. Click "Add custom domain"
3. Follow the instructions to verify your domain
4. Update DNS records as instructed

Continuous Deployment

You can set up automatic deployments with GitHub Actions:

1. Create .github/workflows/deploy.yml:

name: Deploy to Firebase Hosting

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          channelId: live
          projectId: trashtag-ar

2. Add FIREBASE_SERVICE_ACCOUNT secret to your GitHub repository

📝 Firestore Collections Structure

users Collection

{
  uid: string,
  displayName: string,
  email: string,
  photoURL: string,
  points: number,
  cleanups: number,
  badges: array,
  createdAt: timestamp
}

cleanups Collection

{
  userId: string,
  userName: string,
  userPhoto: string,
  location: string,
  beforeImageURL: string,
  afterImageURL: string,
  points: number,
  verified: boolean,
  timestamp: timestamp
}

🎨 Design System

• Colors: Green-based palette (primary-* colors in Tailwind config)
• Typography: Inter font family
• Border Radius: Rounded corners (xl, 2xl, 3xl)
• Animations: Framer Motion for smooth transitions

🚧 Future Enhancements

• Mapbox integration for interactive campus map
• Badge icon assets
• More sophisticated image verification (ML-based)
• Social sharing features
• Team/group challenges
• Campus-specific customization
• Mobile app (React Native)
• Push notifications

📱 Mobile Responsive

The app is fully responsive and works on both desktop and mobile devices.

🐛 Troubleshooting

Image Verification Not Working

• Ensure images are in supported formats (JPG, PNG)
• Check browser console for errors
• Verify that pixelmatch is properly installed

Firebase Authentication Issues

• Verify Firebase config is correct
• Check that Google sign-in is enabled in Firebase Console
• Ensure authorized domains are configured

Firestore Permission Errors

• Check Firestore security rules
• Verify user is authenticated before accessing protected data

📄 License

This project is created for educational purposes.

🤝 Contributing

This is a campus-specific project. For contributions, please contact the project maintainers.

---

Built with ❤️ for a cleaner campus 🌱