docs/guides/local-development.md

# How to run the site locally

End-to-end development setup: backend Python env, frontend dev server, checkpoints on disk. Pick the path that matches what you're working on — backend-only and frontend-only flows are both supported. For a deployment-equivalent run see [guides/deploy.md](deploy.md) (`docker compose up`).

## Prerequisites

- Mamba (or conda). The repo root has an `environment.yml` capturing the conda half of the env.
- Node 20+ and npm.
- ~6 GB of free disk for the checkpoints if you intend to run inference locally.
- Optional: a Hugging Face account if you want to publish or update checkpoints.
- For Docker (`docker compose up`): WSL2 with at least **12 GB** of memory. Bumping `/dev/shm` is handled by `docker-compose.yml` (`shm_size: "2gb"`). Edit `%UserProfile%\.wslconfig`:
  ```ini
  [wsl2]
  memory=12GB
  processors=4
  swap=4GB
  ```
  then `wsl --shutdown` and restart Docker Desktop. The peak boot RAM is ~5–6 GB while the three COINs Loaders compute graph metrics.

## 1. Create the Python environment

From the repo root:

```bash
mamba env create -n website_c -f environment.yml
mamba activate website_c
pip install --extra-index-url https://download.pytorch.org/whl/cu118 -r src/backend/requirements.txt
```

This mirrors what the deployment image installs. The CUDA 11.8 wheels work on CPU-only machines too — they just bundle the CUDA runtime.

## 2. Pull checkpoints

If you have a Hugging Face account and the `Bani57/checkpoints` repo is accessible to you:

```bash
huggingface-cli login    # paste a read token
python -c "from huggingface_hub import snapshot_download; \
  snapshot_download(repo_id='Bani57/checkpoints', \
                    local_dir='src/research', local_dir_use_symlinks=False)"
```

If you only need the discovery endpoints (no inference), you can skip this — the backend logs warnings about missing checkpoints but starts up fine.

## 3. Run the Django backend

From `src/backend/`:

```bash
DJANGO_DEBUG=True python manage.py runserver 8000
```

The server listens on `http://localhost:8000`. The first start will:

- Skip the HF Hub download because the local `src/research/.../checkpoints/` dirs are populated.
- Scan checkpoints, load Loaders, generate sample subgraphs (~30 s).
- Then accept traffic.

`DJANGO_DEBUG=True` enables verbose error pages and exposes `POST /api/v1/debug/force-unlock`. Without it (`False`), `ALLOWED_HOSTS` and `CORS_ALLOWED_ORIGINS` are enforced strictly — set them via env vars.

Confirm with:

```bash
curl http://localhost:8000/api/v1/health
```

## 4. Run the Vue frontend

In a second shell, from `src/frontend/`:

```bash
npm install        # one-time
npm run dev
```

Vite serves on `http://localhost:5173`. The dev env (`src/frontend/.env.development`) points the SPA at `http://localhost:8000` for API calls — you'll need both servers running.

Open `http://localhost:5173` and exercise the three demos.

## 5. Hand-test the API

The Postman collection at `docs/postman/collection.json` covers every discovery endpoint and the prediction endpoint with sensible request bodies. Import the collection plus `docs/postman/environment.json`, point the base URL variable at `http://localhost:8000/api/v1`, and run.

For the streaming endpoints, browser dev tools (Network tab → an active SSE connection shows individual frames) are usually more informative than Postman.

## Troubleshooting

### "ModelRegistry not initialized"
You hit a view before `AppConfig.ready()` finished. Wait for the boot logs to print "ModelRegistry initialized" and retry.

### "Stale machines.npz for {dataset}: rebuilding"
Harmless. The cached `machines_*.npz` file on disk has an old `num_communities`; the registry rebuilds it in memory.

### `INFERENCE_BUSY` (429)
Another inference is already running. Wait, or `POST http://localhost:8000/api/v1/debug/force-unlock` if `DEBUG=True`.

### Frontend hits the wrong URL
Check `src/frontend/.env.development`. In dev it should be `VITE_API_BASE_URL=http://localhost:8000`. The composables append `/api/v1` themselves.

### `whitenoise` / `huggingface_hub` / `gunicorn` missing
The deployment image installs them; locally you may not need them, but if you've enabled `whitenoise` middleware in dev (it is in `MIDDLEWARE`) you do:

```bash
pip install "whitenoise[brotli]" huggingface_hub gunicorn
```

## See also

- [reference/api.md](../reference/api.md) — endpoint contracts.
- [reference/frontend-modules.md](../reference/frontend-modules.md) — frontend project layout.
- [explanation/inference-lifecycle.md](../explanation/inference-lifecycle.md) — what happens at boot and on each request.
- [guides/deploy.md](deploy.md) — running the full container locally and pushing to the HF Space.