Smart Community Energy Saving Planner

A production-grade web-based system for residential communities to analyze, predict, and reduce electricity consumption using historical bill data, statistical machine learning models, and rule-based recommendations.

🎯 Project Overview

This system helps residential communities:

• Analyze electricity consumption patterns with deterministic analytics
• Predict future consumption using classical ML models
• Reduce energy waste through actionable recommendations
• Compare household performance against community averages
• Track consumption trends over time

🏗️ Technology Stack

Backend

• FastAPI - Modern, fast web framework
• SQLAlchemy - SQL toolkit and ORM
• PostgreSQL - Relational database
• scikit-learn - Machine learning library
• APScheduler - Background job scheduling
• pytesseract - OCR for bill processing

Frontend

• HTML5/CSS3 - Structure and styling
• Vanilla JavaScript - No framework dependencies
• Chart.js - Data visualization

📋 Features

1. User Roles & Authentication

• Community Admin: Register community, create households
• Household User: Upload bills, view analytics, get recommendations
• JWT-based authentication with role-based access control

2. Electricity Bill Processing

• Upload bill images/PDFs with OCR extraction
• Manual entry option
• Automatic data validation and correction

3. Analytics Module

• Monthly consumption trends
• Year-over-year comparisons
• Community average comparisons
• Cost per unit analysis
• Spike and anomaly detection

4. Machine Learning Predictions

• Linear Regression: Trend-based forecasting
• Moving Average: Recent pattern analysis
• Exponential Smoothing: Weighted historical data
• Ensemble predictions combining all models

5. Recommendation Engine

• Rule-based energy-saving suggestions
• Triggers:
  • High consumption detected
  • Rising consumption trend
  • Predicted spike
  • Above community average
  • Seasonal inefficiency
• Actionable suggestions with estimated savings

🚀 Installation & Setup

Prerequisites

• Python 3.9+
• PostgreSQL 12+
• Tesseract OCR
• Node.js (optional, for development tools)

Step 1: Clone Repository

git clone <repository-url>
cd SmartCommunitiPlanner

Step 2: Setup Python Environment

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

pip install -r requirements.txt

Step 3: Install Tesseract OCR

Windows:

1. Download from: https://github.com/UB-Mannheim/tesseract/wiki
2. Install and note the installation path
3. Update .env with Tesseract path

Linux:

sudo apt-get install tesseract-ocr

Mac:

brew install tesseract

Step 4: Setup PostgreSQL Database

# Create database
psql -U postgres
CREATE DATABASE smart_community;
CREATE USER smartuser WITH PASSWORD 'yourpassword';
GRANT ALL PRIVILEGES ON DATABASE smart_community TO smartuser;
\q

Step 5: Configure Environment

cp .env.example .env
# Edit .env with your database credentials and secret key

Step 6: Initialize Database

# Run Python shell
python
>>> from app.models import init_db
>>> init_db()
>>> exit()

Step 7: Run Application

# Development mode
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production mode
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Step 8: Access Application

• API Documentation: http://localhost:8000/docs
• Frontend: http://localhost:8000/login.html

📁 Project Structure

SmartCommunitiPlanner/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI application
│   │   ├── scheduler.py         # Background jobs
│   │   ├── models/              # SQLAlchemy models
│   │   │   ├── base.py
│   │   │   ├── community.py
│   │   │   ├── household.py
│   │   │   ├── user.py
│   │   │   ├── electricity_bill.py
│   │   │   ├── analytics_result.py
│   │   │   ├── prediction_result.py
│   │   │   └── recommendation.py
│   │   ├── routes/              # API endpoints
│   │   │   ├── auth.py
│   │   │   ├── community.py
│   │   │   ├── household.py
│   │   │   ├── bills.py
│   │   │   ├── analytics.py
│   │   │   ├── predictions.py
│   │   │   └── recommendations.py
│   │   ├── services/            # Business logic
│   │   │   ├── ocr_service.py
│   │   │   ├── analytics_service.py
│   │   │   ├── prediction_service.py
│   │   │   └── recommendation_service.py
│   │   ├── schemas/             # Pydantic schemas
│   │   └── utils/               # Helper functions
│   │       ├── security.py
│   │       └── auth.py
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── login.html
│   ├── household-dashboard.html
│   └── static/
│       ├── css/
│       │   └── style.css
│       └── js/
│           ├── app.js
│           ├── auth.js
│           └── dashboard.js
└── README.md

🔐 Default Credentials

After setup, create your first community through the registration page.

📊 Database Schema

Core Tables:

• communities: Community information
• households: Household details
• users: Authentication and role management
• electricity_bills: Bill data with OCR results
• analytics_results: Computed analytics
• prediction_results: ML predictions
• recommendations: Energy-saving recommendations

All tables use UUID primary keys and proper foreign key relationships.

🧪 Testing

Manual Testing

1. Register a community
2. Create households as community admin
3. Login as household user
4. Upload electricity bills
5. View analytics and predictions
6. Generate recommendations

API Testing

Use the interactive API documentation at /docs

🔄 Background Jobs

The system runs periodic background jobs:

• Daily (2 AM): Recalculate analytics for all households
• Monthly (1st, 3 AM): Generate next month's predictions
• Weekly (Monday, 6 AM): Generate new recommendations

📈 Machine Learning Models

Linear Regression

• Uses historical data to fit a linear trend
• Good for stable consumption patterns
• Provides R² accuracy score

Moving Average (3-month window)

• Averages last 3 months for prediction
• Responds quickly to recent changes
• Simple and interpretable

Exponential Smoothing (α=0.3)

• Weighted average favoring recent data
• Balances historical patterns and recent trends
• Smooth predictions with less noise

🎨 Frontend Features

Household Dashboard

• Overview with key metrics
• Bill upload and management
• Interactive analytics charts
• Prediction visualizations
• Recommendation cards

Community Dashboard (Admin)

• Household management
• Aggregated community analytics
• Household performance distribution

🔒 Security

• Passwords hashed with bcrypt
• JWT tokens for authentication
• Role-based access control
• Input validation on all endpoints
• SQL injection protection via ORM
• CORS configuration

🚧 Production Deployment

Environment

• Use strong SECRET_KEY
• Set DEBUG=False
• Configure proper CORS_ORIGINS
• Use production PostgreSQL server
• Set up SSL/TLS certificates

Performance

• Use gunicorn/uvicorn workers
• Enable database connection pooling
• Implement rate limiting
• Set up caching (Redis)
• Use CDN for static files

Monitoring

• Application logging
• Error tracking (Sentry)
• Performance monitoring
• Database query optimization

📝 API Documentation

Interactive API documentation available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🤝 Contributing

This is an academic/demonstration project. For improvements:

1. Follow existing code structure
2. Add proper documentation
3. Write tests for new features
4. Follow PEP 8 style guide

📄 License

[Specify License]

👥 Authors

[Your Name/Team]

🙏 Acknowledgments

• FastAPI documentation
• scikit-learn community
• Chart.js library
• Tesseract OCR project

📞 Support

For issues or questions:

• Open an issue in the repository
• Contact: [your-email]

---

Note: This system is designed for educational and demonstration purposes. For production deployment, conduct proper security audits and load testing.

Login Credentials:

Default credentials have been removed for security. Please set up your own users after deployment.