From 7517c17b566c05605ae86457cd5e7dbdd911fdbe Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 7 Mar 2026 09:34:51 +0000 Subject: [PATCH] docs(backend): document /api/health endpoint behavior Co-authored-by: Tyler Dane --- docs/api-documentation.md | 41 ++++++++++++++++++++++++++++++++++++ docs/backend-request-flow.md | 22 ++++++++++++++++++- docs/env-and-dev-modes.md | 15 +++++++++++++ docs/feature-file-map.md | 1 + 4 files changed, 78 insertions(+), 1 deletion(-) diff --git a/docs/api-documentation.md b/docs/api-documentation.md index 6c20d8c56..82e6c6495 100644 --- a/docs/api-documentation.md +++ b/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 diff --git a/docs/backend-request-flow.md b/docs/backend-request-flow.md index 23891133c..2efdf3631 100644 --- a/docs/backend-request-flow.md +++ b/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: diff --git a/docs/env-and-dev-modes.md b/docs/env-and-dev-modes.md index d4e02a905..80663063f 100644 --- a/docs/env-and-dev-modes.md +++ b/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:/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 diff --git a/docs/feature-file-map.md b/docs/feature-file-map.md index b43aa1c50..31b6c780d 100644 --- a/docs/feature-file-map.md +++ b/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