POSEIDON - Real-Time Distributed Power Grid Monitoring System

IKEJA-GRID-MAP is a real-time distributed power grid telemetry dashboard designed for monitoring Ikeja Electric's distribution network across Lagos, Nigeria. The application visualizes operational distribution substations, feeders, and zones on Google Maps while integrating live national grid generation data directly from the Electricity Maps API.

---

⚡ Key System Features

• Live National Grid Integration: Fetches real-time generation metrics for Nigeria (NG), including carbon intensity ($\text{gCO}_2\text{eq/kWh}$), energy mix (Gas, Hydro, Solar percentages), and total national grid consumption (MW) via Electricity Maps API.
• Real-Time Distribution Simulation: Runs a high-performance background daemon thread simulating load fluctuations ($\pm 0.8\text{ MW}$), voltage ($\text{kV}$), and frequency ($\text{Hz}$) for 30+ substations across 7 operational zones (Ikeja, Surulere, Ikoyi, Lekki, Ajah, Agege, Oshodi) every 3 seconds.
• Brutalist Monochrome Aesthetic: High-end HUD interface built with pure black background (#000000), crisp white typography (#FFFFFF), zero rounded corners (border-radius: 0px), 1px solid sharp dividers, and floating overlays.
• Interactive Telemetry Overlay: Visualizes distribution substations using dynamic Google Maps circle overlays with real-time breathing animations (pulse on update), color-coded load severity thresholds, and hover InfoWindows.
• Network KMZ Support: Attempts automated loading of data/network.kmz network spatial layer onto Google Maps, with seamless fallback to native circle overlays.
• Clear Data Source Attribution: The UI explicitly distinguishes between LIVE NATIONAL DATA (Electricity Maps) and SIMULATED DISTRIBUTION DATA at all times.

---

📁 Repository File Structure

Poseidon/
├── backend/
│   ├── config.py             # Zones metadata, centroids, API endpoints, thresholds
│   ├── simulator.py          # GridSimulator engine & telemetry generator
│   ├── elecmaps_client.py    # Electricity Maps API client with 60s cache & fallback
│   ├── app.py                # Flask server, CORS, background thread & REST API routes
│   └── requirements.txt      # Python backend dependencies
├── frontend/
│   ├── index.html            # Fullscreen map layout & Brutalist HUD overlay HTML
│   ├── style.css             # Brutalist monochrome design system & responsive styling
│   ├── script.js             # Google Maps setup, circle overlays & polling engines
│   └── data/
│       └── network.kmz       # Ikeja Electric network spatial infrastructure archive
└── README.md                 # System documentation & deployment guide

---

⚡ Quick 1-Click Launch (Windows)

Simply open the project folder Poseidon in File Explorer and double-click start_app.bat (or START_HERE.cmd).

It will automatically:

1. Activate your Python environment.
2. Launch the Flask REST API & telemetry simulator background server.
3. Automatically open your browser to http://localhost:5000!

---

🚀 Deployment Instructions

Prerequisites

• Python 3.9 or higher
• Internet connection (for Google Maps JavaScript API & Electricity Maps API)

Step 1: Virtual Environment Setup

Windows (PowerShell or CMD):

python -m venv venv
venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Step 2: Install Backend Dependencies

pip install -r backend/requirements.txt

Step 3: Configure API Keys

1. Google Maps API Key:

   • Open frontend/index.html and replace YOUR_GOOGLE_MAPS_API_KEY in the Google Maps <script> tag:

     <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_ACTUAL_KEY&callback=initMap" async defer></script>

   • Open frontend/script.js if necessary to configure map bounds.

2. Electricity Maps API Key:

   • Open backend/config.py and replace YOUR_ELECTRICITY_MAPS_API_KEY:

     ELECTRICITY_MAPS_API_KEY = "YOUR_ACTUAL_ELECTRICITY_MAPS_KEY"

   • Note: If no key is provided, the backend will automatically render simulated national grid fallback data with a clear SIMULATED badge.

Step 4: Run Application Server

python backend/app.py

The server will start on http://localhost:5000.

Step 5: Launch Dashboard

Open your browser and navigate to:

http://localhost:5000

Alternatively, open frontend/index.html directly in any web browser.

---

📊 REST API Endpoints

Endpoint	Method	Description	Cache/Interval
GET /api/grid/snapshot	GET	Returns telemetry list of all substations (load, voltage, frequency, status)	Polled every 3s
GET /api/grid/aggregate	GET	Returns total grid load MW, peak zone, average frequency, and overload count	Polled every 3s
GET /api/zones	GET	Returns list of 7 operational zones and centroid coordinates	Static
GET /api/national/generation	GET	Returns national carbon intensity, generation mix %, and total MW (source: "live" or "simulated")	Cached 60s
GET /api/energymrc/industry	GET	Returns NESI macro industry metrics (Peak Gen, TCN Wheeling, Tariffs, ATCC Losses)	Cached 60s

---

🎨 Color Coding Rules & Load Severity

• < 5.0 MW: Pure White (#FFFFFF) — Light Load / Operational
• 5.0 - 10.0 MW: Medium Gray (#888888) — Moderate Load
• 10.0 - 15.0 MW: Dark Gray (#444444) — Heavy Load
• > 15.0 MW: Critical Red (#FF0000) — OVERLOADED / CRITICAL ALERT

---

🛡️ License

Built for internship portfolio demonstration at Ikeja Electric. Distributed under the MIT License.