OPTIGRID

Intelligent Energy Optimization

---

Built by Coreflow

---

---

In partnership with EPI-USE

---

Documentation

Document	Link
‣ Software Requirements Specification (SRS)	View SRS →
‣ Design Specification and Brand Style Guide	View →
‣ CI/CD Pipeline	View CI/CD →
‣ GitHub Project Board	View Board →
‣ Wireframes	View Wireframes →
‣ Brand Guidelines	View Brand Guidelines →

---

Team — Coreflow

Name	Student Number	GitHub	LinkedIn
Hamdaan Mirza	u24631494	GitHub	LinkedIn
Abdelrahman Ahmed	u24898008	GitHub	LinkedIn
Abhay Rooplall	u24568792	GitHub	LinkedIn
Talifhani Seaba	u23657350	GitHub	LinkedIn
Atidaishe Mupanemunda	u22747886	GitHub	LinkedIn

✉ Team Email: cos301.coreflow@gmail.com

📷 Team Photo:

---

Repository Structure

OptiGrid
├─ .dockerignore
├─ .eslintrc.cjs
├─ README.md
├─ backend
│  ├─ analytics
│  │  ├─ Dockerfile
│  │  ├─ requirements.txt
│  │  └─ src
│  │     └─ main.py
│  ├─ 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
│        ├─ data.csv
│        ├─ main.py
│        ├─ sensor_emulator.py
│        └─ worker.py
├─ docker-compose.yml
├─ docs
│  ├─ Brand_Guidelines.html
│  ├─ Design_Specifications.md
│  ├─ SRS.md
│  ├─ images/
│  └─ wireframes.html
├─ 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
│  ├─ next-env.d.ts
│  └─ tailwind.config.ts
├─ infrastructure
│  ├─ docker
│  │  └─ docker-compose.prod.yml
│  └─ terraform
│     ├─ .terraform.lock.hcl
│     ├─ docker-user-data.sh
│     ├─ main.tf
│     ├─ outputs.tf
│     ├─ providers.tf
│     ├─ tests/
│     └─ variables.tf
├─ playwright.config.ts
├─ pnpm-lock.yaml
├─ pnpm-workspace.yaml
├─ scripts/
├─ supabase
│  └─ seed.sql
└─ tests
   ├─ integration/
   └─ unit
      ├─ analytics/
      ├─ backend/
      └─ ingestion/

---

◈ Technology Stack

Frontend

• Framework: React + Next.js
• Styling: Tailwind CSS + Tremor
• Data Fetching: TanStack Query + Recharts

Backend

• Runtime: Node.js
• Task Queues/Caching: BullMQ + Redis

Database

• Relational: PostgreSQL (Supabase)
• Time-Series: InfluxDB
• ORM: Prisma ORM

Analytics

• Language: Python
• Modeling: Prophet + Scikit-Learn
• Lifecycle Management: MLFlow + Optuna

Infrastructure

• Containerization: Docker
• Cloud Hosting: AWS
• IaC: Terraform

DevOps

• CI/CD: GitHub Actions
• Workflow: Gitflow
• Package Manager: pnpm (monorepo)

Security & Authentication

• Auth Provider: Supabase Auth
• Vulnerability Scanning: Snyk

Testing

• Unit/Integration: Jest + Pytest + Supertest
• Testing Infrastructure: Testcontainers
• E2E Testing: 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

# Root dependencies
pnpm install

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

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

# Frontend
cd frontend && pnpm install

Environment Setup

Key environment variables:

Variable	Description
DATABASE_URL	PostgreSQL connection string (Supabase)
SUPABASE_URL	Your Supabase project URL
SUPABASE_ANON_KEY	Supabase anonymous public key
INFLUXDB_URL	InfluxDB connection URL
INFLUXDB_TOKEN	InfluxDB auth token
REDIS_URL	Redis connection URL

Run Locally

# Run all services concurrently
pnpm dev

# Run backend separately
cd backend && pnpm dev

# Run frontend separately
cd frontend && pnpm 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 Tests

# Run all tests
pnpm test:all

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

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

---

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 and main require at least two approved review. CI checks (lint, unit tests, build, integration tests) must pass 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 · Built for COS301 in partnership with EPI-USE}