Skip to content

API conventions

Configuration, the error contract, mirrored contracts and authorisation.

On this page

ikazebot-server is NestJS 11 on Express. Modules are feature-shaped, not layer-shaped: agents/, knowledge/, credits/, inbox/. Each owns its controller, service, schema and tests.

Configuration: one reader of process.env

src/config/env.schema.ts is the only module that reads process.env. Every variable is declared there, with a comment naming the feature that owns it.

  • Validation reports every problem at once, so a bad deploy is diagnosed in one boot.
  • Cross-field rules live in validatedEnvSchema. Examples: production refuses :free models and the Resend test sender, and the API and web hosts must share AUTH_COOKIE_DOMAIN.
  • An undeclared variable fails in production; a declared but unused one fails boot for no reason. Keep the list exact.
  • The documented exceptions are drizzle.config.ts and the Jest bootstrap, which run outside Nest.

The error contract

Every error a client sees has one shape:

json
{ "statusCode": 409, "code": "SEAT_LIMIT_REACHED", "message": "…", "details": {}, "requestId": "…" }
  • Throw HttpException subclasses. Pass { code, message, details } when a client must branch on the case.
  • Clients switch on code, never on message. The message is human copy and may change; codes are stable API surface.
  • An unrecognised throwable never reaches a client with its own message. normalizeException replaces it, because that is how stack traces, connection strings and provider keys escape. Do not route around it.
  • requestId is on every error and every log line, so a bug report can be joined to a log.

Mirrored contracts

Every response shape is a Zod schema in src/shared/*, copied verbatim into ikazebot-web/src/lib/shared/*. The web app parses every response with it.

  1. 1Change server src/shared/x.schema.ts
  2. 2Copy byte-for-byte to web src/lib/shared/x.schema.ts
  3. 3Gate passes in both repos
  4. 4Ship together
  • A contract change is one feature, touching both repositories, in the same sitting.
  • Each mirrored file says so at the top: "Change both in the same feature. See CLAUDE.md §1."
  • Do not "improve" one copy. Anything that is not part of the wire contract does not belong in shared.

Routes

  • Declare static routes before parameterised ones: @Get('active') above @Get(':id'), or active is swallowed as an id.
  • Every list endpoint is paginated (cursor-based) from its first commit.
  • Everything is behind the session guard by default; @Public() opts a route out. The v2 API uses @Public() plus ApiKeyGuard.

Authorisation: CASL in one place

Roles (owner, admin, agent, member) live in shared/roles.ts, and what each may do lives in auth/ability.factory.ts. Adding a role or changing a permission is a change there and nowhere else. The API checks abilities on every request; the web app's role checks only decide what to render.

Platform admin is not a workspace role. It is a row in platform_admins, which the API can read but never write, so a workspace admin can never grant themselves platform access.

Ports and adapters

Anything we might swap sits behind an interface with one adapter:

PortAdapter today
MailResend
StorageS3-compatible (MinIO in development, Cloudflare R2 in production)
EmbeddingsOpenRouter
BillingManual bank transfer, approved by a platform admin

Outbound HTTP

Any URL a customer configures, such as a crawled site, a custom API action or a webhook, is fetched through the crawler's guarded dialler. It resolves the host, refuses private, loopback, link-local and cloud-metadata addresses, connects to the exact address it checked, re-checks every redirect, and caps time and size. Never call fetch on a customer URL directly.

Get started free — 50 credits a month