Overview

GridGPT is an open-source, real-time monitoring dashboard for Ontario's electricity grid. It ingests public data from the Independent Electricity System Operator (IESO) and presents it in a dense, analyst-grade interface across nine pricing zones. The dashboard covers zonal pricing, provincial demand, generation by fuel type, intertie flows to neighbouring jurisdictions, weather overlays, and a text-to-SQL AI chatbot that can query any of the underlying data using natural language.

The project is a full-stack engineering portfolio piece built to demonstrate real-time data pipeline design, time-series analytics, and AI-augmented data exploration. Every layer — from the Python producer that parses IESO XML feeds, to the ClickHouse OLAP storage, to the SSE-streamed chat interface — is designed for low-latency observability of a complex, always-on system.

Why Blueprint.js?

Blueprint.js was chosen as the component library because it was purpose-built for data-dense enterprise applications — exactly the kind of interface an electricity grid dashboard needs.

• Data-dense layouts — Blueprint is designed for complex dashboards with tables, trees, and multi-panel views, not consumer landing pages. It doesn't waste space on oversized padding or rounded cards.
• Dark-first design — A native dark theme ships out of the box. No CSS override hacks, no theme provider workarounds. The dark theme is a first-class citizen.
• TypeScript native — Full type definitions for every component and prop, matching the strict TypeScript configuration used throughout this project.
• 500+ icons — A comprehensive icon system for status indicators, navigation, fuel types, and controls without pulling in a separate icon library.

System Architecture

Data flows through a streaming pipeline from IESO's public report servers into the dashboard. Each stage is designed for reliability and low latency.

A separate WMS connection to Environment and Climate Change Canada (ECCC) feeds weather overlays (temperature, cloud cover, precipitation) directly into the map component via GDPS forecast layers.

Dashboard Panels

The dashboard is built around six panels, each showing a different facet of Ontario's grid in real time.

Grid AI: Text-to-SQL Architecture

Grid AI is a context-grounded query assistant that translates natural language into validated ClickHouse SQL. Rather than relying on the LLM's general knowledge, every query is anchored in domain expertise assembled from four context layers.

Context Layers

Tool Loop

The chat API uses Claude's tool-use capability with a query_clickhouse tool. On each turn, the model generates SQL plus a plain-English strategy explanation. The SQL passes through a safety validator (SELECT-only, LIMIT required, no system table access) before executing against ClickHouse. If the query returns an error or empty results, the model can retry with corrected SQL for up to 5 iterations.

SSE Streaming

Results stream to the browser via Server-Sent Events. The frontend receives four event types: tool_use (SQL + strategy), tool_result (row count + duration), text_delta (chunked natural language response), and done. The Grid AI component renders tool badges, strategy text, markdown-formatted answers, and persists conversations in localStorage.

API Reference

The Next.js API layer exposes 19 routes organized into five categories. All routes query ClickHouse directly and use force-dynamic for real-time data.

Weather Integration

The Ontario Zone Map displays weather overlays sourced from ECCC's Global Deterministic Prediction System (GDPS) via WMS tile layers. Three layers are available: surface temperature, cloud cover, and total precipitation.

Weather frames are snapped to 3-hour forecast boundaries (00Z, 03Z, 06Z, etc.) to match GDPS model runs. The map uses a double-buffering technique: the next forecast image loads in a hidden layer while the current one displays, so transitions between time steps are smooth instead of flickering.

Next.js Techniques

• Dynamic imports for Leaflet — The map component uses next/dynamic with ssr: false to avoid window is not defined errors during server-side rendering. Leaflet requires a browser environment.
• force-dynamic on all API routes — Every API route exports export const dynamic = 'force-dynamic' to ensure fresh ClickHouse queries on every request rather than serving stale cached responses.
• Revalidation on ClickHouse fetch — The ClickHouse HTTP client uses next: { revalidate: 5 } to allow brief caching while keeping data near-real-time.
• Client-side hydration for suggested questions — The Grid AI panel renders a deterministic set of suggested questions on the server, then randomizes them client-side after hydration to avoid mismatch errors.

Hosting & Infrastructure

The system is split across two hosting providers, optimized for cost and reliability:

• Frontend on Vercel — The Next.js app runs as serverless functions for API routes and uses Vercel's edge CDN for static assets. This handles bursty user traffic with auto-scaling at near-zero idle cost.
• Backend on Hetzner VPS — A single VPS runs Docker Compose with 5 services: Redpanda, Redpanda Console, ClickHouse, Redis, and init-kafka. The Python producer runs on a cron schedule on the same machine. This provides persistent, always-on infrastructure for 24/7 data ingestion at ~$5–10/month.

The split rationale: Vercel handles user-facing traffic cheaply with auto-scaling, while Hetzner provides the stable, long-running services (Kafka, ClickHouse, Redis) that need to be online continuously regardless of user traffic.

Built with Claude Code

GridGPT was developed using Claude Code as the primary development tool. The project leveraged several MCP (Model Context Protocol) integrations and custom Skills to accelerate development:

• ClickHouse direct queries — A custom /query Skill for running ad-hoc SQL against the live database during development, validating schema designs and query patterns in real time.
• Context7 for documentation — Used for looking up Blueprint.js component APIs, Recharts configuration, Leaflet plugin patterns, and Next.js App Router conventions.
• Sequential Thinking for complex logic — Applied to multi-step problems like the text-to-SQL context assembly, timezone conversion strategy, and deduplication view design.
• Custom Skills — /dev (start all infrastructure), /query (run ClickHouse SQL), and /ingest (trigger a producer run) provided one-command workflows during development.

Tech Stack

Quick Start

# Start infrastructure
docker compose up -d

# Start frontend dev server
cd frontend && npm run dev

# Start producer (separate terminal, activate venv)
cd producer && source venv/bin/activate && python main.py

# Query ClickHouse directly
docker exec -it clickhouse clickhouse-client \
  -q "SELECT zone, price FROM ieso.v_zonal_prices \
      ORDER BY timestamp DESC LIMIT 9"

IESO Data Sources

All data comes from IESO's public report server. These reports are freely available and require no authentication.