Coreflow - OptiGrid - Intelligent Energy Optimization

---

Built by Coreflow

---

---

In partnership with EPI-USE

OptiGrid URL (Click to view)

---

Project Description

OptiGrid is a comprehensive software platform designed for intelligent energy optimisation and predictive analytics, utilising smart grid technology to help buildings reduce energy waste and optimise consumption. The system connects building managers and energy grids through a sophisticated data pipeline that facilitates telemetry ingestion, communicates forecasts, manages configurations, and provides real-time monitoring – all without fundamentally changing the existing building's physical infrastructure.

---

GitHub Project Board

View GitHub Project Board →

Demo 3

SRS Document: Functional Requirements (SRS)

SAS Document: Tracebility Matrix and NFR (SAS)

Service Contracts(SAS)

Coding Standards Document: Coding Standards

User Manual: User Manual

Testing Policy Document: Testing Policy

Brand Style Guide: Brand Style Guide

Demo 2

SRS Document: Functional Requirements (SRS)

SAS Document: Functional Requirements (SAS)

Coding Standards Document: Coding Standards

User Manual: User Manual

Testing Policy Document: Testing Policy

Brand Style Guide: Brand Style Guide

Demo 1

SRS Document: Functional Requirements (SRS)

Design Specification: Design Specification and Brand Style Guide

---

Team: Coreflow

Name	Student Number	GitHub	LinkedIn	Profile
Hamdaan Mirza	u24631494	GitHub	LinkedIn	Team Lead, Backend Developer.
Abdelrahman Ahmed	u24898008	GitHub	LinkedIn	Frontend Developer.
Abhay Rooplall	u24568792	GitHub	LinkedIn	Data & Analytics Engineer.
Talifhani Seaba	u23657350	GitHub	LinkedIn	Frontend Developer.
Atidaishe Mupanemunda	u22747886	GitHub	LinkedIn	Cloud & Infrastructure Engineer.

Team Email: cos301.coreflow@gmail.com

Team Photo:

---

Repository Structure

OptiGrid
├─ .dockerignore
├─ .eslintrc.cjs
├─ README.md
├─ backend
│  ├─ analytics
│  │  ├─ Dockerfile
│  │  ├─ requirements.txt
│  │  └─ src
│  ├─ configuration
│  ├─ core
│  │  ├─ .eslintignore
│  │  ├─ Dockerfile
│  │  ├─ jest.config.cjs
│  │  ├─ prisma/
│  │  ├─ prisma.config.ts
│  │  └─ src
│  │     ├─ app.ts
│  │     ├─ controllers/
│  │     ├─ lib/
│  │     ├─ routes/
│  │     ├─ server.ts
│  │     ├─ services/
│  │     ├─ types/
│  │     └─ validation/
│  └─ ingestion
│     ├─ Dockerfile
│     ├─ prisma/
│     ├─ requirements.txt
│     └─ src
├─ docker-compose.yml
├─ docs
│  ├─ SRS.md
│  |_ images/
├─ eslint.config.cjs
├─ frontend
│  ├─ .storybook
│  │  ├─ main.ts
│  │  └─ preview.ts
│  ├─ Dockerfile
│  ├─ app
│  │  ├─ (auth)
│  │  │  ├─ login/
│  │  │  └─ signup/
│  │  ├─ (dashboard)
│  │  │  ├─ buildings/
│  │  │  ├─ compare/
│  │  │  ├─ dashboard/
│  │  │  ├─ forecast/
│  │  ├─ api/
│  │  ├─ contact/
│  │  ├─ faqs/
│  │  ├─ health/
│  │  ├─ layout.tsx
│  │  ├─ page.tsx
│  │  └─ theme/
│  ├─ eslint.config.mjs
│  ├─ jest.config.cjs
│  ├─ jest.setup.ts
│  └─ tailwind.config.ts
├─ infrastructure
│  ├─ docker/
│  └─ terraform/
├─ playwright.config.ts
├─ pnpm-lock.yaml
├─ pnpm-workspace.yaml
├─ scripts/
├─ supabase/
└─ tests
   ├─ integration/
   └─ unit/
   |_e2e/

---

Technology Stack

Frontend: Next.js (React with TypeScript) For responsive web dashboard development. Fast iteration, rendering, and UI development using Tailwind CSS and Tremor. Supports dynamic data visualization via Recharts.

Backend: Node.js (Express with TypeScript) High-performance REST API handling user requests, background tasks via BullMQ, caching via Redis, and automated data syncing.

Database: PostgreSQL (Supabase) & InfluxDB Relational metadata stored in PostgreSQL and time-series telemetry data stored in InfluxDB. Object-relational mapping handled by Prisma.

Analytics: Python (Scikit-Learn, Prophet) Machine learning service for predicting energy demands. Optuna manages the lifecycle and hyperparameter tuning.

Hosting / Infrastructure: AWS Infrastructure deployed via Terraform and managed with Docker containers.

DevOps & Security: GitHub Actions Automated pipelines for testing, linting, and deployment. Vulnerability scanning with Snyk.

Testing: Jest, Pytest, Playwright Unit and integration testing. End-to-end testing with Playwright.

---

Getting Started

Prerequisites

Ensure the following are installed on your machine before proceeding:

• Node.js 18+
• Python 3.11+
• pnpm - npm install -g pnpm
• Docker & Docker Compose
• Redis (or run via Docker)

Clone & Install Dependencies

git clone https://github.com/COS301-SE-2026/OptiGrid
cd OptiGrid

# Install all Node.js workspace dependencies (Frontend & Backend Core)
pnpm install

# Install Python Analytics dependencies
pip install -r backend/analytics/requirements.txt

# Install Python Ingestion dependencies
pip install -r backend/ingestion/requirements.txt

Environment Setup

Create a .env.local file in the root directory. Key environment variables include:

Database & Supabase:

Variable	Description
DATABASE_URL	PostgreSQL connection string (Supabase)
SUPABASE_URL / NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL
SUPABASE_ANON_KEY / NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anonymous public key
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key for backend operations
SUPABASE_KEY	Alias for Supabase key

InfluxDB:

Variable	Description
INFLUXDB_URL	InfluxDB connection URL
INFLUXDB_TOKEN	InfluxDB authentication token
INFLUXDB_ORG	InfluxDB organization name
INFLUXDB_BUCKET	InfluxDB bucket name for energy data

Redis:

Variable	Description
REDIS_HOST	Redis server hostname
REDIS_PORT	Redis port number
REDIS_DB	Redis database index

Third-party & Security:

Variable	Description
RESEND_API_KEY	Resend API key for email notifications
HARDWARE_API_KEY	Authentication key for hardware sensors

Run Locally

# Run all services concurrently
pnpm dev

# Run backend separately
pnpm --filter @optigrid/core dev

# Run frontend separately
pnpm --filter @optigrid/frontend dev

Run with Docker

docker-compose up --build

Run Lint

# Frontend
pnpm --filter @optigrid/frontend run lint

# Backend
pnpm --filter @optigrid/core run lint

Run Unit Tests

# Run all unit tests
pnpm test:all

# Frontend unit tests only
pnpm --filter @optigrid/frontend run test

# Backend unit tests only
pnpm --filter @optigrid/core run test

Run Scalability Tests

The isolated local Docker suite measures 50/100/150 telemetry requests per second and reports both the original SRS-oriented criteria and revised architectural capability checks. A capability pass percentage does not establish SRS compliance; SC01 and scale-up request failures remain reported separately.

npm install --prefix tests/nfr/scalability --ignore-scripts
npm run test:nfr:scalability:assessment
npm run test:nfr:scalability:preflight
npm run test:nfr:scalability

See the setup and fixed test plan, fresh benchmark results, preserved original results, and revised-criteria reassessment. The full workload takes about 30 minutes after setup. A nonzero benchmark exit code still indicates at least one failing check, even when 60% of checks pass.

Run Integration Tests

# Run all backend integration tests
pnpm --filter @optigrid/core run test:integration

# Run backend integration tests using local Supabase instance
pnpm --filter @optigrid/core run test:supabase

Run E2E Tests (Playwright)

Use this flow to run end-to-end tests using Playwright.

# Run standard E2E test suite
pnpm run test:e2e

Running E2E tests with local Supabase: Use this flow when you want Playwright to test against the local Supabase emulator instead of the temporary Postgres container used by the default E2E launcher.

# Start local Supabase. If this repo has not been initialized locally yet,
# run 'supabase init' once from the repo root first.
supabase start
supabase status

# Run a specific test (e.g. create-building)
corepack pnpm run test:e2e:supabase -- tests/e2e/buildings/create-building.e2e.spec.ts

The Supabase E2E launcher reads supabase status -o env and maps the local DB_URL, API_URL, ANON_KEY, and SERVICE_ROLE_KEY into the app environment automatically. It also runs prisma db push --accept-data-loss before starting the core API. It does not run supabase/seed.sql; keep that seed aligned with the current Prisma schema before using supabase db reset.

---

Branching Strategy

This project follows GitFlow: a structured branching model that separates ongoing development from stable releases, enabling parallel feature work without destabilising production code.

Branch	Purpose
main	Production-ready code only. Merges happen here via tagged releases from develop. Direct commits are not permitted.
develop	The primary integration branch. All completed features and fixes are merged here before being released to main.
backend/feature/<name>	Short-lived branches for individual backend features or fixes. Branch off develop, merge back via pull request once reviewed.
frontend/feature/<name>	Short-lived branches for individual frontend features or UI changes. Branch off develop, merge back via pull request once reviewed.
integration/feature/<name>	Used for cross-cutting changes that span both frontend and backend (e.g. new API contracts, full-stack features). Branch off develop, merge back after integrated testing.

Pull Request policy: All merges into develop require at least two approved reviews. All merges into main require at least three approved reviews. All merges must pass all CI checks before merging.

---

Contact

Role	Name	Email
▸ Project Owner	Durandt Uys	durandt.uys@epiuse.com
▸ Project Mentor	Bryan Janse van Vuuren	bryan.janse.van.vuuren@epiuse.com
▸ Team	Coreflow	cos301.coreflow@gmail.com

---

_{© 2026 Coreflow · In partnership with EPI-USE}