Run it yourself · about 10 minutes

Run the demo on your laptop

The demo is the real MGC website running locally. The investment and energy maps load from snapshots in this folder (data/viz_cache); everything else on the site comes from the live mgc-api. The knowledge graph comes from a small local service that reads the graph database shipped in this folder (data/mgc_kg.demo.sqlite). You need a clone of the frontend repo and this folder; nothing else is downloaded except npm and pip packages.

Node.js 20.9+Next.js 16 requirement

Python 3.9+for the graph service

Git + GitHub accessto mapping-global-china

mgc-api credentialsusername and password for api.mapglobalchina.com

1Unzip this folder

Unzip mgc-kg-handoff.zip anywhere. Keep its layout intact: the scripts find the data by relative path. Below, HANDOFF means the full path to the unzipped mgc-kg-handoff folder.

export HANDOFF="$HOME/Downloads/mgc-kg-handoff"   # adjust to where you unzipped it

2Start the knowledge-graph service

The first run creates a Python environment and installs FastAPI and Uvicorn (about a minute). Leave this terminal running.

cd "$HANDOFF/demo"
./start-kg-service.sh

Check it in a second terminal: curl /kg/entity/country:PAK returns JSON for Pakistan and its relationships.

3Clone the frontend on the pull-request branch

git clone --branch feat/kg-relationships-panel https://github.com/mapping-global-china/mgc-frontend.git
cd mgc-frontend

Already have a clone? git fetch origin && git checkout feat/kg-relationships-panel && git pull instead.

4Apply the demo patch

A small, demo-only change to the API proxy: it sends /kg/* requests to the local graph service and serves the investment and energy maps from this folder's snapshots. It is off unless the env vars in step 5 are set. Do not commit it.

git apply "$HANDOFF/demo/frontend-kg-demo.patch"

5Create `.env.local`

Copy the template, fill in the mgc-api username and password, and point the cache at this folder.

cp "$HANDOFF/demo/frontend.env.local.example" .env.local
sed -i.bak "s#/ABSOLUTE/PATH/TO/mgc-kg-handoff#$HANDOFF#" .env.local && rm .env.local.bak
# then open .env.local and set MGC_API_USERNAME and MGC_API_PASSWORD

6Install and start the site

Port 3001 matches the demo buttons on the overview page.

npm ci
npm run dev -- -p 3001

7Walk through it

Investment map: click Pakistan, then the hub icon at the top right.
Energy map: click any power plant point.
Ask MGC: try what is the research for gwadar port in pakistan.
Raw graph JSON for Pakistan.

If something doesn't work

What you see	Cause and fix
Investment or energy map stays empty	`MGC_VIZ_CACHE_DIR` in `.env.local` doesn't point at this folder's `data/viz_cache`. Fix the path and restart `npm run dev`.
Other pages or country details don't load	They come from the live mgc-api: check the credentials in `.env.local`. On Sep 28 the live API was answering every request with 403 Forbidden (an nginx-level block, even for its health check), so this may be server-side rather than your setup.
Sidebar or Ask MGC shows no connections	The graph service isn't running, or `MGC_KG_API_BASE_URL` doesn't match its port. Re-run the check in step 2.
Port already in use	Pick another: `PORT=18011 ./start-kg-service.sh` (and update `MGC_KG_API_BASE_URL`), or `npm run dev -- -p 3002`.
`git apply` fails	Your checkout isn't on the latest `feat/kg-relationships-panel`, or it's already applied. Run `git pull`, then `git apply --check` to confirm.
Windows	Use WSL. Or run the service by hand: create a venv in `demo/kg-service`, `pip install -r requirements.txt`, then `uvicorn local_kg_api:app --port 18010` from that folder.

What's in this folder

Path	What it is
`data/mgc_kg.demo.sqlite`	The full knowledge graph the demo serves (44,781 entities, 118,205 relationships, 8,441 map links)
`data/viz_cache/`	Investment and energy map snapshots (energy: 742 plants, Sep 2 snapshot) so both demo maps load without the live API
`data/*.sql`, `data/mgc_kg_data.sql.gz`	Postgres and SQLite schemas, map links, and the full graph as a Postgres dump, for loading into the warehouse (backend guide)
`demo/start-kg-service.sh`, `demo/kg-service/`	The local graph service (FastAPI) and its start script
`demo/frontend-kg-demo.patch`, `demo/frontend.env.local.example`	The demo-only frontend patch and env template