Fast-Forward Mode: Full SDD Cycle in One Command

# Proposal: Add health check endpoint

## Metadata
- **Change:** add-health-check
- **Ticket:** N/A
- **Date:** 2026-04-15

## Context

The API has a single root endpoint. Monitoring and orchestration tools (load
balancers, Kubernetes, uptime checks) need a dedicated health endpoint to
determine if the service is running and ready to serve traffic.

## Problem

There is no way to programmatically check if the API is healthy. The root
endpoint (`/`) returns `{ "status": "ok" }` but it is semantically a
general-purpose response, not a health signal. Monitoring tools need a
conventional `/health` endpoint.

## Scope

**In scope:**
- `GET /health` endpoint returning service status
- Response includes uptime

**Out of scope:**
- Dependency checks (database, external services)
- Authentication
- Metrics or Prometheus format

## Proposed Solution

Add a `GET /health` route that returns `200 OK` with a JSON body containing
`status` and `uptime` fields. Implement as a separate route handler file
following the project conventions.

## Alternatives Discarded

| Alternative | Reason discarded |
|-------------|-----------------|
| Reuse `GET /` as health check | Mixes concerns — root should describe the API, not its health |
| Return plain text `OK` | Inconsistent with JSON-only API convention |

## Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Endpoint exposes internal info | Low | Low | Only return uptime, no version or env details |

## Impact

- **Files affected:** 2 (1 new route handler, 1 modified index.js)
- **Domains:** api
- **Tests:** 1 new test file for the health endpoint

## Dependencies

- None

## Acceptance Criteria

- [ ] `GET /health` returns `200` with `{ "status": "healthy", "uptime": <number> }`
- [ ] Other endpoints continue working unchanged
- [ ] Test covers happy path

# Spec: API — Add health check endpoint

## Metadata
- **Domain:** api
- **Change:** add-health-check
- **Date:** 2026-04-15
- **Status:** approved

## Expected Behavior

### Main Case

**Given** the API server is running
**When** a client sends `GET /health`
**Then** the server responds with:
- Status: `200 OK`
- Content-Type: `application/json`
- Body: `{ "status": "healthy", "uptime": <seconds since start> }`

### Alternative Cases

| Scenario | Condition | Result |
|----------|-----------|--------|
| Server just started | Uptime < 1 second | Returns `uptime: 0` (integer, floored) |

### Errors

| Error | When | Response |
|-------|------|----------|
| Method not allowed | `POST /health` | `405` with `{ "error": "method not allowed" }` |

## Business Rules

- **BR-01:** The health endpoint MUST NOT require authentication
- **BR-02:** Uptime MUST be an integer (seconds, floored)

## Decisions Made

| Decision | Alternative discarded | Reason |
|---------|-----------------------|--------|
| Return integer seconds for uptime | Milliseconds or ISO duration | Simplicity — seconds are universally understood |
| Include only status + uptime | Add version, commit hash | Minimize info exposure for a demo project |

# Design: Add health check endpoint

## Metadata
- **Change:** add-health-check
- **Date:** 2026-04-15
- **Status:** approved

## Technical Summary

Add a health check route handler in a new file under `src/routes/`. Modify
the main server to import and dispatch to this handler when the path matches
`/health`. Record the server start time at boot to calculate uptime.

## Architecture

    Request GET /health
      → index.js (routing)
        → routes/health.js (handler)
          → Response { status: "healthy", uptime: N }

## Files to Create

| File | Type | Purpose |
|------|------|---------|
| `src/routes/health.js` | Route handler | Returns health status + uptime |
| `test/health.test.js` | Test | Validates health endpoint behavior |

## Files to Modify

| File | Change | Reason |
|------|--------|--------|
| `src/index.js` | Import health handler, add route dispatch, record start time | Wire up the new endpoint |

## Scope

- **Total files:** 3
- **Result:** Ideal

## Design Decisions

| Decision | Alternative | Reason |
|---------|------------|--------|
| Separate route file | Inline in index.js | Follows convention: one file per domain in routes/ |
| Pass startTime as parameter | Global variable | Explicit dependency, testable |

## Implementation Notes

- `startTime` is captured once at server boot via `Date.now()`
- Health handler receives `startTime` and computes `Math.floor((Date.now() - startTime) / 1000)`
- The `src/routes/` directory does not exist yet — create it

# Tasks: Add health check endpoint

## Metadata
- **Change:** add-health-check
- **Ticket:** N/A
- **Branch:** add-health-check
- **Date:** 2026-04-15

## Implementation Tasks

- [x] **T01** Create `src/routes/health.js` — health check route handler
  - Commit: `[add-health-check] Add health route handler`

- [x] **T02** Modify `src/index.js` — import health handler, add route dispatch, record start time
  - Commit: `[add-health-check] Wire up health endpoint in server`
  - Depends on: T01

- [x] **T03** Create `test/health.test.js` — test health endpoint
  - Commit: `[add-health-check] Add health endpoint tests`
  - Depends on: T01, T02

## Quality Gate

- [x] **QG** Run tests and quality checks
  - `node --test`