NEST Runbook

What it is

nest.thephenom.app is the production NEST application – the primary authenticated user-facing interface for the Phenom platform. It is deployed to Cloudflare Pages from the main branch of the Phenom-Backend GitHub repository. All production users interact with this deployment. Downtime here is a P1 incident.

Deployment chain

Merging to the main branch (via reviewed PR — never a direct push) triggers an automatic build and deployment on Cloudflare Pages.

Feature — Skia media HUD (tactical readout over event video)

The event media player (FloatingMediaCard) can draw a tactical HUD over a telemetry-bearing clip — a compass/heading tape, pitch ladder, boresight, and a lat/lon/alt readout — tracking playback time. It is the web mirror of the native PhenomApp TacticalHUD (CanvasKit/Skia, self-hosted wasm, no CDN egress). The HUD toggle rides on the media card in both globe view and street view (the card is shared), and disables gracefully (greyed toggle) when an event has no telemetry. (#541)

Where the pose comes from (important): the per-sample pose is read from the media’s signed C2PA app.thephenom.sensor_telemetry assertion, not a separate sidecar file. FloatingMediaCard fetches GET /api/events/:id/telemetry; the nest-api route resolves it in order:

1. a bundled C2PA extraction for verified events (BUNDLED_TELEMETRY in admin_sandbox/nest-api/src/routes/event-telemetry.ts — currently the c101f1bf fixture and Lenval Logan’s event 80c5231f, extracted from the video’s assertion via c2patool);
2. any event with a .sidecar.json capture file (fetched from S3, wrapped);
3. otherwise 404 → the HUD stays disabled.

So the HUD lights up for any event whose telemetry the endpoint can serve. The durable path is the extract-at-signing pipeline (#471), which will replace the manually-seeded bundled extractions.

Verify a specific event has telemetry:

curl -s https://nest.thephenom.app/api/events/80c5231f-15eb-48eb-92ed-c4725d2fa533/telemetry \
  -H "Authorization: Bearer <cognito-id-token>" | head -c 120
# Expected: {"version":2,"sampleRateHz":10,...,"samples":[{"timestampMs":0,"heading":...

Common operations

Deploy a new release to production

# Merge develop -> main via GitHub PR (required path — never push main directly)
gh pr create --base main --head develop \
  --title "Release: $(date +%Y-%m-%d)" \
  --body "Production release"

# After PR approval and merge, Cloudflare Pages builds automatically.
# Monitor build:
npx wrangler pages deployment list --project-name phenom-backend-prod

Roll back to a previous deployment

# List recent deployments
npx wrangler pages deployment list --project-name phenom-backend-prod

# In the Cloudflare dashboard: Pages > phenom-backend-prod > Deployments
# Select the target deployment > Rollback to this deployment

Purge Cloudflare cache after deployment

curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"purge_everything":true}'

Verify it is working

curl -si https://nest.thephenom.app/ | grep -E "^HTTP|^cf-ray"
# Expected: HTTP/2 200, cf-ray header present

curl -sf https://nest.thephenom.app/ | grep -i "phenom\|nest\|<title"
# Expected: HTML with Phenom/NEST branding in page title or body

Common failure modes

Related

• Dev NEST runbook
• API runbook
• RDS prod runbook
• SES mail runbook