• Feature Highlights
• Overview
• Product Purpose
• Key Capabilities
• Features
• Technology Stack
• Installation
• Configuration
• Usage
• Project Structure
• Architecture
• API Reference
• Database Schema
• Components
• Real-Time Features
• Styling & Theming
• Testing
• Performance Optimizations
• Security Considerations
• Future Enhancements
• Troubleshooting
• Contributing
• License
• Team
• Acknowledgments
• Resources

• 🔍 Camera-Activated Appliance Scan - Point your camera at any model number label for instant recognition
• 🎤 Voice-Activated Energy Assistant - Natural, conversational AI powered by ElevenLabs
• 💰 Lifetime Cost & Carbon Intelligence - 10-year TCO calculations with location-based pricing
• 🎯 Smart Comparisons & Recommendations - AI-driven alternatives with savings projections
• 🌍 Location-Aware Analysis - Zip code-based utility rates and carbon intensity
• 💸 Rebate Discovery - Automatic detection of energy efficiency rebates
• 🎨 Modern Glassmorphism UI - Beautiful green/black AI-themed interface

AppliScan is an AI-powered web application that helps consumers make informed decisions when purchasing home appliances. By combining OCR technology, Energy Star API integration, location-based utility data, and natural language AI, AppliScan provides comprehensive energy cost analysis, carbon impact tracking, and personalized recommendations.

1. Instant Visual Recognition - No manual data entry required. Simply point your camera at the model number label.
2. AI Voice Assistant - Natural, human-like voice powered by ElevenLabs that explains costs, efficiency, and recommendations conversationally.
3. True Cost Transparency - See the real 10-year cost, not just the sticker price.
4. Location Intelligence - Calculations adapt to your local utility rates and grid carbon intensity.
5. Smart Recommendations - AI finds more efficient alternatives and calculates your potential savings.
6. Rebate Integration - Automatically surfaces available energy efficiency rebates in your area.

AppliScan solves the critical problem of hidden energy costs in appliance purchases. Most consumers only see the upfront price, but the true cost of ownership includes 10 years of electricity bills. AppliScan makes this transparent, helping users:

• Save Money - Understand true 10-year costs and find more efficient alternatives
• Reduce Carbon Footprint - See lifetime CO₂ emissions and make eco-friendly choices
• Maximize Rebates - Discover available energy efficiency incentives
• Make Informed Decisions - Compare products with comprehensive data and AI insights

• Real-time camera scanning with html5-qrcode
• OCR.space API integration for text recognition
• Tesseract.js fallback for offline capability
• Photo upload support for model number labels

• Direct API integration with Energy Star's Socrata database
• Automatic product matching by model number
• Comprehensive product specifications retrieval
• Energy efficiency ratings and certifications

• 10-year Total Cost of Ownership (TCO)
• Annual operating cost projections
• Location-based utility rate integration
• Rebate deduction calculations
• Break-even analysis for upgrades

• Lifetime CO₂ emissions tracking
• Regional carbon intensity data (EPA EGRID)
• Grid region classification
• Environmental impact comparisons

• ElevenLabs text-to-speech for natural voice
• Context-aware responses using ProductAnalysisContext
• Web Speech API fallback
• Voice preferences and welcome message controls
• Conversational product analysis

• Energy-efficient alternative discovery
• Savings calculations (annual and 10-year)
• Energy improvement percentage
• Product specification comparisons

• Zip code to state mapping
• 50 US states utility rate database
• Regional carbon intensity data
• State-specific rebate program lookup

• Real-time scanning with device camera
• OCR text recognition using OCR.space API (primary) and Tesseract.js (fallback)
• Model number extraction from product labels
• Photo upload alternative for scanning
• Instant product lookup via Energy Star API

• Global Voice Agent - Persistent floating assistant available on all pages
• ElevenLabs Integration - Natural, human-like British male voice
• Context-Aware Responses - Understands product analysis context
• Conversational Interface - Ask questions, get voice responses
• Welcome Messages - Configurable voice greetings
• Voice Preferences - Toggle voice welcomes on/off

• 10-Year TCO Calculation

  10-Year TCO = (Upfront Price - Rebates) + (Annual kWh × Electricity Rate × 10)
  

• Annual Operating Cost - Yearly electricity expenses
• Lifetime CO₂ Emissions - Total carbon footprint in tons
• Energy Efficiency Levels - Categorization (Very Low, Low, Medium, High)
• Payback Timeline - ROI analysis for upgrades

• Top 3 Alternatives - Most energy-efficient options
• Energy Improvement % - Efficiency gains over current product
• 10-Year Savings - Projected cost savings
• Product Specifications - CEF, capacity, dimensions comparison
• Side-by-Side Analysis - Easy visual comparison

• Zip Code Input - Enter your location for accurate rates
• State-Level Data - 50 US states covered
• Utility Rate Database - EIA & FERC form data
• Carbon Intensity - EPA EGRID regional data
• Rebate Discovery - State-specific energy efficiency programs

• Glassmorphism Design - Translucent cards with backdrop blur
• Green/Black AI Theme - Modern, tech-forward aesthetic
• Responsive Layout - Mobile-first design
• Smooth Animations - Enhanced user experience
• Accessibility - Voice-first interface, keyboard navigation

• Next.js 14 - React framework with App Router
• React 18 - UI library with hooks and context
• TypeScript 5.0 - Type-safe development
• Tailwind CSS 3.3 - Utility-first styling
• html5-qrcode - Barcode/QR code scanning
• Tesseract.js - Client-side OCR fallback

• Next.js API Routes - Serverless functions
• Energy Star API - Socrata database integration
• OCR.space API - Cloud-based OCR service
• ElevenLabs API - Text-to-speech synthesis
• Web Speech API - Browser-native speech recognition

• Energy Star Database - Product specifications and efficiency data
• EIA & FERC - Utility rate data (residential electricity rates)
• EPA EGRID - Carbon intensity data (regional grid emissions)
• State Rebate Programs - Energy efficiency incentive data

• Vercel - Deployment and hosting
• Git - Version control
• npm - Package management
• TypeScript - Type checking
• ESLint - Code linting

• Node.js 18+ and npm
• Git
• Modern web browser (Chrome, Safari, Firefox, Edge)

git clone https://github.com/gudlaa/ClearCost.git
cd ClearCost

npm install

Create a .env.local file in the root directory:

# OCR API Key (get free key at https://ocr.space/ocrapi/freekey)
OCR_SPACE_API_KEY=your_ocr_space_api_key

# ElevenLabs API Key (get at https://elevenlabs.io)
ELEVENLABS_API_KEY=your_elevenlabs_api_key

# Optional: Custom ElevenLabs Voice ID
ELEVENLABS_VOICE_ID=onwK4e9ZLuTAKqWW03F9  # Daniel (British male)

npm run dev

Visit http://localhost:3000 to see the app.

The project includes vercel.json with optimized settings:

• Build command: npm run build
• Framework: Next.js
• Region: iad1 (US East)
• API route headers for CORS

1. Go to Vercel Dashboard → Your Project → Settings → Environment Variables
2. Add:
   • OCR_SPACE_API_KEY (Production, Preview, Development)
   • ELEVENLABS_API_KEY (Production, Preview, Development)
3. Redeploy after adding variables

See VERCEL_DEPLOYMENT.md for detailed instructions.

Users can toggle voice welcomes via the Voice Agent UI. Preferences are stored in localStorage:

• Key: voiceWelcomeEnabled
• Default: true

1. Launch App - Visit the home page, hear "Welcome to AppliScan"
2. Start Scanning - Click "Start Scanning" button
3. Scan Product - Point camera at model number label or upload photo
4. View Results - See product info, energy use, and efficiency rating
5. Enter Location - Provide zip code for location-based rates
6. Review Analysis - See 10-year cost, carbon impact, and recommendations
7. Interact with Voice - Ask questions or request voice summary

• "What is the 10-year cost?"
• "Tell me about the carbon impact"
• "What are the recommendations?"
• "Change location to [zip code]"
• "Read the results"

1. User scans dryer model DVE52M77
2. App displays: Samsung dryer, 607 kWh/year, average efficiency
3. User enters zip code 10001 (New York)
4. System calculates:
   • Utility rate: $0.1990/kWh
   • 10-Year Cost: $1,594
   • Annual Operating: $119.40
   • Carbon: 6 tons CO₂
5. App recommends 3 more efficient alternatives with savings
6. User clicks Voice Agent, asks "What are my savings?"
7. Voice responds with natural, conversational explanation

ClearCost/
├── app/                          # Next.js App Router
│   ├── api/                      # API routes
│   │   ├── calculate-tco/        # TCO calculation endpoint
│   │   ├── utility-rates/        # Location-based rates
│   │   ├── rebates/              # Rebate lookup
│   │   ├── recommend/            # Product recommendations
│   │   ├── ocr-space/            # OCR.space proxy
│   │   ├── elevenlabs/           # ElevenLabs TTS proxy
│   │   └── lookup-upc/            # UPC lookup
│   ├── page.tsx                  # Home page
│   ├── scan/                     # Scanner page
│   ├── results/                  # Results page
│   ├── compare/                  # Comparison page
│   ├── layout.tsx                # Root layout
│   └── globals.css               # Global styles
├── components/                   # React components
│   ├── barcode-scanner/          # Scanner components
│   ├── voice-assistant/          # Voice AI components
│   ├── navigation/               # TopNav component
│   ├── recommendations/          # Product recommendations
│   └── energy-label/             # Energy label display
├── lib/                          # Utility libraries
│   ├── calculations/             # Energy calculations
│   ├── utils/                    # Helper functions
│   │   ├── voiceAssistant.ts     # Voice synthesis
│   │   ├── elevenlabsVoice.ts    # ElevenLabs integration
│   │   └── voicePreferences.ts   # User preferences
│   └── api-clients/              # API clients
│       ├── energyStar.ts         # Energy Star API
│       └── upcitemdb.ts          # UPC database
├── contexts/                     # React contexts
│   └── ProductAnalysisContext.tsx # Global product state
├── backend/                      # Backend data
│   ├── data/                     # Static data files
│   │   ├── utility_rates.json    # Utility rates by state
│   │   ├── carbon_intensity.json # Carbon data by state
│   │   └── rebates.json          # Rebate programs
│   └── api/                      # FastAPI routes (legacy)
├── public/                       # Static assets
│   └── whiteLogo.png             # AppliScan logo
├── vercel.json                   # Vercel configuration
├── next.config.js                # Next.js configuration
├── tailwind.config.js            # Tailwind configuration
└── package.json                  # Dependencies

┌─────────────────────────────────────────┐
│         Next.js App Router              │
│  ┌──────────┐  ┌──────────┐           │
│  │  Pages   │  │  Layout  │           │
│  └──────────┘  └──────────┘           │
│       │              │                 │
│  ┌──────────────────────────┐         │
│  │   React Components       │         │
│  │  - Scanner               │         │
│  │  - Voice Agent          │         │
│  │  - Results Display      │         │
│  └──────────────────────────┘         │
│       │                                │
│  ┌──────────────────────────┐         │
│  │   Context Providers      │         │
│  │  - ProductAnalysisContext │         │
│  └──────────────────────────┘         │
└─────────────────────────────────────────┘

User Action (Scan/Upload)
    ↓
OCR Processing (OCR.space → Tesseract fallback)
    ↓
Model Number Extraction
    ↓
Energy Star API Query
    ↓
Product Data Retrieved
    ↓
User Enters Zip Code
    ↓
Utility Rates API + Carbon Data
    ↓
TCO Calculation + Recommendations
    ↓
Results Display + Voice Context Update
    ↓
User Interacts with Voice Agent
    ↓
Context-Aware Voice Response

Client (Browser)
    ↓
Next.js API Routes (/api/*)
    ↓
External APIs:
  - Energy Star (Socrata)
  - OCR.space
  - ElevenLabs
    ↓
Data Processing
    ↓
Response to Client

Endpoint: POST /api/calculate-tco

Request Body:

{
  "product": {
    "model_number": "DVE52M77",
    "estimated_annual_energy_use_kwh_yr": 607,
    "brand_name": "Samsung"
  },
  "upfrontPrice": 800,
  "rebates": 0,
  "utilityRate": 0.1990,
  "carbonIntensity": 0.20
}

Response:

{
  "costs": {
    "tenYearTotalCost": 1594.00,
    "annualOperatingCost": 119.40
  },
  "energy": {
    "energyUseLevel": {
      "level": "medium",
      "description": "Average efficiency"
    }
  },
  "carbon": {
    "tenYear_emissions_tons": 6.07
  }
}

Endpoint: GET /api/utility-rates?zipCode=10001

Response:

{
  "state": "NY",
  "stateName": "New York",
  "gridRegion": "Northeast",
  "utilityRate": 0.1990,
  "carbonIntensity": 0.20,
  "rateUnit": "$/kWh",
  "carbonUnit": "lbs CO2/kWh"
}

Endpoint: GET /api/rebates?zipCode=10001&productType=dryer

Response:

{
  "state": "NY",
  "stateName": "New York",
  "productType": "dryer",
  "programs": [
    {
      "name": "New York ENERGY STAR Program",
      "appliances": ["dryer", "washer"],
      "rebateAmount": 125,
      "url": "https://www.dec.ny.gov"
    }
  ],
  "totalPrograms": 1
}

Endpoint: GET /api/recommend?model=DVE52M77&productType=dryer&maxResults=3

Response:

{
  "recommendations": [
    {
      "brand_name": "Samsung",
      "model_name": "DVE45T6000W",
      "model_number": "DVE45T6000W",
      "estimated_annual_energy_use_kwh_yr": 520,
      "energyImprovement": "14% more efficient",
      "combined_energy_factor_cef": "4.2"
    }
  ]
}

Endpoint: POST /api/ocr-space

Request Body:

{
  "imageBase64": "data:image/jpeg;base64,..."
}

Response:

{
  "success": true,
  "fullText": "MODEL DVE52M77...",
  "words": [
    {
      "text": "DVE52M77",
      "confidence": 95.5,
      "left": 100,
      "top": 50
    }
  ]
}

Endpoint: POST /api/elevenlabs/tts

Request Body:

{
  "text": "Welcome to AppliScan",
  "voice_id": "onwK4e9ZLuTAKqWW03F9",
  "voice_settings": {
    "stability": 0.3,
    "similarity_boost": 0.75,
    "style": 0.7
  }
}

Response: Audio stream (MPEG)

AppliScan uses static JSON files for data storage (no database):

{
  "NY": {
    "stateName": "New York",
    "gridRegion": "Northeast",
    "residentialRate": 0.1990,
    "commercialRate": 0.1650
  }
}

{
  "NY": {
    "stateName": "New York",
    "carbonIntensity": 0.20,
    "gridRegion": "Northeast"
  }
}

{
  "NY": {
    "stateName": "New York",
    "programs": [
      {
        "name": "New York ENERGY STAR Program",
        "appliances": ["dryer", "washer"],
        "rebateAmount": 125,
        "url": "https://www.dec.ny.gov"
      }
    ]
  }
}

Note: Product data is fetched dynamically from Energy Star API.

• Location: components/barcode-scanner/ModelNumberScanner.tsx
• Purpose: OCR-based model number scanning
• Features:
  • Camera integration
  • Photo upload
  • OCR.space API integration
  • Tesseract.js fallback
  • Model number extraction

• Location: components/voice-assistant/GlobalVoiceAI.tsx
• Purpose: Persistent voice assistant
• Features:
  • Floating bubble UI
  • Speech recognition
  • ElevenLabs TTS
  • Context-aware responses
  • Voice preferences toggle

• Location: components/navigation/TopNav.tsx
• Purpose: Top navigation bar
• Features:
  • AppliScan branding
  • Status indicator
  • Glassmorphism styling

• Location: contexts/ProductAnalysisContext.tsx
• Purpose: Global state management
• State:
  • productData - Current product info
  • tcoData - Cost calculations
  • recommendations - Alternative products
  • locationDisplay - User location
  • utilityRate - Current rate

• Web Speech API - Browser-native speech recognition
• Real-time transcription - Continuous listening mode
• Command processing - Natural language understanding
• Context-aware responses - Uses ProductAnalysisContext

• ElevenLabs API - High-quality text-to-speech
• Web Speech API fallback - Browser-native synthesis
• Voice preferences - User-controlled welcome messages
• Streaming audio - Real-time playback

• Camera stream - Real-time video feed
• Frame capture - Continuous OCR processing
• Instant feedback - Immediate model number detection

• Theme: Green/Black AI aesthetic
• Style: Glassmorphism with translucent overlays
• Colors:
  • Primary: #22c55e (green-500)
  • Background: #000000 (black)
  • Text: #d1d5db (gray-300)
  • Accent: #10b981 (emerald-500)

.glass-card        /* Translucent card with blur */
.glass-overlay     /* Semi-transparent overlay */
.glass-nav         /* Navigation bar styling */
.ai-text-glow      /* Green text glow effect */
.gradient-border    /* Animated gradient border */

• Custom color palette
• Extended spacing scale
• Custom animation utilities
• Responsive breakpoints

See TESTING_GUIDE.md for comprehensive testing instructions.

1. Scanner Page

   • Camera access and permissions
   • Photo upload functionality
   • OCR accuracy with various label types
   • Model number extraction

2. Results Page

   • TCO calculation accuracy
   • Location-based rate lookup
   • Recommendations display
   • Voice interaction

3. Voice Agent

   • Welcome message playback
   • Speech recognition
   • Context-aware responses
   • Voice preferences persistence

# Test TCO calculation
curl -X POST http://localhost:3000/api/calculate-tco \
  -H "Content-Type: application/json" \
  -d '{"product": {...}, "upfrontPrice": 800, ...}'

# Test utility rates
curl http://localhost:3000/api/utility-rates?zipCode=10001

• Code Splitting - Next.js automatic code splitting
• Image Optimization - Next.js Image component
• Lazy Loading - Dynamic imports for heavy components
• Memoization - React.memo for expensive renders
• Suspense Boundaries - Async component loading

• Caching - Static data cached in memory
• Rate Limiting - Protection against abuse
• Error Handling - Graceful fallbacks
• Response Compression - Gzip compression

• Audio Streaming - Chunked audio delivery
• Fallback Mechanisms - Web Speech API backup
• Preference Caching - localStorage for settings

• Server-Side Only - API keys never exposed to client
• Environment Variables - Secure storage in .env.local
• Vercel Secrets - Encrypted environment variables

• No User Data Storage - No personal information collected
• Client-Side Processing - OCR can run locally (Tesseract)
• HTTPS Only - Secure connections enforced

• Zip Code Validation - 5-digit numeric only
• Model Number Sanitization - Alphanumeric filtering
• Image Size Limits - Prevent abuse

• Multi-Product Comparison - Side-by-side comparison tool
• Wishlist - Save products for later
• Price Tracking - Historical price data
• Smart Home Integration - Connect with smart appliances
• Time-of-Use Rates - TOU rate calculations
• Rebate Application - Direct rebate submission
• Mobile App - Native iOS/Android apps
• Social Sharing - Share product analyses
• Export Reports - PDF/CSV export
• Multi-Language Support - Internationalization

• Database Migration - Move from JSON to PostgreSQL
• Caching Layer - Redis for API responses
• Analytics - User behavior tracking
• A/B Testing - Feature experimentation
• Progressive Web App - PWA capabilities

• Check API Key - Verify ELEVENLABS_API_KEY is set
• Browser Permissions - Allow microphone access
• Fallback Mode - Web Speech API should work without API key
• Console Errors - Check browser console for errors

• Image Quality - Ensure clear, well-lit photos
• API Key - Verify OCR_SPACE_API_KEY is set
• Fallback - Tesseract.js should work offline
• Model Number Format - Check if format matches expected pattern

• TypeScript Errors - Run npm run build to see details
• Missing Dependencies - Run npm install
• Environment Variables - Check .env.local exists

• Environment Variables - Must be set in Vercel dashboard
• Build Logs - Check Vercel deployment logs
• API Routes - Ensure export const dynamic = 'force-dynamic' for dynamic routes

1. Check VERCEL_DEPLOYMENT.md for deployment issues
2. Review TESTING_GUIDE.md for testing scenarios
3. Check browser console for errors
4. Verify environment variables are set correctly

We welcome contributions! Here's how to get started:

1. Fork the Repository
2. Create a Feature Branch

   git checkout -b feature/your-feature-name

3. Make Your Changes
4. Test Thoroughly
5. Commit Your Changes

   git commit -m "Add: your feature description"

6. Push to Your Fork

   git push origin feature/your-feature-name

7. Create a Pull Request

• Follow TypeScript best practices
• Use Tailwind CSS for styling
• Write descriptive commit messages
• Test on multiple browsers
• Update documentation as needed

This project is licensed under the MIT License - see the LICENSE file for details.

• Ritya Godala - Project Lead & Developer
• Contributors - [Add your name here]

• Energy Star - Product database and efficiency ratings
• OCR.space - OCR API service
• ElevenLabs - Natural text-to-speech
• EIA & FERC - Utility rate data
• EPA EGRID - Carbon intensity data
• Next.js Team - Amazing framework
• Vercel - Deployment platform

• Next.js Documentation
• React Documentation
• Tailwind CSS
• Energy Star API
• OCR.space API
• ElevenLabs API

• VERCEL_DEPLOYMENT.md - Deployment guide
• TESTING_GUIDE.md - Testing instructions
• FEATURES.md - Feature documentation
• VOICE_AI_DOCUMENTATION.md - Voice AI details

• Live Demo
• GitHub Repository
• Energy Star Database
• Get OCR API Key
• Get ElevenLabs API Key