Spaces:

Akash-Dragon
/

EcoTracker-II

Runtime error

App Files Files Community

EcoTracker-II / README.md

Akash-Dragon

refactor: restructure project as a monorepo and implement backend API

7e49c4d about 1 month ago

preview code

Raw

History Blame

20.9 kB

	---
	title: EcoTracker II
	emoji: 📉
	colorFrom: yellow
	colorTo: purple
	sdk: docker
	pinned: false
	short_description: Backend for the event Prompt Wars
	---

	# EcoTrack AI — Advanced Carbon Footprint Awareness Platform

	EcoTrack AI is a state-of-the-art web application designed to help users measure, understand, and reduce their carbon footprint. Powered by Groq Cloud AI, the platform offers a personalized AI sustainability coach, 30-day carbon reduction action plans, interactive "what-if" simulations, and a gamified leaderboard with streaks, points, and badges to drive user engagement.

	[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
	[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen)](https://nodejs.org/)
	[![Database: Firestore](https://img.shields.io/badge/Database-Firebase_Firestore-orange.svg)](https://firebase.google.com/)
	[![AI: Groq Cloud](https://img.shields.io/badge/AI-Groq_Llama3-blueviolet)](https://groq.com/)
	[![Tests: Passing](https://img.shields.io/badge/Tests-167_Passing-brightgreen)](#testing-and-verification)

	Live Demo: [eco-tracker-ii-123.vercel.app](https://eco-tracker-ii-123.vercel.app/)

	---

	## Table of Contents

	1. [Architecture & Database Transition](#architecture--database-transition)
	2. [Groq AI Integration & Usage](#groq-ai-integration--usage)
	3. [Scientific Calculation & Emission Factors](#scientific-calculation--emission-factors)
	4. [Scoring & Benchmark Interpolation](#scoring--benchmark-interpolation)
	5. [Gamification & Achievements System](#gamification--achievements-system)
	6. [Tech Stack](#tech-stack)
	7. [Security Hardening Techniques](#security-hardening-techniques)
	8. [Folder Structure](#folder-structure)
	9. [Page Use Cases & Features](#page-use-cases--features)
	10. [Installation & Setup](#installation--setup)
	11. [Testing and Verification](#testing-and-verification)

	---

	## Architecture & Database Transition

	Originally built on top of a relational schema using Prisma and PostgreSQL, EcoTrack AI was transitioned to Firebase Firestore to align with modern serverless and document-based practices.

	```
	┌─────────────────────────────────┐ ┌───────────────────────────────┐
	│ React 18 Frontend │ ──────────────► │ Express 4 Backend │
	│ (Vite, Tailwind, Recharts) │ HTTPS/REST │ (Helmet, Rate-Limiting, Zod)│
	└─────────────────────────────────┘ └──────────────┬────────────────┘
	│
	firebase-admin│ groq-sdk
	▼ ▼
	┌───────────────────────────────┐
	│ Firebase Firestore Database │
	│ (Users, Assessments, Streaks)│
	└───────────────────────────────┘
	```

	### Why Firebase Firestore?

	- Document-Centric Model: Carbon assessments and simulation states are inherently tree-like, hierarchical data. A document-based NoSQL database allows storing user metrics and footprints as direct, rich documents rather than performing heavy relational joins.
	- Schema Flexibility: Enables future expansion of assessment categories (e.g., adding home heating types or detailed food options) without writing complex SQL schema migrations.
	- Serverless Scale: Low-latency reads and writes that scale automatically, providing instantaneous calculations and ranking checks.
	- Data Schema Details:
	- `users`: Stores user credentials, streaks, ranks, points, and earned badges.
	- `assessments`: Flat collection storing historical carbon footprints indexed by `userId`.
	- `simulations`: Captures user configuration states for what-if scenarios.

	### Hermetic Test Mocking

	To ensure integration and unit tests run instantly and are completely insulated from external database network states, the backend uses a custom in-memory Firestore engine in [`firebaseClient.js`](./backend/src/utils/firebaseClient.js).

	- When running in `test` environment, the Firebase Admin connection is bypassed.
	- A robust, virtual mock store runs in memory to manage users and assessments, executing 160+ tests in under 5 seconds with zero server dependencies.

	### Version 1 to Version 2 Database Migration

	To preserve history, the backend includes a migration utility in [`migrateDb.js`](./backend/src/utils/migrateDb.js). This script reads historical footprint documents from the V1 subcollection structure (`users/{userId}/history`) and migrates them into flat V2 collections. It parses legacy breakdown objects (extracting transport, electricity, food, waste, and shopping emissions) and populates modern metadata variables automatically.

	---

	## Groq AI Integration & Usage

	EcoTrack AI integrates the Groq SDK to provide lightning-fast, context-aware artificial intelligence. Powered by high-throughput Llama-3 inference models, the AI operates across five main areas:

	1. AI Sustainability Coach (`POST /api/ai/chat`)
	- An interactive chat assistant where users can ask for eco-friendly recommendations.
	- Provides immediate, real-world advice based on the user's specific carbon footprint breakdown.
	2. 30-Day Net-Zero Action Plan (`POST /api/ai/plan`)
	- Generates a step-by-step 30-day timeline designed to lower the user's carbon footprint.
	- Customizes actions depending on whether the user's highest emissions originate from Transport, Energy, Food, or Shopping.
	3. Narrative Score Analysis (`POST /api/ai/score`)
	- Looks at a user's numerical sustainability score and writes a narrative assessment explaining what their rating signifies.
	4. Daily Eco Micro-Tip (`GET /api/ai/tip`)
	- Generates a daily tip centered on sustainable living.
	- Caches tips on the server for 24 hours to minimize API hits.
	5. Narrative Comparison Analysis (`POST /api/ai/compare`)
	- Explains how the user's footprint compares to global averages and the Paris Agreement target (2,000 kg CO₂e/yr).

	---

	## Scientific Calculation & Emission Factors

	EcoTrack AI calculates carbon footprints utilizing annualized kilograms of carbon dioxide equivalent ($kg\text{ CO}_2\text{e/year}$) based on coefficients compiled from peer-reviewed databases (including IPCC AR6, US EPA, and UK BEIS/DEFRA 2023).

	### Reference Emission Factors

	\| Source Category \| Asset/Habit Type \| Carbon Coefficient \| Unit \|
	\| :-------------- \| :---------------- \| :----------------- \| :----------------------------------------------------------------- \|
	\| Transport \| Petrol Car \| `0.21` \| $kg\text{ CO}_2\text{ / km}$ \|
	\| \| Diesel Car \| `0.17` \| $kg\text{ CO}_2\text{ / km}$ \|
	\| \| Hybrid Car \| `0.105` \| $kg\text{ CO}_2\text{ / km}$ \|
	\| \| Electric Car \| `0.047` \| $kg\text{ CO}_2\text{ / km}$ \|
	\| \| Public Transport \| `0.089` \| $kg\text{ CO}_2\text{ / km}$ (Bus average) \|
	\| \| Train \| `0.041` \| $kg\text{ CO}_2\text{ / km}$ \|
	\| \| Short-Haul Flight \| `255.0` \| $kg\text{ CO}_2\text{ / return flight } (<3\text{ hrs})$ \|
	\| \| Long-Haul Flight \| `1620.0` \| $kg\text{ CO}_2\text{ / return flight } (>3\text{ hrs})$ \|
	\| Energy \| Grid Electricity \| `0.233` \| $kg\text{ CO}_2\text{ / kWh}$ (UK Grid 2023) \|
	\| Food & Diet \| Heavy Meat Diet \| `3300.0` \| $kg\text{ CO}_2\text{ / year}$ \|
	\| \| Mixed Diet \| `2500.0` \| $kg\text{ CO}_2\text{ / year}$ \|
	\| \| Vegetarian Diet \| `1700.0` \| $kg\text{ CO}_2\text{ / year}$ \|
	\| \| Vegan Diet \| `1500.0` \| $kg\text{ CO}_2\text{ / year}$ \|
	\| Shopping \| Clothing Item \| `33.0` \| $kg\text{ CO}_2\text{ / item}$ (Manufacturing + Transport) \|
	\| \| Electronic Device \| `300.0` \| $kg\text{ CO}_2\text{ / device}$ (Lifecycle manufacturing average) \|

	### Formula Systems

	- Transport Emissions:
	$$\text{Emissions}_{\text{transport}} = (\text{Daily Car Km} \times \text{Factor}_{\text{car}} \times 365) + (\text{Public Transport Km/Week} \times 52 \times 0.089) + (\text{Short Flights} \times 255) + (\text{Long Flights} \times 1620)$$
	- Home Energy Emissions (incorporating renewable energy tariff credits):
	$$\text{Emissions}_{\text{energy}} = \text{Monthly Electricity (kWh)} \times 12 \times 0.233 \times \left(1 - \frac{\text{Renewable \%}}{100}\right)$$
	- Shopping Emissions:
	$$\text{Emissions}_{\text{shopping}} = (\text{Clothing/Year} \times 33) + (\text{Electronics/Year} \times 300)$$

	---

	## Scoring & Benchmark Interpolation

	Sustainability scores range from 0 to 100 based on the total annualized carbon footprint. Instead of flat rating brackets, EcoTrack AI applies piecewise linear interpolation across five primary benchmark reference points:

	- Paris Agreement 2050 Target: $2,000\text{ kg CO}_2\text{e/year}$ (Score: 100)
	- Excellent Threshold: $3,000\text{ kg CO}_2\text{e/year}$ (Score: 90)
	- Good Threshold: $5,000\text{ kg CO}_2\text{e/year}$ (Score: 70)
	- Moderate Threshold: $7,500\text{ kg CO}_2\text{e/year}$ (Score: 50)
	- High/Poor Threshold: $12,000\text{ kg CO}_2\text{e/year}$ (Score: 0)

	### Score Interpolation Logic

	- If emissions $\le 2000$: Score is 100.
	- If $2000 < \text{emissions} \le 3000$:
	$$\text{Score} = 90 + \left(\frac{3000 - \text{emissions}}{3000 - 2000}\right) \times 10$$
	- If $3000 < \text{emissions} \le 5000$:
	$$\text{Score} = 70 + \left(\frac{5000 - \text{emissions}}{5000 - 3000}\right) \times 20$$
	- If $5000 < \text{emissions} \le 7500$:
	$$\text{Score} = 50 + \left(\frac{7500 - \text{emissions}}{7500 - 5000}\right) \times 20$$
	- If $7500 < \text{emissions} < 12000$:
	$$\text{Score} = \left(\frac{12000 - \text{emissions}}{12000 - 7500}\right) \times 50$$
	- If emissions $\ge 12000$: Score is 0.

	---

	## Gamification & Achievements System

	EcoTrack AI builds tracking habits by rewarding sustainable choices through a points, streaks, badges, and rank titles system.

	### Points Allocation

	- Assessment Submission: Base reward of $100\text{ points}$ per unique assessment log.
	- Streak Milestone Bonuses:
	- 3-Day Streak: Adds a $+50\text{ points}$ bonus.
	- 7-Day Streak: Adds a $+250\text{ points}$ bonus.

	### Ranks & Levels

	Based on total points accumulated, users level up through ranks:

	\| Points Required \| Rank Title \|
	\| :---------------- \| :---------------------------------- \|
	\| `0 - 999` \| Eco Novice (Baseline tier) \|
	\| `1,000 - 2,999` \| Green Sprout \|
	\| `3,000 - 5,999` \| Carbon Reducer \|
	\| `6,000 - 9,999` \| Nature Enthusiast \|
	\| `10,000 - 14,999` \| Ocean Guardian \|
	\| `15,000 - 24,999` \| Climate Champion \|
	\| `25,000+` \| Master Guardian (Ultimate tier) \|

	### Achievements & Badges

	Badges are analyzed during calculation routines and unlocked when meeting the following criteria:

	\| Badge Image/Title \| Criteria for Unlocking \|
	\| :---------------- \| :-------------------------------------------------------------------------------------------- \|
	\| Tree Planter \| User reports a `vegan` or `vegetarian` dietType. \|
	\| Carbon Ninja \| User drives `0 km` daily OR drives a `hybrid`/`electric` vehicle OR has `none` for fuel type. \|
	\| Zero Waste \| User buys less than `5` clothes per year AND `0` electronics items per year. \|

	---

	## Tech Stack

	\| Layer \| Technologies Used \|
	\| ------------ \| ------------------------------------------------------------------ \|
	\| Core \| HTML5, Vanilla CSS, Javascript (ES Modules) \|
	\| Frontend \| React 18, Vite 5, Tailwind CSS 3, Recharts, Axios, React Router v6 \|
	\| Backend \| Node.js 18+, Express 4, Helmet, Zod, Groq SDK, Firebase Admin SDK \|
	\| Database \| Firebase Firestore (Real-time Document Store) \|
	\| Testing \| Vitest, JSDOM, React Testing Library, Supertest \|

	---

	## Security Hardening Techniques

	EcoTrack AI implements a multi-layer defense-in-depth security model:

	- Strict Content Security Policy (CSP): Managed through Helmet.js middleware, restriction rules block execution of inline script payloads. Approved connect boundaries (`connectSrc`) are configured for local development and production Vercel apps.
	- Rate Limiting: Custom rate limits are established via `express-rate-limit`:
	- Default API Limit: `100 requests / 15 minutes` across the app.
	- User Registration (`/api/users`): Restricted to `15 registrations / hour` to prevent identity spoofing and sybil attacks.
	- Assessment Submissions (`/api/assessments`): Capped at `30 submissions / hour` to mitigate database flooding.
	- Input Sanitization: Built via custom XSS sanitizers (`sanitize.js`) in the backend route controllers. Any user text input (such as sustainability plan goals or coach chat messages) is parsed to strip out HTML tags and characters matching script patterns.
	- Zod Schema Parsing: Validates matching data types, structures, and bounds for all API requests. Unrecognized schema keys in requests are rejected immediately.
	- Safe Key Isolation: Firebase Service Account keys are read from `firebase-key.json` and are ignored in git commits by `.gitignore`.

	---

	## Folder Structure

	```
	carbon/
	├── backend/
	│ ├── src/
	│ │ ├── controllers/ # Express route controllers (User, Assessment, AI, etc.)
	│ │ ├── middleware/ # Rate limiters, error handling schemas
	│ │ ├── routes/ # API route definitions (ai.js, users.js, assessments.js, etc.)
	│ │ ├── services/ # Business logic (scoring, carbon math, Groq AI coach)
	│ │ ├── tests/ # Unit and integration test suites
	│ │ └── utils/ # firebaseClient, logger, sanitize helpers, migrateDb script
	│ ├── .env.example
	│ ├── firebase-key.json # Git-ignored Firebase credential file
	│ └── package.json
	├── frontend/
	│ ├── src/
	│ │ ├── components/ # Reusable UI widgets, charts, and layout components
	│ │ ├── hooks/ # Custom React hooks (useUser, useAssessment)
	│ │ ├── pages/ # Page components (Calculator, Dashboard, Coach, Leaderboard)
	│ │ ├── services/ # API axios instances
	│ │ ├── tests/ # Frontend component and integration tests
	│ │ └── utils/ # Debouncing, formatting, and cache handlers
	│ ├── .env.example
	│ └── package.json
	├── .gitignore
	├── package.json # Monorepo management
	└── README.md
	```

	---

	## Page Use Cases & Features

	### 1. Carbon Footprint Calculator

	- Use Case: Allows users to input daily habits across 4 distinct categories (Transport, Energy, Food, Shopping).
	- Details: Dynamic progress indicators, validation feedback, and instant emission calculations (annualized kg CO₂e).

	### 2. Interactive Dashboard

	- Use Case: Visual representation of the carbon footprint.
	- Details: Powered by Recharts. Renders category emission pie charts, progress over time, and comparative benchmark sliders (comparing user footprint to global and Paris Agreement targets).

	### 3. What-If Simulation Widget

	- Use Case: Lets users simulate changes in their habits (e.g. eating less meat, walking more, reducing electricity usage).
	- Details: Provides instant, dynamic reductions feedback showing how lifestyle changes impact their overall carbon footprint in real-time.

	### 4. AI Coach Chat & Planner

	- Use Case: Direct interactive messaging with the sustainability coach.
	- Details: Users get custom 30-day timelines, daily tips, and structured advice for lowering their footprints.

	### 5. Gamification & Leaderboards

	- Use Case: Encourages continuous tracking and eco-friendly competition.
	- Details: Shows user streaks, points earned for low footprints, ranks (e.g., "Eco Warrior"), and achievement badges (e.g., "Renewable Pioneer").

	---

	## Installation & Setup

	### Prerequisites

	- Node.js ≥ 18.0.0
	- npm ≥ 9
	- A Firebase Firestore project database (Free tier)

	### 1. Configure the Backend

	1. Navigate to `/backend` and create a `.env` file from the example:
	```bash
	cd backend
	cp .env.example .env
	```
	2. Populate the `.env` file:
	- Add your `GROQ_API_KEY` (obtained from [console.groq.com](https://console.groq.com)).
	3. Save your Firebase Service Account JSON credentials file as `firebase-key.json` in the `/backend` folder. _(Alternatively, stringify the JSON key and paste it as the `FIREBASE_SERVICE_ACCOUNT` value in your `.env`)_.

	### 2. Configure the Frontend

	1. Navigate to `/frontend` and create a `.env` file:
	```bash
	cd ../frontend
	cp .env.example .env
	```
	2. By default, it points to local development:
	```env
	VITE_API_URL=http://localhost:3001/api
	```

	### 3. Start the Development Servers

	In the root directory, install all dependencies:

	```bash
	# Root directory
	npm install
	```

	Start the backend API server:

	```bash
	# In backend/
	npm run dev
	```

	Start the React development server:

	```bash
	# In frontend/
	npm run dev
	```

	Open http://localhost:5173 to run the application locally.

	---

	## Deployment (Free Tier Hosting)

	The platform is designed to be hosted for free using a split server/client architecture:

	### 1. Backend: Hugging Face Spaces (Docker)

	The Node.js/Express backend runs in a free Hugging Face Space using Docker.

	- Hardware: CPU Basic (Free Tier - 2 vCPU · 16 GB).
	- Environment Variables & Secrets:
	- `PORT`: `7860` (assigned automatically by Hugging Face)
	- `GROQ_API_KEY`: Your Groq Cloud API key.
	- `CORS_ORIGIN`: Your deployed Vercel frontend URL (e.g., `https://eco-tracker-ii-123.vercel.app`).
	- `FIREBASE_SERVICE_ACCOUNT`: The stringified JSON content of your `firebase-key.json` file.
	- Dockerfile: Create this at the root directory:
	```dockerfile
	FROM node:18-alpine
	WORKDIR /app
	COPY package*.json ./
	COPY backend/package*.json ./backend/
	RUN npm install && npm install --prefix backend
	COPY backend/ ./backend/
	ENV NODE_ENV=production
	ENV PORT=7860
	EXPOSE 7860
	WORKDIR /app/backend
	CMD ["npm", "start"]
	```

	### 2. Frontend: Vercel (Static Web Hosting)

	The React/Vite client is hosted on Vercel (Live at: `https://eco-tracker-ii-123.vercel.app`).

	- Root Directory: `frontend`
	- Environment Variables:
	- `VITE_API_URL`: Your Hugging Face Space endpoint (e.g., `https://akash-dragon-ecotracker-ii.hf.space/api`).

	---

	## Testing and Verification

	To run tests across both the backend and frontend, run the following command in the root folder:

	```bash
	# From the project root folder
	npm test
	```

	### Coverage

	- Backend: Includes tests for emissions calculation formulas, rate limits, Zod schema validation, and Express routes.
	- Frontend: Includes tests for React hooks, cached calculations, custom debouncing utility, HTML sanitization, and the multi-step calculator workflow.

	# EcoTracker-II