---
name: api-conventions
description: Service structure conventions for this codebase: routing, layering, and where code lives. Use whenever writing or modifying a service's server entry, route definitions, handlers, or adapters. Loads inline so it shapes structure as code is written.
---

# Service Architecture Conventions

Every service is three layers, one direction: `server.ts` → `handlers/` → `adapters/`. Apply while writing, not after.

## Versioning

- All routes live under `/api/v1/`. New endpoints are versioned from the first line. No unversioned routes "for now."

## server.ts is thin

- `server.ts` defines routes and delegates. Nothing else.
- No business logic in `server.ts` or in a route definition. A route wires the request to a handler and returns its result.

## handlers/ hold the logic

- Business logic lives in `handlers/`, one file per domain.
- A handler owns its domain's rules and orchestration. It calls adapters for anything external. It does not reach outside the process itself.

## adapters/ wrap everything external

- Database, external APIs, queues, anything outside the process goes through an adapter in `adapters/`. Handlers never touch them directly.
- **The database adapter uses StrictDB when it's installed, otherwise the native driver. Never Mongoose.** A handler that imports a driver or calls an external API inline is wrong, that belongs in an adapter. The data adapter is the one place driver code lives, which is also where the `mongodb-rules` apply.

## Service (package) separation

- A service owns its domain and is reached through its interface. A package does not reach into another package's internals or its data. Call the owning service.
- Code two services both need is hoisted to a shared layer, never imported sideways from a sibling.

The test: routes in `server.ts` read request-in, handler-call, response-out. Logic sits in `handlers/`. Anything that leaves the process goes through `adapters/`, and the data adapter uses StrictDB if installed, the native driver otherwise.