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:freemodels and the Resend test sender, and the API and web hosts must shareAUTH_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.tsand the Jest bootstrap, which run outside Nest.
The error contract
Every error a client sees has one shape:
{ "statusCode": 409, "code": "SEAT_LIMIT_REACHED", "message": "…", "details": {}, "requestId": "…" }
- Throw
HttpExceptionsubclasses. Pass{ code, message, details }when a client must branch on the case. - Clients switch on
code, never onmessage. The message is human copy and may change; codes are stable API surface. - An unrecognised throwable never reaches a client with its own message.
normalizeExceptionreplaces it, because that is how stack traces, connection strings and provider keys escape. Do not route around it. requestIdis 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.
- 1Change server src/shared/x.schema.ts
- 2Copy byte-for-byte to web src/lib/shared/x.schema.ts
- 3Gate passes in both repos
- 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'), oractiveis 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()plusApiKeyGuard.
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:
| Port | Adapter today |
|---|---|
| Resend | |
| Storage | S3-compatible (MinIO in development, Cloudflare R2 in production) |
| Embeddings | OpenRouter |
| Billing | Manual 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.