EnergizeAI

EnergizeAI is a full-stack Next.js web app for Indian households to track electricity consumption, monitor appliance costs, and receive Gemini AI-powered savings recommendations. It supports Tamil Nadu slab-based billing, regional flat rates, budget alerts, and monthly reports.

---

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Auth: Firebase Authentication (email/password)
• Database: Cloud Firestore
• Admin SDK: firebase-admin (server-side API routes)
• AI: Google Gemini 1.5 Flash (@google/generative-ai)
• UI: Tailwind CSS, shadcn/ui, Radix UI, Recharts, Framer Motion
• Session: HTTP-only cookie set after Firebase login (edge middleware protection)
• Package Manager: pnpm

---

Project Structure

app/
  page.tsx                  # Landing page
  layout.tsx                # Root layout with AuthProvider + ThemeProvider
  dashboard/page.tsx        # Main dashboard (usage summary, charts, AI insights)
  readings/page.tsx         # Meter readings log
  appliance-tracker/page.tsx# Appliance management
  settings/page.tsx         # User settings (region, budget, rate)
  import/page.tsx           # CSV import for readings
  dashboard/import/page.tsx # CSV import for appliances
  login/page.tsx            # Login
  register/page.tsx         # Register
  forgot-password/page.tsx  # Password reset
  error.tsx                 # Global error boundary
  loading.tsx               # Global loading skeleton
  api/
    auth/session/route.ts   # POST/DELETE session cookie
    readings/route.ts       # GET + POST readings
    readings/[id]/route.ts  # DELETE reading
    appliances/route.ts     # GET + POST appliances
    appliances/[id]/route.ts# DELETE appliance
    settings/route.ts       # GET + PUT user settings
    insights/route.ts       # GET AI insights (Gemini)
    reports/route.ts        # POST monthly report (Gemini)

components/
  Navigation.tsx            # Top nav with auth state + theme toggle
  AddApplianceForm.tsx      # Add single appliance
  ApplianceImport.tsx       # CSV bulk import for appliances
  ApplianceCard.tsx         # Appliance display card
  ApplianceBreakdown.tsx    # Cost breakdown by appliance
  UsageChart.tsx            # Recharts usage graph
  UsageProgressBar.tsx      # Budget progress bar
  BudgetAlert.tsx           # Over/near budget alert
  CostDisplay.tsx           # Formatted cost display
  ai-insights.tsx           # AI insights card (client-side)
  prediction-card.tsx       # 7-day prediction card
  MonthlyReportGenerator.tsx# Monthly report UI
  OnboardingModal.tsx       # First-time setup modal
  SlabBreakdownDisplay.tsx  # Tamil Nadu slab cost breakdown
  SlabBreakdownModal.tsx    # Slab breakdown modal
  TamilNaduBillingInfo.tsx  # TN billing info banner
  TamilNaduSlabNotification.tsx # Slab tier notification

lib/
  firebase.ts               # Firebase client SDK init
  firebaseAdmin.ts          # Firebase Admin SDK + verifyIdToken()
  gemini.ts                 # Gemini 1.5 Flash client
  aiService.ts              # Local rule-based fallback analysis
  utils.ts                  # Core logic: dashboard summary, insights, reports
  constants.ts              # Rates, slab tables, billing helpers
  types.ts                  # Shared TypeScript interfaces
  schemas.ts                # Zod validation schemas
  validation.ts             # CSV row validation
  errorMessages.ts          # Friendly error message map
  analytics.ts              # Vercel Analytics helpers

context/
  AuthContext.tsx            # Firebase auth state + logout

middleware.ts               # Edge route protection via session cookie
firestore.rules             # Firestore security rules
firestore.indexes.json      # Composite indexes

---

Environment Variables

Create .env.local in the project root:

# Firebase Client SDK (public)
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=

# Firebase Admin SDK (server-side only — never expose to client)
FIREBASE_ADMIN_PROJECT_ID=
FIREBASE_ADMIN_CLIENT_EMAIL=
FIREBASE_ADMIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

# Gemini AI (server-side only)
GEMINI_API_KEY=

Get Firebase client keys from Firebase Console → Project Settings → General. Get Admin credentials from Firebase Console → Project Settings → Service Accounts → Generate new private key. Get Gemini key from aistudio.google.com/app/apikey.

---

Getting Started

pnpm install
pnpm run dev

Open http://localhost:3000.

---

Auth Flow

1. User registers/logs in via Firebase Auth (client-side)
2. Client gets Firebase ID token and POSTs it to /api/auth/session
3. Server sets an HTTP-only session cookie containing the raw ID token
4. middleware.ts checks for this cookie on every protected route at the edge
5. API routes verify the token server-side using verifyIdToken() from lib/firebaseAdmin.ts
6. On logout, client calls DELETE /api/auth/session to clear the cookie

Protected routes: /dashboard, /readings, /appliance-tracker, /settings, /import

---

Billing Logic

Tamil Nadu (Slab-based)

Uses official LT-1 Domestic Tariff slabs:

Units (kWh)	Rate (₹/unit)
0 – 100	Free
101 – 200	₹2.50
201 – 400	₹4.50
401 – 500	₹5.50
501 – 600	₹6.00
601 – 800	₹8.55
801 – 1000	₹9.65
1001+	₹11.80

Appliance costs are calculated proportionally based on each appliance's share of total monthly kWh.

Other Regions

Flat rate per kWh. Supported regions: Kerala, Karnataka, Maharashtra, Delhi, Gujarat, and 10+ more. Default: ₹8/kWh.

---

AI Insights (Gemini)

GET /api/insights fetches the user's readings, appliances, and settings from Firestore, then sends a structured prompt to Gemini 1.5 Flash. Returns 4 personalized, India-specific energy-saving recommendations. Falls back to rule-based analysis if Gemini is unavailable.

POST /api/reports generates a monthly report with 3 Gemini-generated recommendations based on actual cost and usage data.

---

Firestore Data Model

users/{userId}
  monthlyBudget: number
  electricityRate: number | null
  region: string
  onboardingComplete: boolean

readings/{readingId}
  userId: string
  date: string        # YYYY-MM-DD
  time: string        # HH:mm
  reading: number     # kWh meter value
  createdAt: Timestamp

appliances/{applianceId}
  userId: string
  name: string
  power: number       # watts
  hoursPerDay: number
  daysPerMonth: number
  monthlyKwh: number
  monthlyCost: number
  category: "essential" | "optional"
  createdAt: Timestamp

---

Deploying Firestore Rules & Indexes

firebase login
firebase deploy --only firestore:rules,firestore:indexes --project <your-project-id>

If firebase.json is missing, create it:

{ "firestore": { "rules": "firestore.rules", "indexes": "firestore.indexes.json" } }

---

Scripts

pnpm run dev      # Start dev server
pnpm run build    # Production build
pnpm run start    # Start production server
pnpm run lint     # Run ESLint