Add a Backend Endpoint

Follow the owning path rather than placing behavior in a route or server assembly file.

shared/domain type
→ validator
→ repository
→ service/helper
→ controller
→ route
→ OpenAPI
→ tests

1. Define the Contract

Use readable concrete types. Persisted JSON variants must be named bounded types or discriminated unions. Parse unknown at the boundary and keep production code free of any.

2. Validate Input

Put params, query, body, and environment schemas in validators. Reuse shared validation primitives and readable issue formatting. Validation errors should use the shared response envelope.

3. Add Persistence

Repositories own database access. Keep standalone CRUDL functions and a small organization-scoped factory. Use transactions for transitions that must commit together. Add cursor pagination and semantic tie-breakers for lists.

4. Compose Lifecycle Behavior

Services or helpers own cross-record transitions, policy, wakeups, and post-commit behavior. Keep application modules for dependency wiring and startup only.

5. Add the Controller and Route

• One named handler per operation.
• Thin controller factories.
• Routes bind middleware and handlers only.
• Scope authentication to the URL prefix it owns.
• Preserve valid W3C trace context and request-ID compatibility.

Add a route-level test proving protected-router fallthrough does not challenge unrelated public routes.

6. Add OpenAPI

Create or update the resource module under apps/backend/src/documentation with:

• stable operationId;
• plain summary and meaningful description;
• tags;
• path, query, and header parameters;
• typed request body;
• realistic examples;
• response and error descriptions; and
• security requirements.

The backend /docs/spec.json, backend Scalar explorer, and the tracked docs base snapshot all derive from createOpenApiDocument(). The snapshot is a generated projection guarded by a drift check, not a second schema.

7. Check Agent Control-plane Impact

If an agent must invoke the transition, update oblivectl, its skill reference, and the internal service-authenticated API contract in the same change.

8. Verify

bun test
bun run --cwd apps/backend typecheck
bun run docs:openapi:sync
bun run docs:openapi:check
bun run --cwd sites --filter @oblive/site-docs api:generate
bun run --cwd sites --filter @oblive/site-docs build

Smoke-check /health, /docs/spec.json, /docs, and the generated API section.