Local development

Prerequisites

• Node.js 20+
• Optional: AWS SSO profile for deployed platform / ingest to S3

API + UI (typical)

# Terminal 1 — query API (reads graph once at startup)
HELIX_GRAPH_PATH="$(pwd)/scans/latest/reports/technical-graph.json" npm run dev:api

# Terminal 2 — Vite UI (proxies /query/* to :8787)
npm run dev --workspace=frontend

Open the URL printed by Vite (default http://127.0.0.1:5173). Ensure scans/latest symlinks to a scan with reports/technical-graph.json.

Or use the combined helper:

npm run dev:local-api

Ingest a new scan locally

npm run ingest:igentify
# or: npm run ingest -- --roots /path/to/repo ...

Point scans/latest at the new scan id if the CLI did not, then restart dev:api.

Environment variables

Variable	Used by	Purpose
HELIX_GRAPH_PATH	dev:api	Path to technical-graph.json
HELIX_SCAN_ROOT	dev:api	Scan folder for lazy AI artifacts
NEPTUNE_ENDPOINT	optional	Neptune openCypher reads (with tunnel)
VITE_APPSYNC_URL	frontend build	Live scan progress against AWS
VITE_COGNITO_*	frontend build	Auth against deployed pool

Copy frontend/.env.example to frontend/.env.local when pointing the UI at AWS.

Docs site

npm run dev -w @helix/docs-site
# VitePress prints the local preview URL in the terminal

Verify API

curl -sS http://localhost:8787/query/features | jq .
curl -sS http://localhost:8787/query/technical-graph | jq '.nodes | length'