03 - User Journey (Health Module)

• 1. Machine journey - LB health probe (implemented today)
• 2. DevOps incident journey (human)
• 3. Support engineer journey (screen (proposed))
• 4. School admin journey (forward-looking)
• 5. Key moments of truth

End-to-end journeys around the health surface. Machine journey reflects the implemented backend exactly; human journeys rely on the (proposed) App Health screen (05/06). Sources: health.controller.ts:14-37, response-envelope.interceptor.ts:47-60, http-exception.filter.ts:73-81.

1. Machine journey - LB health probe (implemented today)

LB ── GET /api/v1/health (30s interval) ──► API
     API runs 4 checks in parallel (health.controller.ts:31-36):
       mongodb   Terminus pingCheck      (health.controller.ts:32)
       redis     PING → 'PONG'           (redis-health.indicator.ts:12-23)
       storage   provider healthCheck()  (storage-health.indicator.ts:16-26)
       bullmq    getJobCounts on 4 queues(bullmq-health.indicator.ts:19-37)
     │
     ├─ all up ──► 200 {success, message:'OK', data:{status:'ok', info:{…},
     │                error:{}, details:{…}}, timestamp, requestId}
     │                (response-envelope.interceptor.ts:47-60)
     └─ any down ─► 503 {success:false, message, error:{code:'INTERNAL_SERVER_ERROR'},
                        timestamp, requestId}
                        (http-exception.filter.ts:56-58, 73-81)
     LB: 200 → route traffic; 503 → drain instance

• One instance, one request, four dependency answers. No tenant context, no auth - the probe is public (health.controller.ts:15).
• Partial failure: status: 'error', info still lists the healthy deps, error.<key>.status === 'down' names the culprit (health.controller.spec.ts:21-36).

2. DevOps incident journey (human)

1. Detect - probe alert, or user-reported slowness.
2. Triage - curl /api/v1/health; read data.status.
   • ok → API and its four dependencies are reachable; problem is upstream (network, DNS, tenant-specific), not the platform.
   • error → read data.error for the down key (mongodb | redis | storage | bullmq).
3. Diagnose - down key names the console to open:
   • redis → check the ping detail was lost on failure (redis-health.indicator.ts:17-22 throws without payload).
   • bullmq → pending-job counts were the last healthy signal (bullmq-health.indicator.ts:30); a growing pendingJobs smells like a stalled worker before a hard down.
4. Resolve - fix the dependency; next probe flips the instance back to 200; LB re-routes automatically.
5. Confirm - re-curl; info lists all four up (health.controller.spec.ts:23-28).

3. Support engineer journey (screen (proposed))

1. Open App Health screen; auto-poll runs (13).
2. Cards: API (implicit 200), DB, Redis, Queues, Storage (05 S1). A red card names the culprit - no curl needed.
3. Tap Retry for an immediate re-check instead of waiting for the next poll tick (06 S1).
4. Screenshot the card states + last-check time into the ticket.

4. School admin journey (forward-looking)

1. Parent reports "app is down" → admin opens App Health.
2. Green cards → "working here; issue may be device/network" → generic status communication.
3. Red cards → confirm platform issue → relay to support with the card screenshot.
4. Admin cannot fix anything from this screen - read-only (proposed).

5. Key moments of truth