API Routes As Adapters

Summary

API routes adapt HTTP requests into service calls. They should validate input, attach context, serialize output, and leave business behavior in services.

Problem

Business rules inside route handlers are hard to reuse from jobs, workers, and future interfaces. They also scatter data access and authorization decisions.

Principle

Route handlers are transport adapters. Services expose the capability.

Platform Shape

Marketing, POA, precon, and payroll APIs are organized as route packages over domain services. POA's route map explicitly documents this boundary: new behavior belongs in services, not inside handler-local logic.

Source Evidence

• app/api/marketing
• app/api/poa
• app/api/precon
• app/api/payroll

Related Reading

• docs/engineering/concepts/services-expose-capabilities.md
• docs/engineering/reference/auth-and-module-access.md