api-conventions

name	api-conventions
description	The conventions apps/api holds itself to — no explanatory comments, no classes, errors as values, the closed verb set, one unit per file and the suffix that names a file's role. Use when writing or reviewing anything under apps/api/src.

The conventions in apps/api

CLAUDE.md is the law and docs/backend-architecture.md is the reasoning. This is the pass to run over a diff before calling it done. Nothing here is asserted by a test — test/architecture.test.ts polices the boundaries between layers and contexts, and the rest is read.

Comments

• No explanatory comment survives. A comment is a bug report against a name: rename the thing or extract a function until the line reads on its own.
• No section banners, no English restatement of the code, no // TODO markers.
• Two exceptions, and only these: a JSDoc line on a published type when it changes what a caller passes, and a reference to an external contract that cannot be inferred — an RFC number, a vendor quirk, why a workaround exists.
• Prefer encoding the reason in a name. negativeCacheTtlSeconds needs no comment about RFC 2308; soaMinimum would.

Tool directives (biome-ignore, @ts-expect-error) are not comments in this sense.

Types and control flow

• Data is plain readonly types. No classes anywhere; nothing is newed except adapters.
• Outcomes are tagged unions, so illegal states cannot be constructed. A nullable field travelling next to a boolean flag is a union wearing a disguise.
• Errors are values. domain/ and application/ never throw; they return Result<T, E> with a tagged E.
• Map a union with an exhaustive switch closed by unreachable(value) from shared/result.ts, so a new variant breaks the build.
• No any, no non-null !, no barrel files. Biome fails the build on these.

Names

The verbs are a closed set:

Kind	Verbs
Query	get<Thing>, list<Things>, findOrCreate<Thing>
Command	create cancel archive delete run stop revoke prove expire notify
Event	<Entity><Verb>ed, derived from the command that caused it

An act that wants a verb outside the set is usually two acts. Widening the set is a decision; reaching for apply, request, announce, handle or process is not.

One name, in four places: the file, the type, the function and the module property carry the same word. That a function closes over its dependencies is the pattern, not the noun, so no create*/make* factory prefix appears in application/. create in a name means creating something.

One file, one unit

One use case per file, one query per file, one schedule per file. Its own input, deps and error types travel with it; nothing else does. A type invented to cover several use cases at once — because they share a signature rather than a meaning — is the smell this removes.

The suffix says the role

Folder	Suffix
domain/	none
application/	.use-case.ts · .query.ts · .schedule.ts
api/	.routes.ts · .response.ts · .errors.ts
infra/	.repository.ts · .service.ts
root	.module.ts · .app.ts · .config.ts · .contract.ts

A file that fits none of them is usually in the wrong folder.

A reaction to an event is an ordinary use case with a business name, wired in one line in src/app.ts. A .policy.ts is earned only by a reaction carrying a real condition.

The wire

• Every route declares a response schema per status, and a detail: { tags, summary, description }. Regenerate with bun run docs:emit.
• Every code passed to errorResponse() has a ## <code> heading in apps/docs/errors.mdx. test/docs.test.ts checks it.
• Never break an Elysia method chain — Eden Treaty's types on the front end depend on it.

Before calling it done

cd apps/api && bun test && bun run typecheck && bun run lint