# Proposal

## Why

The CMMS API already has authentication and a substantial MySQL domain schema, but response shapes and error handling are not consistent. Preserve the existing layered architecture and folder layout while strengthening these contracts. Establish a core contract before Inventory and Maintenance endpoints multiply, so the frontend can handle data and failures predictably.

## What Changes

- Extend the existing routes -> controllers -> services -> Prisma architecture using Express 5, TypeScript, Prisma 7.2, and MySQL. Keep the existing folder names and locations, including config/prisma.ts.
- **BREAKING**: Standardize JSON responses under `/api/v1`, including authentication, with success/error envelopes, request IDs, safe error codes, and field errors; move semantic validation failures from 400 to 422.
- Define collection pagination, serialization, English machine identifiers, and Indonesian content and user-facing messages.
- Centralize error normalization, unmatched-route handling, request-correlated logging, and safe database error translation.
- Clarify responsibilities within the existing routes, controllers, services, validators, middlewares, config, and interfaces folders. Keep explicit DTO mapping in services and define Inventory/Maintenance ownership and transaction boundaries through service contracts.
- Coordinate the API contract migration with shared DTOs and the frontend auth consumer; preserve cookie authentication behavior and bodyless logout.

## Capabilities

### New Capabilities

- `api-response-contract`: JSON envelopes, status semantics, pagination, language, serialization, and client compatibility.
- `api-error-handling`: Centralized safe failure responses, request correlation, and contextual error translation.
- `api-module-boundaries`: Feature ownership, dependency direction, explicit DTO boundaries, and cross-module transaction rules.

### Modified Capabilities

None. The project has no existing durable OpenSpec capabilities.

## Impact

Affected areas include `src/app.ts`, current routes/controllers/services/middleware, `src/config/swagger.ts`, API tests and source documentation. Companion changes are required in `packages/shared` and `apps/app/src/services/auth.service.ts`; these are outside this API workspace's current write boundary and must be delivered from an appropriately scoped workspace before release.

No folder restructuring, feature-module directories, relocation of existing auth/Prisma files, database migration, new runtime dependency, Inventory/Maintenance CRUD implementation, scheduler, new authentication mechanism, or microservice deployment is included. Domain transaction requirements establish rules for future feature changes; this baseline does not claim those features are implemented. Planning artifacts become durable core specs through the later OpenSpec sync/archive lifecycle.