CarbonTrace

This is a submission for Weekend Challenge: Earth Day Edition

"my inbox already knows everything I do, so I built an agent to read it"

Project Overview

CarbonTrace is an AI-powered web application that automatically tracks a user's personal carbon footprint by scanning their Gmail inbox. Instead of asking users to manually log activities, the app connects to Gmail via OAuth, reads receipts and booking confirmations, and uses Google Gemini to classify each activity and estimate its CO₂ emissions. The result is a personalised carbon dashboard with actionable nudges.

What is a carbon footprint?

Every action you take that consumes energy or resources releases greenhouse gases into the atmosphere. Driving to work, ordering food, buying a new phone, flying to another city. All of these activities burn fuel or require manufacturing processes that emit gases, primarily carbon dioxide (CO₂) and methane (CH₄).
A carbon footprint is the total sum of all those emissions. That is everything you personally released into the atmosphere over a period of time, measured in kilograms or tonnes of CO₂ equivalent (CO₂e).
The "equivalent" part matters because methane is far more potent than CO₂, so scientists convert all greenhouse gases into a single CO₂ unit for comparison.

How it connects to CarbonTrace

1. The Metric Concept The definition says carbon footprints measure the impact of individuals on climate change. That is exactly the problem CarbonTrace solves at the personal level. For every activity, the energy is usually generated by burning fossil fuels, which releases Carbon Dioxide into the atmosphere. The "KG CO₂" number is an estimation of exactly how heavy those invisible greenhouse gas emissions are for that specific receipt.

For example, a 15-mile Uber ride might produce roughly 5.2 kg CO₂.
A domestic flight from NY to LA might produce 400.5 kg CO₂.

1. How CarbonTrace App Calculates It (The AI Magic) Instead of forcing users to navigate complex scientific emission tables, your backend relies entirely on Google Gemini 2.5 Flash. When your API pulls the receipt text from a user's Gmail, it sends it to Gemini with this internal prompt.

CarbonTrace simply takes the abstract definition: "total greenhouse gases from human activities", and makes it concrete and personal.

The average Nigerian emits roughly 0.5 tonnes of CO₂ per year. The global average is 4.7 tonnes. A single Lagos–London flight emits approximately 0.5 tonnes per passenger, wiping out an entire year of average Nigerian emissions in one trip.
Most people have no idea their flight just did that. CarbonTrace makes that invisible number visible.

Because you cannot reduce what you cannot measure

Demo

Live App:

How it Works:

• Visit the live URL
• Click "Get started with Google"
• Sign in and grant Gmail read access
• Click "Scan my emails"
• Watch your carbon footprint appear in seconds

Demo Video: (embed your Loom link here)
In the video I walk through the full user journey — from signing in with Google, through the Auth0 consent screen, to the dashboard populating with real CO₂ data classified by Gemini. The entire flow from login to result takes under 30 seconds.

Code

Github link:
The repository is fully public. Here is a quick map of the most important files:

src/
  app/
    page.tsx              → Landing page with login button
    dashboard/
      page.tsx            → Server component, pre-fetches Supabase data
      DashboardClient.tsx → Client component, handles scan button and live results
    api/
      scan/
        route.ts          → Core agent: Gmail fetch, Gemini parse,
Supabase save
  lib/
    auth0.ts              → Auth0 client initialisation
    supabase.ts           → Supabase client initialisation
middleware.ts             → Auth0 v4 middleware, mounts /auth/*routes automatically

The most interesting file is src/app/api/scan/route.ts — that is where the entire agent loop lives. Everything else is just plumbing to support it.

How I Built It

I built CarbonTrace in 48 hours for the Earth Day 2026 hackathon. Here is the technical story.

The stack
The app is built on Next.js 15 App Router with TypeScript and Tailwind CSS. I used pnpm as the package manager and deployed to Vercel. The entire project: frontend, backend API routes, and middleware, all in a single Next.js repository.

Auth0 for Agent: The hardest part
The most technically interesting decision was using Auth0 for Agents to handle the Gmail OAuth consent flow. This is not regular login. it is agentic authentication, where the user grants the app permission to act on their behalf and read their Gmail even when they are not actively present.
Auth0 v4 completely changed the SDK architecture from v3. Routes are no longer manually registered. The middleware mounts /auth/login, /auth/logout, and /auth/callback automatically. The Auth0Client is initialised once in src/lib/auth0.ts and shared across all server components and API routes:

import { Auth0Client } from '@auth0/nextjs-auth0/server';
export const auth0 = new Auth0Client();

This single line handles the entire session lifecycle, which includes token storage, rotation, and expiry, without any additional configuration.

Google Gemini: the brain
The intelligence layer is a single POST route at /api/scan. Instead of asking Gemini to return free-form text and parsing it with regex, I used Gemini's structured output feature with a responseSchema. This forces Gemini to return exactly the JSON shape I need, every time, with zero parsing failures:

const model = genAI.getGenerativeModel({
  model: 'gemini-2.5-flash',
  generationConfig: {
    responseMimeType: 'application/json',
    responseSchema: scanSchema,
  },
});

Gemini reads each email and classifies it into one of three categories: Travel, Food, or Shopping. It estimates the CO₂ in kilograms using its knowledge of emissions factors. It also generates a personalised nudge based on the user's biggest emission source. The whole thing runs in under 3 seconds.

Supabase: persistence
Every activity Gemini detects gets saved as an individual row in a carbon_logs table in Supabase Postgres. Row Level Security is enabled so users can only ever query their own data, even if there is a bug in the API, one user can never see another user's logs.
When you open the dashboard, the server component pre-fetches your existing logs from Supabase and passes them as initialData to the client component. This means the dashboard loads with your historical data immediately, no scan required on every visit.

The biggest challenge

Auth0 v4 was a significant hurdle. The SDK is a complete rewrite from v3: the UserProvider, handleAuth, and /api/auth/[auth0] patterns that every tutorial on the internet uses are all gone. I spent roughly 2 hours debugging import errors before finding the v4 migration guide and understanding that middleware now handles everything automatically.

The lesson:

always check the major version before installing a package.

What I would build next

• Bank transaction scanning via Open Banking APIs for a more complete footprint picture
• Team and company accounts so organisations can track collective emissions
• Integration with verified offset registries like Gold Standard and Verra so users can take direct action from the dashboard

Prize Categories

I am submitting to these categories:

• Best Use of Auth0 for Agents
• Best Use of Google Gemini

I would love to get a feedback, if you happen to actually read to the end of this blog.Thanks for participating!