MGPlanner

MGPlanner is a web-based planning workspace for microgrid sizing, renewable resource preparation, optimization runs, and result review. It is designed for engineering teams that need to compare photovoltaic, wind, battery, diesel, and grid-connected planning options across project sites.

The application combines a FastAPI backend, an RQ worker, a Next.js frontend, and a Python optimization engine. Users work in the browser to define projects, generate resource curves, prepare load profiles, run optimization jobs, compare solutions, and export results.

This README is an application and deployment guide. It intentionally does not document the mathematical formulation, variable definitions, or constraint derivations.

Main Capabilities

• Project workspace management with local accounts and optional OIDC-based authentication.
• Wind, PV, and load curve preparation for microgrid planning studies.
• Scenario construction and generated input workbook management.
• Optimization job submission through FastAPI and asynchronous RQ workers.
• Result review for capacity, dispatch, financial indicators, and feasibility diagnostics.
• Frontend report and chart export support.
• Deterministic, stochastic, multi-zone, and staged-capacity planning paths in the Python optimization engine.

Repository Layout

.
|-- backend/                 # FastAPI API, RQ integration, auth, storage, jobs
|-- frontend/                # Next.js application and frontend unit tests
|-- models/                  # Python optimization engine modules
|-- scripts/                 # Source-code helpers for built-in load datasets
|-- tests/                   # Backend and optimization tests
|-- web/                     # Resource and load-generation utility modules
|-- main.py                  # Batch optimization entry point used by backend jobs
|-- data_io.py               # Excel and case input/output utilities
|-- tariff_utils.py          # Tariff and time-series utilities
|-- export_eval_inputs.py    # Evaluation workbook export helpers
|-- requirements.txt         # Core Python optimization dependencies
`-- README.md

The synchronized repository intentionally excludes local configuration files, sample case datasets, sample case documents, runtime outputs, caches, pmtiles map archives, and real source data. Runtime configuration and input data should be supplied by the deployment environment or uploaded through the application.

Runtime Components

MGPlanner is normally run as four cooperating processes:

1. Redis for RQ queues.
2. FastAPI backend on port 8000.
3. RQ worker for optimization and generation jobs.
4. Next.js frontend on port 3010.

The frontend communicates with the backend through NEXT_PUBLIC_API_BASE. The backend writes uploads, generated inputs, project snapshots, job logs, and the SQLite workspace database under runtime directories. These directories are not part of the source repository.

Requirements

Recommended baseline:

• macOS or Linux.
• Python 3.11.
• Node.js 20 or newer.
• Redis 6 or newer.
• A MILP solver supported by PuLP. The project can use the default PuLP solver stack, and can also use external solvers such as HiGHS, CBC, GLPK, or Gurobi when they are available in the runtime environment.

Core Python packages are listed in:

• requirements.txt for the optimization engine.
• backend/requirements.txt for the API, queue worker, reporting, curve generation, and optional load-generation features.

Frontend packages are listed in frontend/package.json.

Some resource-generation features use scientific weather and power libraries such as pvlib, windpowerlib, xarray, netCDF4, cfgrib, eccodes, and cdsapi. ERA5 access requires the deployment environment to provide valid CDS API credentials.

Local Development Setup

Clone the repository and enter the project directory:

git clone https://github.com/ynot0083/Microgrid-Sizing.git
cd Microgrid-Sizing

Create a Python environment:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
pip install -r backend/requirements.txt

Install frontend dependencies:

cd frontend
npm install
cd ..

Start Redis in a separate terminal:

redis-server --port 6379

Start the FastAPI backend:

source .venv/bin/activate
python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000

Start the worker in another terminal:

source .venv/bin/activate
python backend/worker.py

Start the frontend:

cd frontend
NEXT_PUBLIC_API_BASE=http://127.0.0.1:8000 npm run dev

Open the application at:

http://127.0.0.1:3010

Backend Configuration

The backend is configured through environment variables. Common settings:

Variable	Default	Purpose
REDIS_URL	redis://127.0.0.1:6379/0	Redis connection string
RQ_QUEUE_NAME	optimization	Queue used by API and worker
DEFAULT_CONFIG_PATH	config.yaml	Optional default planning config path
UPLOAD_DIR	tmp/uploads	Uploaded files
LOG_DIR	tmp/job_logs	Job logs
PROJECT_DIR	tmp/projects	Project snapshots and generated inputs
DATABASE_PATH	tmp/mgplanner.db	SQLite workspace database
CORS_ORIGINS	local frontend URLs	Allowed browser origins
FRONTEND_RENDER_BASE_URL	http://127.0.0.1:3010	Frontend URL for rendering/export tasks
FRONTEND_BASE_URL	frontend render URL	Public frontend URL
AUTH_MODE	local	local, oidc, or hybrid auth mode

OIDC deployments should also provide:

• OIDC_ISSUER
• OIDC_DISCOVERY_URL
• OIDC_CLIENT_ID
• OIDC_CLIENT_SECRET
• OIDC_REDIRECT_URI
• OIDC_SCOPES
• OIDC_ALLOWED_GROUPS
• OIDC_ADMIN_GROUPS

Do not commit secrets or environment-specific configuration into this repository.

Frontend Configuration

The frontend reads:

Variable	Purpose
NEXT_PUBLIC_API_BASE	Backend API base URL used by browser requests

For local development:

NEXT_PUBLIC_API_BASE=http://127.0.0.1:8000 npm run dev

For production builds:

cd frontend
NEXT_PUBLIC_API_BASE=https://your-api.example.com npm run build
npm run start

Deployment Notes

A production deployment should run these services under a process manager, container platform, or service supervisor:

• Redis
• FastAPI backend
• RQ worker
• Next.js frontend

Recommended deployment practices:

• Put the frontend and backend behind HTTPS.
• Set FRONTEND_BASE_URL, FRONTEND_RENDER_BASE_URL, CORS_ORIGINS, and NEXT_PUBLIC_API_BASE to public deployment URLs.
• Use persistent storage for DATABASE_PATH, PROJECT_DIR, UPLOAD_DIR, and LOG_DIR.
• Keep source data, uploaded case files, generated curves, job logs, reports, and exported workbooks outside the Git repository.
• Provide solver binaries and licenses at the operating-system or container level when using commercial solvers.
• Provide CDS API credentials only in the deployment environment when ERA5 downloads are enabled.

Batch Optimization Entry Point

The web application is the primary user interface. The Python batch entry point is still available for controlled offline runs:

source .venv/bin/activate
python main.py --config /path/to/config.yaml

The config file and input workbooks are deployment or project artifacts. They are not included in the synchronized repository.

Testing

Run backend and optimization tests:

source .venv/bin/activate
PYTHONPATH=. pytest tests

Run frontend unit tests:

npm --prefix frontend run test:unit

Run a Python syntax check:

python -m compileall -q backend/app models web main.py data_io.py tariff_utils.py export_eval_inputs.py scripts tests

Runtime Data Policy

The repository is source-only. It should not contain:

• Environment files or secrets.
• Local solver configuration.
• Case-specific input workbooks.
• Training datasets.
• ERA5 or other source-data caches.
• Generated reports or optimization outputs.
• Browser, Python, Node.js, or test caches.

This keeps the remote repository focused on the application code needed to install, deploy, test, and run MGPlanner.