---
title: WattLog
emoji: ⚡
colorFrom: yellow
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# ⚡ WattLog — Electricity Bill Tracker & Weather MCP Solar Forecasting

WattLog is a production-grade energy analytics and power distribution platform. It automatically extracts monthly bill data from PDF scans and photos via OCR, integrates an Open-Meteo **Weather MCP (Model Context Protocol) Server**, and predicts **next-month electricity bills (₹)** and **solar plant generation (kWh)** on unified analysis dashboards.

![WattLog Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)
![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)
![MCP Server](https://img.shields.io/badge/MCP-Weather%20Server-teal)
![Docker](https://img.shields.io/badge/Docker-Supported-blue)
![Render](https://img.shields.io/badge/Deploy-Render%20%7C%20Koyeb%20%7C%20Railway-purple)

---

## ☀️ Consumer Panels & Solar Configuration (1 to 5.2)

Solar capacity is installed exclusively on **Panels 2, 3, and 4**. Non-solar panels operate on grid-only power:

| Panel Identifier | USC Number | Solar Status | Solar Plant Capacity | Contract Load | Loads & Notes |
| :--- | :---: | :---: | :---: | :---: | :--- |
| **Sivam Panel-1** | `1211262001709` | ⚡ **GRID ONLY** | — | 4 kW | (NO LOADS) [Shifted to PL-2 / PL-3 on 16-08-2026] |
| **Sivam Panel-2** | `1211262001710` | ☀️ **SOLAR ACTIVE** | **5.90 kW** | 7 kW | South Lift, Water Pumps 1, 'A' Block Lighting, Security, CCTV |
| **Sivam Panel-3** | `1211262001711` | ☀️ **SOLAR ACTIVE** | **4.13 kW** | 4 kW | Middle Lift, 'B' Block Lighting, Water Pump-2 |
| **Sivam Panel-4** | `1211262001780` | ☀️ **SOLAR ACTIVE** | **5.90 kW** | 8 kW | North Lift, R.O Plant, Water Pumps 3 & 4 |
| **Sivam Panel-5.1** | `1211262001778` | ⚡ **GRID ONLY** | — | 5 kW | Flat No 110 (Gym) [Water Pumps 3 & 4 Shifted to PL-4 on 16/08/2026] |
| **Sivam Panel-5.2** | `1211262001781` | ⚡ **GRID ONLY** | — | 5 kW | Swimming Pool, Sweeper Room (Amenities Feeder) |
| **Total Solar Fleet** | `all` | ☀️ **ACTIVE TOTAL** | **15.93 kW** | **33 kW** | **Full Society Combined Common Supply Feeder** |

---

## 🌟 Application Features & Navigation

- **`/` (Tracker)**: Drag-and-drop bill upload (PDF scans & smartphone images), real-time OCR extraction, bill record editing, CSV export, and database management.
- **`/analysis` (Analytics & Forecast)**: 
  - Single monthly points for **All Panels Combined** (historical vs predicted trend).
  - Solar generation forecast & financial net savings for solar panels (Panels 2, 3, 4).
  - Clean grid-only analytics for non-solar panels.
- **`/distribution` (Electrical Distribution Matrix)**: Complete society technical specifications, transformer feeds (`SS-22: 160 kVA`, `SS-23: 160 kVA`, `SS-24: 250 kVA`), connection specs, and common supply panel feeder routes.
- **`/logs` (Activity & MCP Monitor)**: Audit log tracking every triggered action, request/response payload data size in bytes, and real-time Weather MCP connection status.
- **Automatic Database Seeding**: Ships with `seed_bills.json`. When deployed to a clean container or cloud host, the database initializes and auto-populates the 35 historical bills across all 6 panels on first startup!

---

## 🌐 Web Deployment Guide (100% Free Tiers)

### Option 1: Deploy on Render.com (Recommended — Easiest & Free)

Render provides a 100% free web service tier that connects directly to your GitHub repository.

1. **Push your code to GitHub**:
   ```bash
   git init -b main
   git add .
   git commit -m "feat: Production-grade WattLog release"
   git remote add origin https://github.com/<your-username>/<your-repo-name>.git
   git push -u origin main
   ```
2. **Deploy on Render**:
   - Go to [dashboard.render.com](https://dashboard.render.com/) and sign in with GitHub.
   - Click **New +** -> **Blueprint** (or **Web Service**).
   - Select your repository.
   - If using **Blueprint**: Render automatically detects [`render.yaml`](render.yaml) and configures everything.
   - If setting up **Web Service manually**:
     - **Name**: `wattlog`
     - **Environment**: `Python 3`
     - **Build Command**: `pip install -r requirements.txt`
     - **Start Command**: `gunicorn wsgi:app`
     - **Plan**: `Free`
   - Click **Create Web Service**.
3. **Access Your App**:
   Render will deploy your app in 2-3 minutes and assign a public URL (e.g. `https://wattlog.onrender.com`).

---

### Option 2: Deploy on Koyeb (Free Docker Tier)

Koyeb offers a free tier with 512 MB RAM and global edge deployment.

1. Create a free account at [koyeb.com](https://www.koyeb.com/).
2. Click **Create App** -> **GitHub**.
3. Select your WattLog repository.
4. Set builder to **Dockerfile** (it automatically uses our production [`Dockerfile`](Dockerfile)).
5. Set port to `5000` and deploy.

---

### Option 3: Deploy on Railway (Free Trial / Starter)

1. Go to [railway.app](https://railway.app/).
2. Click **New Project** -> **Deploy from GitHub repo**.
3. Select your WattLog repository.
4. Railway will automatically detect the [`Procfile`](Procfile) and [`Dockerfile`](Dockerfile), build the app, and provide an instant public domain.

---

### Option 4: Deploy on Hugging Face Spaces (100% Free Docker Space)

1. Go to [huggingface.co/spaces](https://huggingface.co/spaces) and click **Create new Space**.
2. Space SDK: Select **Docker** -> **Blank**.
3. Clone the space repo or push this repository to your Space remote:
   ```bash
   git remote add space https://huggingface.co/spaces/<your-username>/<your-space-name>
   git push space main
   ```
4. Hugging Face builds and hosts your app completely free with zero maintenance.

---

### Option 5: Self-Hosted / VPS Deployment with Docker Compose

If you have a Linux VPS (Ubuntu/Debian) or local server:

```bash
# Clone the repository
git clone https://github.com/<your-username>/wattlog.git
cd wattlog

# Build and start in background
docker-compose up --build -d
```
The application will run on port `5000` with automated persistent storage mapped to `wattlog_data`.

---

## 🛠️ Local Development Setup

```bash
# 1. Clone repository
git clone https://github.com/<your-username>/wattlog.git
cd wattlog

# 2. Create virtual environment
python -m venv .venv

# On Windows:
.venv\Scripts\activate
# On Linux / macOS:
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start backend server
python app.py
```
Open your browser at `http://localhost:5000`.

---

## 🧪 Running Automated Tests

```bash
python -m unittest discover tests
```
Runs the complete test suite verifying:
- Panel configurations and solar capacities (Panels 1 to 5.2).
- Weather MCP Server communication and Open-Meteo tool calls.
- Non-solar panels solar exclusion.
- All panels combined monthly point aggregation.
- Persistent action logging and payload data size monitoring.

---

## 📄 License
MIT License. Created for Sivam Enclave Apartment & Flat Owners Welfare Association.