CarbonLedger AI

Turn business spending into climate action.

Comment

📝 CarbonLedger AI – Project Story

🚀 What Inspired Me

Growing up in a family that ran a small manufacturing business, I watched my parents struggle with two things: tight margins and growing pressure to "go green."

Every quarter, a big corporate client would ask for our carbon footprint data. My father, an engineer who could calculate production costs in his sleep, would spend entire weekends manually adding up electricity bills, fuel receipts, and shipping invoices. He'd mutter the same thing every time:

"I want to help the planet. But I run a business, not a climate lab."

That stuck with me.

When I learned that 30+ million SMEs globally face the same problem – and that existing carbon accounting tools cost $10,000+ annually – I realized this wasn't just a family frustration. It was a market failure.

Nexforge's theme of "innovation that creates measurable value" clicked immediately. What if we could turn the paperwork SMEs already generate into instant climate intelligence? What if we could democratize carbon accounting like TurboTax democratized tax filing?

That's why I built CarbonLedger AI.

📚 What I Learned

Technical Lessons

Concept What I Learned
API Integration Connecting Next.js frontend to FastAPI backend requires careful CORS configuration and environment variable management
Emission Factors Different databases (EPA vs Defra) give different CO₂ values – I learned to standardize on EPA 2024 for consistency
File Parsing Parsing unstructured PDF invoices is harder than CSV. For MVP, I prioritized CSV + mocked PDF parsing with OpenAI
Deployment Netlify is great for static Next.js, but backend needs separate hosting (Render/Railway)

Domain Lessons

Carbon Accounting Math:

The core calculation is surprisingly simple:

$$CO_2 = \sum_{i=1}^{n} (Activity_i \times EmissionFactor_i)$$

Where:

  • $Activity_i$ = amount of fuel/electricity/miles traveled
  • $EmissionFactor_i$ = CO₂ emitted per unit (kg CO₂/kWh, kg CO₂/gallon, etc.)

But the challenge isn't the math – it's getting the activity data. Most SMEs don't track these numbers. CarbonLedger AI solves this by extracting activity from financial data.

Example: A $500 electricity bill × average local rate ($0.12/kWh) = 4,167 kWh × 0.233 kg CO₂/kWh = 971 kg CO₂

$$CO_2 = \frac{500}{0.12} \times 0.233 = 971 \text{ kg}$$

No manual entry required.

Human Lessons

  1. Start with a real problem – My parents' frustration wasn't unique; it validated the market
  2. Build for one user first – I focused on a single SME owner persona before generalizing
  3. Perfection is the enemy of done – My first version crashed constantly. v2 worked. v3 shipped.

🛠️ How I Built CarbonLedger AI

Architecture Overview

User Browser (Netlify)
    ↓
Next.js Frontend (React + Tailwind)
    ↓ API Call (REST)
FastAPI Backend (Python)
    ↓
├── OpenAI API (Invoice Parsing)
├── Emission Factor DB (EPA/Defra)
├── Calculation Engine
└── PostgreSQL (Supabase)

Tech Stack Decisions

Component Choice Why
Frontend Next.js + Tailwind Fast development, beautiful UI out-of-the-box, easy Netlify deploy
Backend FastAPI Python ecosystem for AI, automatic API docs, async support
AI Parsing OpenAI API Handles messy invoice formats without training custom models
Database Supabase Free tier, PostgreSQL, built-in auth for future
Deployment Netlify (frontend) + Render (backend) Simple, free, good for hackathon

Key Features Built in 48 Hours

# Core calculation engine (simplified)
def calculate_carbon(category: str, amount: float) -> float:
    factors = {
        "electricity": 0.233,  # kg CO₂ per kWh
        "gasoline": 8.89,      # kg CO₂ per gallon
        "air_travel": 0.22,    # kg CO₂ per mile
        "shipping": 0.161,     # kg CO₂ per ton-mile
    }
    return amount * factors.get(category, 0)

Step-by-Step Build Process

Hours Task Status
0-6 Setup: GitHub, Next.js, Tailwind, basic UI ✅
6-12 FastAPI backend, emission factor database, /calculate endpoint ✅
12-18 File upload component, drag-and-drop, CSV parsing ✅
18-24 Connect frontend → backend, display results dashboard ✅
24-30 Add AI recommendations engine, PDF report generation ✅
30-36 Polish UI, add loading states, error handling ✅
36-42 Deploy to Netlify + Render, configure CORS ✅
42-48 Record demo video, write documentation, submit ✅

⚠️ Challenges I Faced & How I Solved Them

Challenge 1: CORS Errors When Connecting Frontend to Backend

The Problem:
My Next.js frontend on Netlify couldn't talk to my FastAPI backend on Render. Browser console showed:

Access to fetch at 'https://my-backend.onrender.com/calculate' from origin 
'https://carbonledger-ai.netlify.app' has been blocked by CORS policy

The Solution:
I configured CORS properly in FastAPI:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://carbonledger-ai.netlify.app"],
    allow_methods=["*"],
    allow_headers=["*"],
)

Lesson Learned: Always set CORS early in development, not as an afterthought.

Challenge 2: OpenAI API Rate Limits During Peak Testing

The Problem:
During heavy testing, OpenAI returned 429 Too Many Requests errors. My hackathon budget couldn't absorb premium tier.

The Solution:
I implemented:

  1. Caching – Same invoice → same result, no second API call
  2. Fallback parser – Simple regex for CSV files (free)
  3. Mock mode – For demo video, I pre-generated results
# Cached parsing
from functools import lru_cache

@lru_cache(maxsize=100)
def parse_invoice(invoice_hash: str) -> dict:
    # OpenAI call here
    pass

Lesson Learned: Always build fallbacks for third-party APIs.

Challenge 3: Inconsistent Emission Factors Across Sources

The Problem:
EPA says electricity is 0.233 kg CO₂/kWh. Defra says 0.212. Our Lady of Perpetual Carbon says something else. Which is right?

The Solution:
I standardized on EPA 2024 for US businesses, documented the source, and made factors configurable:

EMISSION_SOURCES = {
    "EPA_2024": {"electricity": 0.233, "gasoline": 8.89},
    "DEFRA_2024": {"electricity": 0.212, "gasoline": 8.78},
}
# Default: EPA_2024

Lesson Learned: Transparency > "perfect" data. Judges care that you know the issue exists.

Challenge 4: Deployment Pipeline Broke 2 Hours Before Submission

The Problem:
Netlify build failed because I forgot to add NEXT_PUBLIC_API_URL to environment variables. npm run build errored with API_URL is not defined.

The Solution:
Breathing exercises first. Then:

# Fixed in 5 minutes
netlify env:set NEXT_PUBLIC_API_URL https://my-backend.onrender.com
netlify deploy --prod

Lesson Learned: Test your production build locally BEFORE deploying.

Challenge 5: Making Complex Carbon Data Understandable

The Problem:
"1,245 kg CO₂" means nothing to most SME owners. Is that good? Bad? Should I panic?

The Solution:
I added contextual comparisons:

Your carbon footprint = 1,245 kg CO₂
Equivalent to driving 3,100 miles in an average car
or powering 1.5 homes for a month

This turned abstract numbers into intuitive understanding.

Lesson Learned: Technical accuracy without human context is useless.

🎉 What I'm Proud Of

  1. Complete working prototype in 48 hours – from idea to deployed product
  2. Beautiful, intuitive UI – Judges can use it without instructions
  3. Real problem, real solution – Not just another AI wrapper
  4. Documentation – Clean code, README, demo video

🔮 What's Next for CarbonLedger AI

Feature Timeline
QuickBooks/Xero API integration 2 weeks
Real-time supply chain tracking 1 month
Mobile app (React Native) 2 months
Pilot with 10 local SMEs 3 months
Launch on QuickBooks App Store 6 months

🙏 Thank You

To Nexforge – for creating a platform that rewards strategic innovation, not just rapid hacks.
To my parents – for showing me the real problem.
To the judges – for considering a solution that turns business spending into climate action.

CarbonLedger AI: Turn spending into climate action.

Share this project:

Updates