docs(backend): document /api/health behavior and runbook

docs/api-documentation.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- [Health Routes](#health-routes)
 - [Calendar Routes](#calendar-routes)
 - [Auth Routes](#auth-routes)
 - [User Routes](#user-routes)
@@ -12,6 +13,41 @@
 
 ---
 
+## Health Routes
+
+**Source**: `packages/backend/src/health/health.routes.config.ts`, `packages/backend/src/health/controllers/health.controller.ts`
+
+### /api/health
+
+`GET /api/health` verifies MongoDB connectivity and returns a minimal status payload.
+
+Behavior:
+
+- no authentication middleware is applied
+- returns `200` when `mongoService.db.admin().ping()` succeeds
+- returns `500` when the database ping fails
+- always includes an ISO-8601 `timestamp`
+
+Success response:
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-03-07T12:34:56.789Z"
+}
+```
+
+Failure response:
+
+```json
+{
+  "status": "error",
+  "timestamp": "2026-03-07T12:34:56.789Z"
+}
+```
+
+---
+
 ## Calendar Routes
 
 **Source**: `packages/backend/src/calendar/calendar.routes.config.ts`
@@ -157,6 +193,10 @@ Most endpoints require authentication via Supertokens session management.
 4. Subsequent requests include session cookie
 5. Backend validates session with `verifySession()` middleware
 
+Authentication exceptions:
+
+- `GET /api/health` is intentionally unauthenticated for monitoring and load balancer probes
+
 ## Common Patterns
 
 ### Route Configuration
@@ -210,3 +250,4 @@ When this payload accompanies `401` or `410`, web clients should keep the sessio
 - `/api/calendars/*` - Calendar list and selection
 - `/api/sync/*` - Google Calendar synchronization
 - `/api/priority/*` - Task priority management
+- `/api/health` - service health and database reachability check

docs/backend-request-flow.md

@@ -15,7 +15,7 @@ Express startup does this:
 2. install request middleware
 3. install CORS and SuperTokens middleware
 4. install helmet, logging, and JSON parsing
-5. register route config classes
+5. register route config classes (including unauthenticated health check route)
 6. install the SuperTokens error handler after routes
 
 ## Route Config Pattern
@@ -43,6 +43,22 @@ The backend relies on middleware ordering for correct behavior:
 
 If a new route behaves strangely, verify it is registered inside `initExpressServer()` and uses the expected middleware stack.
 
+## Health Check Endpoint Pattern
+
+Files:
+
+- `packages/backend/src/health/health.routes.config.ts`
+- `packages/backend/src/health/controllers/health.controller.ts`
+
+`GET /api/health` is registered as a lightweight operational endpoint:
+
+- no `verifySession()` requirement
+- controller performs `mongoService.db.admin().ping()`
+- response contract is intentionally small: `{ status, timestamp }`
+- returns `200` (`status: "ok"`) on successful DB ping, `500` (`status: "error"`) on failure
+
+This route is suitable for uptime probes and quick backend triage, but it is not a deep dependency readiness check beyond database reachability.
+
 ## Response Pattern
 
 File:
@@ -97,6 +113,10 @@ Frequently used middleware:
 - `authMiddleware.verifyIsFromCompass`: trusted internal caller
 - `authMiddleware.verifyIsFromGoogle`: trusted Google notification source
 
+Intentional unauthenticated route:
+
+- `GET /api/health`: monitoring endpoint that checks DB connectivity
+
 ## Validation Placement
 
 Validation is spread across a few layers:

docs/env-and-dev-modes.md

@@ -99,6 +99,20 @@ Important variables:
 - Mongo persistence
 - websocket server behavior
 
+## Backend Health Probe
+
+When debugging backend startup or connectivity issues, use the health endpoint first:
+
+```bash
+curl -i http://localhost:<PORT>/api/health
+```
+
+Interpretation:
+
+- `200` with `{"status":"ok","timestamp":"..."}`: backend is running and can reach MongoDB
+- `500` with `{"status":"error","timestamp":"..."}`: backend is running but database connectivity failed
+- connection refused/timeouts: backend process is not listening yet, or the port/base URL is wrong
+
 ### Requires Google-related setup
 
 - real OAuth
@@ -139,3 +153,4 @@ This keeps cache writes inside the workspace (instead of relying on a user-level
 - web points at the wrong API base URL
 - session exists but user profile fetch fails
 - sync endpoints work but notification/watch setup fails due to incomplete Google/ngrok setup
+- backend starts but `/api/health` returns `500` because `MONGO_URI` or database reachability is broken

docs/feature-file-map.md

@@ -77,6 +77,7 @@ Use this document to find the first files to inspect for common Compass changes.
 - Backend env parsing: `packages/backend/src/common/constants/env.constants.ts`
 - Web env parsing: `packages/web/src/common/constants/env.constants.ts`
 - Express middleware order: `packages/backend/src/servers/express/express.server.ts`
+- Health endpoint route/controller/tests: `packages/backend/src/health/health.routes.config.ts`, `packages/backend/src/health/controllers/health.controller.ts`, `packages/backend/src/health/controllers/health.controller.test.ts`
 
 ## CLI / Maintenance