Scrum4Me/docs/adr/0004-status-enum-mapping.md

ADR-0004: DB enums UPPER_SNAKE, API enums lowercase, mapped exclusively via lib/task-status.ts

Status

accepted

Context

Prisma generates TypeScript types from PostgreSQL enum values verbatim. Our DB enums use UPPER_SNAKE_CASE (e.g. TO_DO, IN_PROGRESS, DONE) because that is the PostgreSQL convention and it keeps Prisma-generated code readable. However, REST API consumers — including Claude Code via MCP and frontend fetch calls — expect lowercase, underscore-separated values (todo, in_progress, done). Without a single conversion boundary, ad-hoc .toLowerCase() calls scattered across route handlers and actions introduce silent mapping bugs when enum values change.

Decision

• The database retains UPPER_SNAKE_CASE enum values. Prisma schema is the source of truth.
• The REST API (route handlers) and MCP server always expose and accept lowercase enum strings.
• All conversion happens exclusively in lib/task-status.ts via named mapper functions. No .toLowerCase(), .toUpperCase(), or inline string mapping anywhere else.

Consequences

Positive

• A single file to audit when enum values change.
• TypeScript types catch missing branches in mapper exhaustive checks.
• API contract is stable and grep-friendly.

Negative

• Every developer (and AI agent) must know to use the mappers rather than string coercion. Violations compile fine but break the API contract at runtime.
• Mitigated by an ESLint rule that flags direct .toLowerCase() on known enum types (pending implementation).