PowerWise

A full-stack electricity bill reduction assistant for Sri Lankan households.

PowerWise helps families record electricity use, estimate bills before they arrive, manage a monthly budget, understand what each appliance is really costing them, and act on practical saving tips — all from one household-focused dashboard.

Live Demo · Report an Issue · Architecture · Deployment Guide

This is an academic and portfolio project. It is deployed and functional, but its configured tariff data must be checked against current official utility rates before any real-world use.

---

Table of Contents

• Problem Statement
• Target Users
• Key Features
• Tech Stack
• Architecture Overview
• Repository Structure
• Getting Started
• Environment Variables
• Testing
• Deployment
• Security Notes
• Known Limitations
• Future Improvements
• Documentation
• Authors

Problem Statement

Electricity bills can be difficult to predict, especially when households have limited access to clear usage data. PowerWise brings meter readings, appliance estimates, budget tracking, alerts, and saving guidance into one household-focused application, so families can see a bill coming before it arrives instead of being surprised by it.

Target Users

• Sri Lankan households monitoring monthly electricity costs
• Families working within a limited electricity budget
• People who enter meter readings manually
• Non-technical users who need clear, practical guidance
• Administrators who maintain tariff and saving-tip records

Key Features

• 🔐 JWT-based user authentication and role-protected administration
• 🏠 Household profile, owner, and member management
• 📈 Manual meter-reading history and consumption comparisons
• 🔌 Appliance tracking with common household presets
• 💵 Configurable block tariffs and itemized bill estimates
• 📊 Monthly budget plans, billing-cycle progress, and budget-risk messages
• 🔮 Bill predictions based on available readings or appliance estimates
• 🔔 Household alerts with read and dismiss actions
• 💡 Saving-tip recommendations, bookmarks, feedback, and estimated savings
• 🧭 Dashboard summary for usage, bill, budget, appliances, alerts, and weekly actions
• 📚 Swagger UI for interactive API exploration
• ♿ Responsive frontend with loading, error, empty, and accessibility states

Tech Stack

Area	Technology
Frontend	React, Vite, Tailwind CSS, React Router, Axios, Recharts
Backend	Node.js, Express
Database	MongoDB, Mongoose
Authentication	JSON Web Tokens, bcrypt
Validation	Joi, express-validator
Security	Helmet, CORS allow-list, rate limiting
Backend tests	Jest, Supertest
Frontend tests	Vitest, React Testing Library, MSW, jest-axe
API documentation	Swagger UI
CI	GitHub Actions
Hosting	Vercel (frontend), Render (backend), MongoDB Atlas (database)

Architecture Overview

flowchart LR
    A[React + Vite SPA] -->|Axios / JSON / JWT| B[Express API<br/>/api/v1]
    B -->|Controllers → Services → Mongoose| C[(MongoDB)]

Loading

The frontend lazy-loads route pages and uses a shared Axios client for authenticated API requests. The backend separates HTTP routing, validation, controllers, business services, and persistence models. Household access checks protect private records, while admin middleware protects management endpoints.

See Architecture for the detailed system design.

Repository Structure

PowerWise/
  .github/workflows/        Continuous integration
  backend/
    scripts/seed/            Tariff and saving-tip seeders
    src/
      config/                Environment, database, and Swagger setup
      controllers/           HTTP request handlers
      data/                  Appliance preset data
      middleware/            Authentication, validation, and errors
      models/                Mongoose models
      routes/                API route definitions
      services/              Domain and calculation logic
      utils/                 Response and email helpers
      validators/            Shared request schemas
    tests/
      integration/           API and authorization tests
      load/                  Local Artillery scenarios
      unit/                  Calculation and helper tests
  frontend/
    public/                  Static public files
    src/
      assets/                Imported images
      components/            Layout, feature, and UI components
      context/                Authentication state
      lib/                    Shared frontend utilities
      pages/                  Route-level screens
      services/               API clients
      test/                   Shared test setup and accessibility checks
  docs/                       Architecture, testing, and deployment guidance

Getting Started

Prerequisites

• Node.js 22.22 or later for the full backend and frontend workspace
• npm
• MongoDB running locally, or a MongoDB Atlas connection string

The backend alone supports Node.js 20.19 or later. Use Node.js 22.22 or later for local full-stack work and deployment so both applications use the same supported runtime.

Backend

cd backend
npm install
cp .env.example .env
npm run dev

At minimum, configure MONGODB_URI and a long random JWT_ACCESS_SECRET. The API starts at http://localhost:5000 by default.

Endpoint	Purpose
http://localhost:5000/api/v1/health	Health check
http://localhost:5000/api/v1/docs	Swagger UI
http://localhost:5000/api/v1	API base

Optional starter data:

npm run seed:tariffs
npm run seed:tips

Seeded tariffs are configuration examples and are not guaranteed to match current official rates.

For a connected demo household, set DEMO_USER_PASSWORD in the trusted shell environment and run:

npm run seed:demo

Optional administrator seeding uses DEMO_SEED_ADMIN=true and DEMO_ADMIN_PASSWORD. To remove only the allowlisted demo accounts and PowerWise Demo Home data, set DEMO_SEED_RESET_CONFIRM=POWERWISE_DEMO_RESET and run npm run seed:demo:reset. Never store demo passwords in source files or public documentation.

Frontend

cd frontend
npm install
cp .env.example .env
npm run dev

The frontend starts at http://localhost:5173 by default.

Environment Variables

Backend variables are documented in backend/.env.example.

Variable	Purpose
MONGODB_URI	MongoDB connection string
MONGO_TEST_URI	MongoDB database used by tests
PORT	API port, default 5000
FRONTEND_URL	Allowed frontend origin
CORS_ALLOWED_ORIGINS	Optional comma-separated additional origins
JWT_ACCESS_SECRET	JWT signing secret
JWT_ACCESS_EXPIRE	JWT lifetime
ADMIN_SECRET_KEY	Controls administrator registration
RATE_LIMIT_*	General API rate-limit settings
AUTH_RATE_LIMIT_*	Authentication rate-limit settings
SMTP_* and FROM_*	Optional password-reset email configuration
OPENWEATHER_API_KEY	Optional weather enrichment
CARBON_API_KEY	Optional carbon data enrichment

Frontend configuration:

VITE_API_BASE_URL=http://localhost:5000/api/v1

Never commit real credentials or production environment files.

Testing

The project ships with automated backend and frontend suites: 50 backend tests across 5 suites, and 14 frontend tests across 8 files.

Backend:

cd backend
npm test
npm run test:unit
npm run test:integration
npm audit

Frontend:

cd frontend
npm run lint
npm test
npm run build
npm audit

Local load-test instructions are available in backend/tests/load/README.md. See Testing for full coverage details and known gaps.

Deployment

PowerWise is deployed and live:

Layer	Service	Status
Frontend	Vercel	✅ Live — powerwise.vercel.app
Backend	Render web service	✅ Live
Database	MongoDB Atlas	✅ Live

To deploy your own instance, follow Deployment and complete the Production Checklist before publishing an environment.

Security Notes

• Protected routes require a valid bearer token.
• Admin endpoints require an authenticated administrator role.
• Household records are checked against owner, member, or administrator access.
• Request validation rejects malformed identifiers and unsupported input.
• Helmet, restricted CORS, and API rate limits are enabled.
• Production errors use a normalized response without raw server details.
• Password-reset tokens are stored as hashes and email delivery requires SMTP configuration.
• Secrets belong in environment variables and must never be committed.

Known Limitations

• Tariff records are configurable project data, not a guarantee of current official utility pricing.
• Full browser end-to-end coverage is not yet included.
• Monitoring and hosted error tracking are not connected to a provider.
• Password-reset delivery depends on valid SMTP configuration.
• The application does not include utility-provider, smart-meter, SMS, or WhatsApp integrations.

Future Improvements

• Add stable browser end-to-end tests for critical user journeys.
• Add Sinhala and Tamil translations with user-tested terminology.
• Connect monitoring, structured logging, and hosted error tracking.
• Establish a reviewed process for updating tariff data.
• Expand accessibility testing across authenticated pages.
• Add deployment-specific backup and recovery procedures.

Documentation

• Architecture
• Testing
• Deployment
• Production Checklist

Authors

• Shiham Ahamed
• Kavishka Sandaruwan
• nadeeshan1
• Imesha Dissanayaka