🌿 GreenLens - AI-Powered Carbon Tracking Platform

Smart & Digital Innovation | Sustainability Hackathon 2026 | Parul University

Track Your Carbon. Change Your Campus.

A production-grade AI-powered sustainability platform built for Indian college students to understand, track, and reduce their personal carbon footprint.

🌐 Live Production Application

Frontend UI (Vercel): https://green-lens-tau.vercel.app
Backend API (Render): https://greenlens-backend-n3ws.onrender.com

📸 Application Preview

🏠 Homepage

📊 Personal Dashboard

📝 Activity Logging (Gemini Vision Scan)

🤖 Personal AI Coach

🏆 Campus Leaderboard

⚡ Quick Start

Prerequisites

Python 3.11+
Node.js 18+
PostgreSQL 14+ (or Docker)
Git

5-Minute Local Setup

1. Clone & Navigate

git clone <your-repo-url>
cd GreenLens

2. Backend Setup

cd backend
pip install -r requirements.txt
copy .env.example .env
python main.py

3. PostgreSQL (Another Terminal)

# Option A: Docker
docker-compose up -d postgres

# Option B: Manual PostgreSQL
# Download from postgresql.org and create database
psql -U postgres
CREATE DATABASE greenlens;

4. Frontend Setup (Third Terminal)

cd frontend
npm install
npm run dev

5. Access Application

📂 Project Structure

GreenLens/
├── backend/                      # FastAPI + PostgreSQL backend
│   ├── main.py                  # Main FastAPI application (15+ endpoints)
│   ├── models.py                # SQLAlchemy ORM models (6 tables)
│   ├── schemas.py               # Pydantic validation schemas
│   ├── auth.py                  # JWT + bcrypt authentication
│   ├── database.py              # PostgreSQL connection setup
│   ├── config.py                # Environment configuration
│   ├── emission_factors.py      # CO2 calculation engine
│   ├── gemini_nudges.py         # Google Gemini AI integration
│   ├── requirements.txt          # Python dependencies
│   ├── Dockerfile               # Container configuration
│   ├── .env.example             # Environment variables template
│   ├── .gitignore               # Git exclusions
│   └── README.md                # Backend documentation
│
├── frontend/                     # React + Vite frontend
│   ├── src/
│   │   ├── App.jsx              # Main app router
│   │   ├── main.jsx             # React entry point
│   │   ├── AuthContext.jsx      # Authentication state management
│   │   ├── ProtectedRoute.jsx   # Route protection
│   │   ├── api.js               # Axios API client
│   │   ├── index.css            # Global styles + animations
│   │   │
│   │   ├── pages/               # 6 complete pages
│   │   │   ├── HomePage.jsx         # Home with live CO₂ counter
│   │   │   ├── AuthPages.jsx        # Login & Register
│   │   │   ├── DashboardPage.jsx    # Personal stats & charts
│   │   │   ├── LogPage.jsx          # Activity logger
│   │   │   ├── CoachPage.jsx        # AI nudges
│   │   │   ├── LeaderboardPage.jsx  # Campus rankings
│   │   │   └── ImpactPage.jsx       # 30-day journey
│   │   │
│   │   └── components/          # Reusable components
│   │       └── Navbar.jsx       # Navigation
│   │
│   ├── index.html               # HTML entry point
│   ├── package.json             # Node dependencies
│   ├── vite.config.js           # Vite bundler config
│   ├── tailwind.config.js       # Tailwind CSS config
│   ├── postcss.config.js        # PostCSS config
│   ├── Dockerfile               # Container configuration
│   ├── .env.example             # Environment template
│   ├── .gitignore               # Git exclusions
│   └── README.md                # Frontend documentation
│
├── docker-compose.yml           # Local development environment
├── QUICKSTART.md                # 5-minute setup guide
├── DEPLOYMENT.md                # Production deployment guide
├── PROJECT_SUMMARY.md           # Detailed project overview
├── START_HERE.txt               # Visual project summary
├── .gitignore                   # Root git exclusions
└── README.md                    # This file

✨ Features

🔐 Authentication

User registration with email validation
Secure JWT-based login
bcrypt password hashing
Protected API endpoints
Session management

📊 Activity Logging

5 Activity Categories:
- Transport (car, bike, bus, metro, flight)
- Food (vegetarian, non-vegetarian, vegan, dairy, meat)
- Electricity (kWh with Indian grid intensity)
- Purchases (clothing, electronics, household)
- Waste (plastic, paper, organic)
Real-time CO₂ Calculation using Indian emission factors
Activity history & trends
Personal activity timeline

🎮 Gamification

XP points system (10 points per kg CO₂)
Daily streaks tracking
Campus-wide leaderboard
🥇 Gold/Silver/Bronze badges (top 3)
Trees saved equivalent calculation

🤖 AI Features

Google Gemini 1.5 Flash integration
Personalized daily nudges
Context-aware recommendations
Fallback nudges when API unavailable
Conversational AI coach interface

📈 Dashboard

Personal carbon statistics
Weekly emission charts (Recharts)
Activity breakdown by category
Recent activities timeline
Campus-wide impact metrics

🌍 Social Features

Anonymous campus leaderboard
Community impact tracking
30-day sustainability journey
Aggregate campus statistics
Weekly winner announcements

🛠️ Tech Stack

Backend

Technology	Purpose	Version
FastAPI	Web framework	0.104
Uvicorn	ASGI server	0.24
SQLAlchemy	ORM	2.0
PostgreSQL	Database	15
Pydantic	Data validation	2.5
PyJWT	JWT authentication	3.3
bcrypt	Password hashing	4.1
Google Generative AI	AI nudges	0.3
Python-Jose	Token handling	3.3

Frontend

Technology	Purpose	Version
React	UI framework	18.2
Vite	Module bundler	5.0
React Router	Client routing	6.20
Tailwind CSS	Styling	3.3
Recharts	Data visualization	2.10
Lucide	Icons	0.294
Axios	HTTP client	1.6
PostCSS	CSS processing	8.4

DevOps

Technology	Purpose
Docker	Containerization
Docker Compose	Multi-container setup
PostgreSQL	Database

🚀 Setup Instructions

Local Development

Step 1: Install Dependencies

# Backend
cd backend
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

Step 2: Configure Environment

# Backend
cd ../backend
copy .env.example .env
# Edit .env and add:
# - DATABASE_URL (PostgreSQL connection)
# - SECRET_KEY (random 32+ char string)
# - GEMINI_API_KEY (optional, for AI nudges)

# Frontend
cd ../frontend
copy .env.example .env
# VITE_API_URL=http://localhost:8000

Step 3: Set Up Database

Option A: Using Docker (Recommended)

cd ..
docker-compose up -d postgres
# Wait 10 seconds for PostgreSQL to start

Option B: Manual PostgreSQL

# Download from https://www.postgresql.org/download/windows/
# After installation:
psql -U postgres
CREATE DATABASE greenlens;
\q

Step 4: Run Applications

# Terminal 1 - Backend
cd backend
python main.py
# Server running at http://localhost:8000

# Terminal 2 - Frontend
cd frontend
npm run dev
# App running at http://localhost:3000

Step 5: Test the Application

Open http://localhost:3000
Click "Sign Up"
Create account (test@example.com)
Log activities
View dashboard & leaderboard

📤 Deployment

Quick Deployment (10 minutes)

Option 1: Railway (Recommended)

Go to https://railway.app
Create new project
Add PostgreSQL plugin
Deploy backend service
Deploy frontend service
Share public URLs

[Full Railway Guide → See DEPLOYMENT.md]

Option 2: Render

Go to https://render.com
Create PostgreSQL database
Deploy backend web service
Deploy frontend static site

[Full Render Guide → See DEPLOYMENT.md]

Option 3: Docker + VPS

docker-compose up -d

[Full Docker Guide → See DEPLOYMENT.md]

Production Checklist

Set strong SECRET_KEY (32+ random chars)
Configure GEMINI_API_KEY (optional)
Use managed PostgreSQL (don't expose credentials)
Enable HTTPS
Set up monitoring & logs
Configure email notifications (future)
Review security headers
Test all API endpoints
Load test the application

📡 API Documentation

Base URL

http://localhost:8000  (local)
https://your-api.railway.app  (production)

Authentication Endpoints

Method	Endpoint	Purpose
POST	`/api/auth/register`	Create new account
POST	`/api/auth/login`	Get JWT token

Activity Endpoints

Method	Endpoint	Purpose
POST	`/api/activities`	Log new activity
GET	`/api/activities`	Get user activities

Stats Endpoints

Method	Endpoint	Purpose
GET	`/api/user/profile`	Get user details
GET	`/api/stats`	Get personal stats
GET	`/api/dashboard`	Get full dashboard

Social Endpoints

Method	Endpoint	Purpose
GET	`/api/leaderboard`	Get campus rankings
GET	`/api/nudges`	Get AI nudges
PUT	`/api/nudges/{id}`	Mark nudge read

Campus Endpoints

Method	Endpoint	Purpose
GET	`/api/campus-stats`	Get aggregate impact

Full API Docs

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

🏗️ Architecture

System Design

┌─────────────────────────────────────────────────────────────┐
│                        Frontend (React)                      │
│  ┌──────────────┬──────────────┬────────────────────────┐   │
│  │ Home Page    │ Dashboard    │ Activity Logger        │   │
│  │ Auth Pages   │ Leaderboard  │ AI Coach              │   │
│  │ Impact Page  │              │                        │   │
│  └──────────────┴──────────────┴────────────────────────┘   │
│            ↓ HTTP/REST with JWT Bearer Token ↓              │
├─────────────────────────────────────────────────────────────┤
│                    Backend API (FastAPI)                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Authentication │ Activities │ Stats │ Leaderboard     │   │
│  │ CO₂ Calculator │ AI Nudges  │ Realtime Updates     │   │
│  └──────────────────────────────────────────────────────┘   │
│              ↓ SQLAlchemy ORM with Connection Pooling ↓    │
├─────────────────────────────────────────────────────────────┤
│                 PostgreSQL Database                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Users │ Activities │ Stats │ Leaderboard │ Nudges   │   │
│  └──────────────────────────────────────────────────────┘   │
│              ↓ External Services ↓                          │
├─────────────────────────────────────────────────────────────┤
│ Google Gemini 1.5 Flash (AI Nudge Generation)               │
└─────────────────────────────────────────────────────────────┘

Data Flow

User Registration → FastAPI validates → Bcrypt hashes password → Stores in PostgreSQL
Login → FastAPI verifies credentials → Issues JWT token → Frontend stores in localStorage
Log Activity → Frontend sends to API with JWT → FastAPI validates & calculates CO₂ → Stores in DB → Generates AI nudge
View Stats → Frontend requests from API → FastAPI queries DB → Returns aggregated data with charts

🔒 Security Features

✅ Authentication & Authorization

JWT tokens with 30-min expiration
bcrypt password hashing
Protected routes requiring valid token
CORS configured

✅ Data Protection

Pydantic input validation
SQL injection prevention (SQLAlchemy ORM)
Email validation on registration
Rate limiting ready (future)

✅ Environment Security

Secrets in .env files (not in code)
Example files provided (.env.example)
Production database credentials managed

⚠️ Future Enhancements

Rate limiting per IP
Email verification
Two-factor authentication
Audit logging
Data encryption at rest

📊 Database Schema

Users Table

id (PK) | email | username | hashed_password | full_name | campus | created_at | updated_at

Activities Table

id (PK) | user_id (FK) | activity_type | value | unit | co2_kg | description | created_at

UserStats Table

id (PK) | user_id (FK) | total_co2_kg | weekly_co2_kg | streak_days | xp_points | rank | trees_saved | updated_at

Leaderboard Table

id (PK) | user_id (FK) | rank | xp_points | weekly_co2_reduction | streak | username | campus | badge | updated_at

Nudges Table

id (PK) | user_id (FK) | content | category | is_read | created_at

🧪 Testing

Manual Testing Checklist

# 1. Authentication
[ ] Register new user
[ ] Login with credentials
[ ] Token stored in localStorage
[ ] Logout clears token

# 2. Activity Logging
[ ] Log transport activity (10 km)
[ ] Log food activity (1 meal)
[ ] Log electricity (5 kWh)
[ ] See CO₂ calculated correctly
[ ] View in dashboard

# 3. Dashboard
[ ] Load personal stats
[ ] Display weekly chart
[ ] Show recent activities
[ ] Display correct XP points
[ ] Show streak count

# 4. Leaderboard
[ ] Fetch top 50 users
[ ] Display rankings with badges
[ ] Show XP points
[ ] Update in real-time

# 5. AI Features
[ ] Receive nudges on activity log
[ ] Nudges appear in coach page
[ ] Can mark nudges as read
[ ] Fallback nudges display if API down

# 6. API
[ ] GET /docs loads Swagger UI
[ ] All endpoints respond correctly
[ ] JWT protection works
[ ] Error messages are clear

🐛 Troubleshooting

Backend Issues

"ModuleNotFoundError: No module named 'fastapi'"

cd backend
pip install -r requirements.txt

"postgres connection refused"

# Check PostgreSQL is running
docker-compose ps postgres
# Or restart
docker-compose restart postgres

"Port 8000 already in use"

# Use different port
uvicorn main:app --port 8001

Frontend Issues

"Cannot find module 'react'"

cd frontend
npm install

"Blank page after deploy"

Check browser console (F12) for errors
Verify VITE_API_URL is correct
Clear browser cache (Ctrl+Shift+Delete)

"API calls return 404"

Ensure backend is running
Check API URL in .env
Verify JWT token is valid

📈 Performance Tips

Backend

SQLAlchemy connection pooling enabled
Ready for Redis caching
Pagination on list endpoints
Indexed database queries

Frontend

Code splitting enabled in Vite
Lazy loading of pages
Images are optimized
CSS tree-shaking

Database

Indexed on user_id and created_at
Optimized queries
Connection pooling

🚦 CI/CD (Ready to Setup)

GitHub Actions Template

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to Railway
        run: railway up

Pre-commit Checklist

📚 Additional Resources

Resource	Link
FastAPI Docs	https://fastapi.tiangolo.com
React Docs	https://react.dev
PostgreSQL Docs	https://www.postgresql.org/docs/
Tailwind CSS	https://tailwindcss.com
Docker Docs	https://docs.docker.com

📖 Documentation

QUICKSTART.md - 5-minute setup guide
DEPLOYMENT.md - Production deployment (9000+ words)
PROJECT_SUMMARY.md - Detailed project overview
backend/README.md - Backend API documentation
frontend/README.md - Frontend setup guide
START_HERE.txt - Visual project summary

🤝 Contributing

Code Style

Backend: PEP 8 compliance
Frontend: ESLint configuration included
Commits: Clear, descriptive messages

Adding Features

Create feature branch: git checkout -b feature/your-feature
Make changes
Test thoroughly
Push to GitHub
Create Pull Request

Reporting Issues

Include:

Error message (full stack trace)
Steps to reproduce
Expected vs actual behavior
Screenshots if applicable

📄 License

Built for Parul University Sustainability Hackathon 2026

👥 Team

GreenLens Development Team

AI-Powered Sustainability Platform
Smart & Digital Innovation Category
Parul University

🎯 Project Goals

✅ Completed (MVP)

User authentication system
Activity logging engine
CO₂ calculation with Indian factors
Gamification system
AI nudge generation
Campus leaderboard
Responsive UI/UX
Production deployment

🔄 Future Enhancements

Mobile app (React Native)
Advanced analytics dashboard
Real-time notifications
Email notifications
SMS alerts
Data export (CSV/PDF)
Admin panel
API v2 with advanced features

📞 Support & Contact

Getting Help:

Check the documentation files above
Review backend README for API issues
Check frontend README for UI issues
Look at Swagger UI for endpoint details

Deployment Issues:

See DEPLOYMENT.md for step-by-step help
Check Railway/Render dashboard logs

🌱 Impact Goal

Target: 1000+ students tracking carbon in the first semester

By making carbon tracking fun, social, and rewarding, GreenLens aims to:

Increase climate awareness among college students
Drive behavioral change through gamification
Create a culture of sustainability on campus
Measure real environmental impact
Inspire peer-to-peer challenges

5-15% reduction in campus carbon footprint is achievable with active participation.

🚀 Launch Checklist

✨ Track Your Carbon. Change Your Campus.

Built with ❤️ for Parul University Sustainability Hackathon 2026

Start tracking now! 🌱

Last Updated: May 20, 2026
Status: Production Ready
Version: 1.0.0

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
backend		backend
frontend		frontend
screenshots		screenshots
.gitignore		.gitignore
BUILD_COMPLETE.txt		BUILD_COMPLETE.txt
DEPLOYMENT.md		DEPLOYMENT.md
INTEGRATION_COMPLETE.md		INTEGRATION_COMPLETE.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
START_HERE.txt		START_HERE.txt
docker-compose.yml		docker-compose.yml
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

🌿 GreenLens - AI-Powered Carbon Tracking Platform

🌐 Live Production Application

📋 Table of Contents

📸 Application Preview

🏠 Homepage

📊 Personal Dashboard

📝 Activity Logging (Gemini Vision Scan)

🤖 Personal AI Coach

🏆 Campus Leaderboard

⚡ Quick Start

Prerequisites

5-Minute Local Setup

📂 Project Structure

✨ Features

🔐 Authentication

📊 Activity Logging

🎮 Gamification

🤖 AI Features

📈 Dashboard

🌍 Social Features

🛠️ Tech Stack

Backend

Frontend

DevOps

🚀 Setup Instructions

Local Development

📤 Deployment

Quick Deployment (10 minutes)

Option 1: Railway (Recommended)

Option 2: Render

Option 3: Docker + VPS

Production Checklist

📡 API Documentation

Base URL

Authentication Endpoints

Activity Endpoints

Stats Endpoints

Social Endpoints

Campus Endpoints

Full API Docs

🏗️ Architecture

System Design

Data Flow

🔒 Security Features

📊 Database Schema

Users Table

Activities Table

UserStats Table

Leaderboard Table

Nudges Table

🧪 Testing

Manual Testing Checklist

🐛 Troubleshooting

Backend Issues

Frontend Issues

📈 Performance Tips

Backend

Frontend

Database

🚦 CI/CD (Ready to Setup)

GitHub Actions Template

Pre-commit Checklist

📚 Additional Resources

📖 Documentation

🤝 Contributing

Code Style

Adding Features

Reporting Issues

📄 License

👥 Team

🎯 Project Goals

📞 Support & Contact

🌱 Impact Goal

🚀 Launch Checklist

✨ Track Your Carbon. Change Your Campus.

About

Packages