Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

04 - Information Architecture (Health Module)

Where the health surface lives in the StudyLyon IA. Global conventions in 00-shared/05. The backend surface is a single public endpoint; the screen IA below is (proposed) for a future admin surface.

1. Backend IA (implemented)

/api/v1/health            GET  combined Terminus check (health.controller.ts:27-37)
                            ├─ mongodb   (health.controller.ts:32)
                            ├─ redis     (redis-health.indicator.ts:12-23)
                            ├─ storage   (storage-health.indicator.ts:16-26)
                            └─ bullmq    (bullmq-health.indicator.ts:19-37)
  • Root: /api global prefix, URI versioning, default version 1 (env.ts:14,16, main.ts:44-48); health also accepts /api/v2/health (@Version(['1','2']), health.controller.ts:28).
  • Global, not tenant-scoped: no tenantId, no tenant middleware context - a platform-wide concern. It does not appear in any tenant menu tree.
  • Planned siblings: /api/v1/health/live and /api/v1/health/ready (liveness/readiness split) exist only in docs/user-flows/END_TO_END_USER_FLOWS.md:738-740 - (planned), not routed.

2. Screen IA (proposed)

App Health lives in the admin/operations zone, sibling to Audit (audit.read surface) and Scheduler, not under any tenant feature tree:

Settings / Operations (admin)            (proposed placement)
└── App Health                            S1 - status dashboard
    ├── Service status cards              API / DB / Redis / Queues / Storage
    ├── Last-check time                   
    └── Retry (manual re-check)
NodeContentState source
API cardimplicit - the request itself succeededHTTP 200 of the call
DB carddata.info.mongodb.status (health.controller.ts:32)up/down
Redis carddata.info.redis.status + ping (redis-health.indicator.ts:16)up/down
Storage carddata.info.storage.status (storage-health.indicator.ts:19)up/down
Queues carddata.info.bullmq.status + pendingJobs (bullmq-health.indicator.ts:30)up/down

3. Information priorities

  1. Overall state - one glance: all green / one red.
  2. Culprit identification - which dependency, from data.error (health.controller.spec.ts:29-35).
  3. Freshness - last-check time (client-side timestamp of the 200/503).
  4. Detail - pendingJobs backlog on the Queues card; hidden by default.

4. Explicitly absent (keep it lean)

  • No per-tenant health hierarchy (non-goal, 01 §5).
  • No uptime history / incident timeline - (planned) at best, stateless endpoint today.
  • No write actions beyond Retry - no config, no thresholds, no toggles on the screen ((proposed) surface is read-only + retry).