PowerWise

PowerWise is a full-stack electricity bill reduction assistant designed for Sri Lankan households. It helps families record electricity use, estimate bills, manage a monthly budget, understand appliance consumption, and act on practical saving tips.

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

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.

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 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

Architecture Overview

React + Vite
    |
    | Axios / JSON / JWT
    v
Express API at /api/v1
    |
    | Controllers -> Services -> Mongoose models
    v
MongoDB

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

Local Setup

Prerequisites

• Node.js 20 or later
• npm
• MongoDB running locally, or a MongoDB Atlas connection string

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.

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

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 coverage details and known gaps.

Deployment

Layer	Suggested service
Frontend	Vercel
Backend	Render web service
Database	MongoDB Atlas

This repository has not been deployed. 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

• The application is not currently deployed.
• 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.

Screenshots

Screenshots of the landing page, household dashboard, meter readings, appliances, budgets, saving tips, and administration screens will be added before public portfolio publication.

Documentation

• Architecture
• Testing
• Deployment
• Production Checklist