Backend Patterns
tereo is one service (packages/tereo, port 4001) with one database — a
Postgres schema per area (auth, files, webhooks, audit, plus core for the outbox, keys and
registry). Areas share one Express app, one db object and one env schema; nothing calls another area
over HTTP.
Package Layout
packages/tereo/
├── prisma/schema.prisma # The one schema; client generated to prisma/generated/client
├── openapi/{auth,files,webhooks,audit}/
└── src/
├── index.ts / app.ts / worker.ts # Entry, Express app, background work (ROLE=all|api|worker)
├── preload.ts # First import of every entry point (loads .env)
├── env.ts # The one Zod env schema — `import env from "./env.js"`
├── definitions/ # Core's declaration: permissions, roles, buckets, event types
├── middleware/ # auth.ts, organizationId.ts, rateLimit.ts, accessLog.ts, …
├── routes/ # Mirrors the URL (see below)
│ └── v1/{area}/…/{resource}/
│ ├── index.ts # The one router: imports and route wiring only
│ ├── controllers.ts # Handlers
│ ├── schemas.ts # Zod schemas
│ ├── middleware.ts # Route-local middleware (guards, multer wrappers), if any
│ └── {item}/ # The `/:id` sub-router (organization/, webhook/, …)
├── utils/
│ ├── db/{table}.ts # Prisma calls, one file per table group; db/index.ts = `db`
│ ├── outbox.ts # logAuditTx, emitTx, computeChanges, the outbox reaper
│ └── cursor.ts # applyCursorToWhere, buildCursorPageResponse
├── jobs/ # BullMQ queues and workers
└── tests/ # Mirrors src/ (see the `test` skill and tests/README.md)
URL → folder: routes/index.ts is the root of the tree. It mounts /health (routes/health/),
core's own API under /v1 (routes/v1/, composed in routes/v1/index.ts with each area's
body-size limit: v1/account/, v1/admin/, v1/setup/, v1/files/, v1/webhooks/, v1/audit/), the protocol endpoints at the root (routes/oauth/, routes/well-known/), and
last the admin UI, which takes every browser path outside the reserved prefixes in utils/ui.ts.
A new API route goes under routes/v1/.
Route Layout and Registration Order
Where a route's files go, what each file holds, :param folders and the order routes register in
are in the routes skill (enforced by tests/conventions/routeLayout.unit.test.ts). REQUIRED: load it before
adding or moving a route.
Validation
- Always Zod.
validateBody(schema, req), validateParams(schema, req), validateQuery(schema, req)
from utils/validateReq.ts — they throw ValidationError (400 invalid_request).
- Ids are UUIDv7: param schemas use
z.guid() — any 8-4-4-4-12 hex id, as Postgres takes it (z.uuid() refuses ids outside RFC 9562's variants).
- List endpoints are cursor-paginated:
createCursorQuerySchema({ filters, sortFields, defaultSort })
from utils/parseQueryString.ts, then applyCursorToWhere(query, baseWhere) and
buildCursorPageResponse(result, query) from utils/cursor.ts (cursors are HMAC-signed with
CURSOR_SIGNING_KEY_V{n}). There is no offset pagination.
- Extra query flags (e.g.
includeArchived) get a second schema; parse booleans with
z.enum(["true","false"]).transform(v => v === "true"), never z.coerce.boolean().
Error Handling
- Throw the classes from
utils/errors.ts — never res.status().json() for errors.
ValidationError 400 · BadRequestError(code, message) 400 · UnauthorizedError(message, code?)
401 · ForbiddenError 403 · NotFoundError 404 · ConflictError(message, code?) 409 ·
PreconditionFailedError 412 · PayloadTooLargeError 413 · UnprocessableEntityError(code, message)
422 · TooManyRequestsError(retryAfter, message?) 429 · ServiceUnavailableError 503 ·
OAuth2Error(error, description, status) for OAuth/OIDC.
- Archive state:
ArchivedError 409 resource_archived (changing an archived row),
AlreadyArchivedError 409 already_archived, NotArchivedError 409 not_archived. A 404 means
only that the row is not there or hidden. See docs/errors.md for the shared codes.
- Where nothing can be thrown (a stream's
error event after the controller returned), use
sendError(res, err) — same body and headers as the handler.
- Auth-specific:
InvalidTokenError for bad/expired/revoked bearer tokens.
- Prisma constraint errors:
mapUniqueViolation(fn, msg, code) and
rethrowRestrictedAsConflict(err, msg) (utils/prismaErrors.ts) turn them into 409s with a
specific message. Unmapped unique and foreign-key violations, in any of the shapes the driver
adapter produces, reach errorHandler as a generic 409 conflict.
errorHandler (last in app.ts, after a catch-all NotFoundError) answers in RFC 6749 form:
{ "error": "code", "error_description": "message" }.
Auth and Permissions
- Tokens are verified in-process by
requireAuth (middleware/auth.ts) — signature, stored
access_tokens row, revocation, session, then permissions from the user's roles. No introspection
hop and no test-mode shortcut.
requireAuth goes on the area router (routes/v1/admin/index.ts, routes/v1/webhooks/index.ts,
routes/v1/audit/index.ts), followed by rateLimitGeneral. Areas with anonymous reads build their
own with createRequireAuth({ publicRoutes }) (routes/v1/files/index.ts); the controller still gates.
requirePermission(name) goes on each route. Names come from PERMISSIONS in
definitions/permissions.ts (files, webhooks, audit — PERMISSIONS.WEBHOOKS.WRITE,
PERMISSIONS.buckets.read) or are literal for auth's admin routes ("organizations.write").
- Hierarchy (
hasPermission): read (1) < write (2) < archive (3) < delete (4) < admin (5); a
x.admin covers its whole subtree, and the bare admin permission covers everything.
- In controllers,
validateUser(req) returns the AuthContext
(userId, email, permissions, organizationId, oauthClientId, …).
- Finer checks are in code, not middleware:
requireOrgRole("member" | "admin" | "owner", req, orgId)
(utils/orgRoleAuth.ts) for org routes; validateBucketAccess / validateBucketManagement
(utils/bucketAccess.ts) for the per-bucket grants files layer on top of permissions.
Organization Context
- The tenant comes from the token (
req.auth.organizationId), not a header.
- Webhooks:
resolveWebhookOrganizationId sets req.organizationId (a webhooks.admin caller may
override with X-Organization-ID); audit: resolveAuditOrganizationId. Controllers read it with
validateOrganizationId(req) (middleware/organizationId.ts).
- Org-owned rows: load by id, then compare
row.organizationId to the caller's and throw
ForbiddenError("Resource does not belong to this client"). Lists put organizationId in the base
where passed to applyCursorToWhere.
Database Layer
- Prisma calls live in
utils/db/{table}.ts, aggregated by utils/db/index.ts into one default
export: import db from "../../utils/db/index.js" → db.organizations.get(id).
- Controllers call
db.*, not prisma (a few read-only admin aggregations are the exception).
- Every write function takes an optional transaction:
(…, tx?: Prisma.TransactionClient) with
const db = tx ?? prisma;. Controllers open db.$transaction(async (tx) => …).
get throws NotFoundError; findById / getBy… return null for the caller to decide.
getPaginated({ take, orderBy, where }) fetches take + 1 and returns { data, hasMore }.
- Raw SQL names the schema on every table —
"files"."objects", "core"."outbox". There is no
public schema.
Prisma Conventions
- One
prisma/schema.prisma; every model and enum carries @@schema("auth" | "files" | "webhooks" | "audit" | "core"). Import the client and types from prisma/generated/client/index.js.
id String @id @default(uuid(7)) @db.Uuid; foreign keys @db.Uuid (Bucket alone keeps an
autoincrement Int id).
- camelCase fields,
@map("snake_case") columns, @@map("table_name") tables.
createdAt @default(now()), updatedAt @updatedAt, both mapped.
- Actors: every "who" column (
createdBy, userId, writerUserId, …) is a FK into User with
onDelete: Restrict. Clients act as their service-account user; core acts as SYSTEM_USER_ID.
- Archive, don't delete: archivable rows have
archivedAt DateTime? @map("archived_at") +
@@index([archivedAt]); mutations on archived rows are blocked with guardArchived /
guardArchivedById. Users and organizations are deactivated (isActive) or archived, never deleted.
deletedAt exists only on Bucket, Object and ObjectVersion, where deletion is a storage
lifecycle (cleanup jobs, delete markers) — filter deletedAt: null there.
- Tenant-owned models have
organizationId with a Restrict relation to Organization.
Migrations
npx prisma migrate dev --create-only --name <name>, review, then npx prisma migrate deploy.
- Append raw SQL only for what Prisma can't express: range partitioning, partial/opclass indexes,
CHECK constraints.
- On the partitioned tables (
audit_log_entries, webhook_deliveries) Prisma emits a PK-reset
statement Postgres rejects — delete only that statement.
src/scripts/seed.ts is idempotent and runs after every migrate.
Declared, Not Seeded
Core's permissions, system roles, buckets and event types are code in src/definitions/
(CORE_DECLARATION), registered by registerCore() on every start. Removing one there retires it
after REGISTRY_RETIREMENT_GRACE_HOURS. Admins never create permissions or edit system roles. App
services declare theirs in their provisioning documents (see docs/provisioning.md, docs/registry.md).
Audit Entries + Webhook Events (Transactional)
Both happen inside the mutation's transaction, from utils/outbox.ts:
const updated = await db.$transaction(async (tx) => {
const next = await db.organizations.update(id, body, tx);
await logAuditTx(tx, {
auth,
organizationId: next.id,
action: "UPDATE",
entityType: "Organization",
entityId: next.id,
entityName: next.name,
changes: computeChanges(existing, next),
});
await emitTx(tx, {
organizationId: getDefaultOrganizationId(),
eventType: "auth.organization.updated",
entityType: "Organization",
entityId: next.id,
data: formatOrganization(next) as Record<string, unknown>,
});
return next;
});
logAuditTx inserts into audit.audit_log_entries directly (same database) — userId is the
caller, writerUserId is SYSTEM_USER_ID, request id and IP come from AsyncLocalStorage.
emitTx writes a core.outbox row; the worker's reaper fans it out to subscribed endpoints after
commit, using the row id as the idempotency key. Don't pass one.
emitTx throws on an event type not in definitions/eventTypes.ts — add it there first.
Format {area}.{resource}.{action}: auth.organization.created, file-service.bucket.updated,
core.service.declared.
- Platform events (auth, core) are emitted under
getDefaultOrganizationId(); tenant data
(buckets, objects) under the owning organization.
action: CREATE | UPDATE | DELETE | MERGE | ARCHIVE | RESTORE.
For the reaper, dead-letters and the app-service side (core.outbox in @tereo-io/sdk), invoke
the outbox skill.
App Wiring
app.ts order: trust proxy → createRequestIdMiddleware() → helmet() → bucket CORS
preflights → apiCors (credentialed CORS on the API only) → authRequestLog → routes (routes/index.ts) → catch-all
NotFoundError → errorHandler.
routes/index.ts: /.well-known, /health (DB + Redis probe, 503 degraded on failure),
/oauth, /v1 (routes/v1/index.ts: /files, /webhooks, /audit, /account,
/admin, /setup, each with its body limit — smallBodyParsers from
middleware/bodyParsers.ts for the auth ones), then the admin UI.
index.ts start order: loadKeys() (before anything signs, verifies or decrypts) → Redis →
default organization → assertSystemUser() → registerCore() → worker (if ROLE runs it) →
app imported after Redis is up.
- Background work goes in
src/jobs/: queues from createQueue (with RETRY_POLICIES /
REMOVAL_POLICIES) in utils/bullmq.ts, BullMQ Workers in the job modules, started from
worker.ts.
Environment Variables
- One schema:
src/env.ts; default export env. Add the variable there with a Zod type and default.
- Never read
process.env elsewhere. src/preload.ts must be the first import of every entry point.
- Booleans with the
bool("false") helper; numbers with z.coerce.number().
- Keys (
JWT_*, TOTP_ENCRYPTION_KEY, *_SIGNING_KEY_V1) are optional — loadKeys() fills them
from core.secrets, generating them on first start.
OpenAPI Spec
One spec for the whole service under packages/tereo/openapi/ (openapi.yaml,
paths/<area>/, components/ with components/<area>/, generated bundled-openapi.yaml). Update
it with every route change — invoke the openapi skill.
Adding a Resource
src/routes/v1/{area}/…/{resource}/ with index.ts, schemas.ts, controllers.ts, plus
{item}/ for the /:id routes (see the routes skill)
- Model in
prisma/schema.prisma (right @@schema), migration via --create-only
src/utils/db/{table}.ts, added to utils/db/index.ts
- Mount the router in its parent
index.ts (respect registration order)
- Permissions in
definitions/permissions.ts (PERMISSION_CATALOG + PERMISSIONS), and in
definitions/roles.ts if a system role should hold them
- Event types in
definitions/eventTypes.ts; logAuditTx + emitTx in every mutation
- OpenAPI paths and schemas; tests mirroring the route under
src/tests/routes/ (see the test skill)
DO
- Validate every input with
validateBody/Params/Query; throw error classes for every failure
- Keep Prisma in
utils/db/; pass tx through for writes inside a transaction
logAuditTx + emitTx inside the mutation's transaction
requirePermission() on every route; scope tenant data by the caller's organization
- Archive (
archivedAt) instead of deleting; keep actor columns as FKs into auth.users
.js on every relative import; imports sorted longest-first (npm run sort-imports)
- Log with Pino, object first:
logger.info({ orgId }, "msg")
DON'T
- Never
res.status(400).json(...) — throw
- Never emit or audit outside the transaction, or fire-and-forget after commit
- Never seed permissions, roles or event types — declare them in
definitions/
- Never put
requireAuth on individual routes — it belongs to the area router
- Never read
process.env outside env.ts, or sign/verify before loadKeys()
- Never write raw SQL without the schema prefix
- Never use
any — unknown and narrow
- Never add external API integrations (they belong in dianemo-plugins)
Additional Resources
- Code examples (routers, schemas, controllers, db layer, raw SQL, definitions, Prisma model, env):
examples.md
- Related skills:
routes, outbox, openapi, test
- Per-area notes:
packages/tereo/docs/{auth,files,webhooks,audit,registry,telemetry}.md
- Conventions:
CLAUDE.md, docs/code-style.md
1---2name: backend-63description: Backend patterns for tereo — the one Express/Prisma service (auth, files, webhooks, audit). Use when creating or changing routes, controllers, Zod validation, error handling, db functions, Prisma models or migrations, permissions/roles/event types in definitions/, audit entries, or webhook events.4paths:5 - packages/tereo/src/**6 - packages/tereo/prisma/**7 - packages/tereo/openapi/**8metadata:9 source: https://skillmd.com/skills/majiayu000/backend-610---1112# Backend Patterns1314tereo is **one service** (`packages/tereo`, port 4001) with **one database** — a15Postgres schema per area (`auth`, `files`, `webhooks`, `audit`, plus `core` for the outbox, keys and16registry). Areas share one Express app, one `db` object and one env schema; nothing calls another area17over HTTP.1819## Package Layout2021```22packages/tereo/23├── prisma/schema.prisma # The one schema; client generated to prisma/generated/client24├── openapi/{auth,files,webhooks,audit}/25└── src/26 ├── index.ts / app.ts / worker.ts # Entry, Express app, background work (ROLE=all|api|worker)27 ├── preload.ts # First import of every entry point (loads .env)28 ├── env.ts # The one Zod env schema — `import env from "./env.js"`29 ├── definitions/ # Core's declaration: permissions, roles, buckets, event types30 ├── middleware/ # auth.ts, organizationId.ts, rateLimit.ts, accessLog.ts, …31 ├── routes/ # Mirrors the URL (see below)32 │ └── v1/{area}/…/{resource}/33 │ ├── index.ts # The one router: imports and route wiring only34 │ ├── controllers.ts # Handlers35 │ ├── schemas.ts # Zod schemas36 │ ├── middleware.ts # Route-local middleware (guards, multer wrappers), if any37 │ └── {item}/ # The `/:id` sub-router (organization/, webhook/, …)38 ├── utils/39 │ ├── db/{table}.ts # Prisma calls, one file per table group; db/index.ts = `db`40 │ ├── outbox.ts # logAuditTx, emitTx, computeChanges, the outbox reaper41 │ └── cursor.ts # applyCursorToWhere, buildCursorPageResponse42 ├── jobs/ # BullMQ queues and workers43 └── tests/ # Mirrors src/ (see the `test` skill and tests/README.md)44```4546URL → folder: `routes/index.ts` is the root of the tree. It mounts `/health` (`routes/health/`),47core's own API under `/v1` (`routes/v1/`, composed in `routes/v1/index.ts` with each area's48body-size limit: `v1/account/`, `v1/admin/`, `v1/setup/`, `v1/files/`, `v1/webhooks/`, `v1/audit/`), the protocol endpoints at the root (`routes/oauth/`, `routes/well-known/`), and49last the admin UI, which takes every browser path outside the reserved prefixes in `utils/ui.ts`.50A new API route goes under `routes/v1/`.5152## Route Layout and Registration Order5354Where a route's files go, what each file holds, `:param` folders and the order routes register in55are in the `routes` skill (enforced by `tests/conventions/routeLayout.unit.test.ts`). **REQUIRED:** load it before56adding or moving a route.5758## Validation5960- Always Zod. `validateBody(schema, req)`, `validateParams(schema, req)`, `validateQuery(schema, req)`61 from `utils/validateReq.ts` — they throw `ValidationError` (400 `invalid_request`).62- Ids are UUIDv7: param schemas use `z.guid()` — any 8-4-4-4-12 hex id, as Postgres takes it (`z.uuid()` refuses ids outside RFC 9562's variants).63- **List endpoints are cursor-paginated**: `createCursorQuerySchema({ filters, sortFields, defaultSort })`64 from `utils/parseQueryString.ts`, then `applyCursorToWhere(query, baseWhere)` and65 `buildCursorPageResponse(result, query)` from `utils/cursor.ts` (cursors are HMAC-signed with66 `CURSOR_SIGNING_KEY_V{n}`). There is no offset pagination.67- Extra query flags (e.g. `includeArchived`) get a second schema; parse booleans with68 `z.enum(["true","false"]).transform(v => v === "true")`, never `z.coerce.boolean()`.6970## Error Handling7172- Throw the classes from `utils/errors.ts` — never `res.status().json()` for errors.73- `ValidationError` 400 · `BadRequestError(code, message)` 400 · `UnauthorizedError(message, code?)`74 401 · `ForbiddenError` 403 · `NotFoundError` 404 · `ConflictError(message, code?)` 409 ·75 `PreconditionFailedError` 412 · `PayloadTooLargeError` 413 · `UnprocessableEntityError(code, message)`76 422 · `TooManyRequestsError(retryAfter, message?)` 429 · `ServiceUnavailableError` 503 ·77 `OAuth2Error(error, description, status)` for OAuth/OIDC.78- Archive state: `ArchivedError` 409 `resource_archived` (changing an archived row),79 `AlreadyArchivedError` 409 `already_archived`, `NotArchivedError` 409 `not_archived`. A 404 means80 only that the row is not there or hidden. See `docs/errors.md` for the shared codes.81- Where nothing can be thrown (a stream's `error` event after the controller returned), use82 `sendError(res, err)` — same body and headers as the handler.83- Auth-specific: `InvalidTokenError` for bad/expired/revoked bearer tokens.84- Prisma constraint errors: `mapUniqueViolation(fn, msg, code)` and85 `rethrowRestrictedAsConflict(err, msg)` (`utils/prismaErrors.ts`) turn them into 409s with a86 specific message. Unmapped unique and foreign-key violations, in any of the shapes the driver87 adapter produces, reach `errorHandler` as a generic 409 `conflict`.88- `errorHandler` (last in `app.ts`, after a catch-all `NotFoundError`) answers in RFC 6749 form:89 `{ "error": "code", "error_description": "message" }`.9091## Auth and Permissions9293- Tokens are verified **in-process** by `requireAuth` (`middleware/auth.ts`) — signature, stored94 `access_tokens` row, revocation, session, then permissions from the user's roles. No introspection95 hop and **no test-mode shortcut**.96- `requireAuth` goes on the **area router** (`routes/v1/admin/index.ts`, `routes/v1/webhooks/index.ts`,97 `routes/v1/audit/index.ts`), followed by `rateLimitGeneral`. Areas with anonymous reads build their98 own with `createRequireAuth({ publicRoutes })` (`routes/v1/files/index.ts`); the controller still gates.99- `requirePermission(name)` goes on **each route**. Names come from `PERMISSIONS` in100 `definitions/permissions.ts` (files, webhooks, audit — `PERMISSIONS.WEBHOOKS.WRITE`,101 `PERMISSIONS.buckets.read`) or are literal for auth's admin routes (`"organizations.write"`).102- Hierarchy (`hasPermission`): `read (1) < write (2) < archive (3) < delete (4) < admin (5)`; a103 `x.admin` covers its whole subtree, and the bare `admin` permission covers everything.104- In controllers, `validateUser(req)` returns the `AuthContext`105 (`userId`, `email`, `permissions`, `organizationId`, `oauthClientId`, …).106- Finer checks are in code, not middleware: `requireOrgRole("member" | "admin" | "owner", req, orgId)`107 (`utils/orgRoleAuth.ts`) for org routes; `validateBucketAccess` / `validateBucketManagement`108 (`utils/bucketAccess.ts`) for the per-bucket grants files layer on top of permissions.109110## Organization Context111112- The tenant comes from the **token** (`req.auth.organizationId`), not a header.113- Webhooks: `resolveWebhookOrganizationId` sets `req.organizationId` (a `webhooks.admin` caller may114 override with `X-Organization-ID`); audit: `resolveAuditOrganizationId`. Controllers read it with115 `validateOrganizationId(req)` (`middleware/organizationId.ts`).116- Org-owned rows: load by id, then compare `row.organizationId` to the caller's and throw117 `ForbiddenError("Resource does not belong to this client")`. Lists put `organizationId` in the base118 `where` passed to `applyCursorToWhere`.119120## Database Layer121122- Prisma calls live in `utils/db/{table}.ts`, aggregated by `utils/db/index.ts` into one default123 export: `import db from "../../utils/db/index.js"` → `db.organizations.get(id)`.124- Controllers call `db.*`, not `prisma` (a few read-only admin aggregations are the exception).125- Every write function takes an optional transaction: `(…, tx?: Prisma.TransactionClient)` with126 `const db = tx ?? prisma;`. Controllers open `db.$transaction(async (tx) => …)`.127- `get` throws `NotFoundError`; `findById` / `getBy…` return `null` for the caller to decide.128- `getPaginated({ take, orderBy, where })` fetches `take + 1` and returns `{ data, hasMore }`.129- **Raw SQL** names the schema on every table — `"files"."objects"`, `"core"."outbox"`. There is no130 `public` schema.131132## Prisma Conventions133134- One `prisma/schema.prisma`; every model and enum carries `@@schema("auth" | "files" | "webhooks" |135 "audit" | "core")`. Import the client and types from `prisma/generated/client/index.js`.136- `id String @id @default(uuid(7)) @db.Uuid`; foreign keys `@db.Uuid` (`Bucket` alone keeps an137 autoincrement `Int` id).138- camelCase fields, `@map("snake_case")` columns, `@@map("table_name")` tables.139- `createdAt @default(now())`, `updatedAt @updatedAt`, both mapped.140- **Actors**: every "who" column (`createdBy`, `userId`, `writerUserId`, …) is a FK into `User` with141 `onDelete: Restrict`. Clients act as their service-account user; core acts as `SYSTEM_USER_ID`.142- **Archive, don't delete**: archivable rows have `archivedAt DateTime? @map("archived_at")` +143 `@@index([archivedAt])`; mutations on archived rows are blocked with `guardArchived` /144 `guardArchivedById`. Users and organizations are deactivated (`isActive`) or archived, never deleted.145 `deletedAt` exists only on `Bucket`, `Object` and `ObjectVersion`, where deletion is a storage146 lifecycle (cleanup jobs, delete markers) — filter `deletedAt: null` there.147- Tenant-owned models have `organizationId` with a `Restrict` relation to `Organization`.148149## Migrations150151- `npx prisma migrate dev --create-only --name <name>`, review, then `npx prisma migrate deploy`.152- Append raw SQL only for what Prisma can't express: range partitioning, partial/opclass indexes,153 CHECK constraints.154- On the partitioned tables (`audit_log_entries`, `webhook_deliveries`) Prisma emits a PK-reset155 statement Postgres rejects — delete only that statement.156- `src/scripts/seed.ts` is idempotent and runs after every migrate.157158## Declared, Not Seeded159160Core's permissions, system roles, buckets and event types are **code** in `src/definitions/`161(`CORE_DECLARATION`), registered by `registerCore()` on every start. Removing one there retires it162after `REGISTRY_RETIREMENT_GRACE_HOURS`. Admins never create permissions or edit system roles. App163services declare theirs in their provisioning documents (see `docs/provisioning.md`, `docs/registry.md`).164165## Audit Entries + Webhook Events (Transactional)166167Both happen **inside the mutation's transaction**, from `utils/outbox.ts`:168169```typescript170const updated = await db.$transaction(async (tx) => {171 const next = await db.organizations.update(id, body, tx);172 await logAuditTx(tx, {173 auth,174 organizationId: next.id,175 action: "UPDATE",176 entityType: "Organization",177 entityId: next.id,178 entityName: next.name,179 changes: computeChanges(existing, next),180 });181 await emitTx(tx, {182 organizationId: getDefaultOrganizationId(),183 eventType: "auth.organization.updated",184 entityType: "Organization",185 entityId: next.id,186 data: formatOrganization(next) as Record<string, unknown>,187 });188 return next;189});190```191192- `logAuditTx` inserts into `audit.audit_log_entries` directly (same database) — `userId` is the193 caller, `writerUserId` is `SYSTEM_USER_ID`, request id and IP come from AsyncLocalStorage.194- `emitTx` writes a `core.outbox` row; the worker's reaper fans it out to subscribed endpoints after195 commit, using the row id as the idempotency key. Don't pass one.196- `emitTx` throws on an event type not in `definitions/eventTypes.ts` — add it there first.197 Format `{area}.{resource}.{action}`: `auth.organization.created`, `file-service.bucket.updated`,198 `core.service.declared`.199- Platform events (auth, core) are emitted under `getDefaultOrganizationId()`; tenant data200 (buckets, objects) under the owning organization.201- `action`: `CREATE | UPDATE | DELETE | MERGE | ARCHIVE | RESTORE`.202203For the reaper, dead-letters and the app-service side (`core.outbox` in @tereo-io/sdk), invoke204the `outbox` skill.205206## App Wiring207208- `app.ts` order: `trust proxy` → `createRequestIdMiddleware()` → `helmet()` → bucket CORS209 preflights → `apiCors` (credentialed CORS on the API only) → `authRequestLog` → `routes` (`routes/index.ts`) → catch-all210 `NotFoundError` → `errorHandler`.211- `routes/index.ts`: `/.well-known`, `/health` (DB + Redis probe, 503 `degraded` on failure),212 `/oauth`, `/v1` (`routes/v1/index.ts`: `/files`, `/webhooks`, `/audit`, `/account`,213 `/admin`, `/setup`, each with its body limit — `smallBodyParsers` from214 `middleware/bodyParsers.ts` for the auth ones), then the admin UI.215- `index.ts` start order: `loadKeys()` (before anything signs, verifies or decrypts) → Redis →216 default organization → `assertSystemUser()` → `registerCore()` → worker (if `ROLE` runs it) →217 `app` imported after Redis is up.218- Background work goes in `src/jobs/`: queues from `createQueue` (with `RETRY_POLICIES` /219 `REMOVAL_POLICIES`) in `utils/bullmq.ts`, BullMQ `Worker`s in the job modules, started from220 `worker.ts`.221222## Environment Variables223224- One schema: `src/env.ts`; default export `env`. Add the variable there with a Zod type and default.225- Never read `process.env` elsewhere. `src/preload.ts` must be the first import of every entry point.226- Booleans with the `bool("false")` helper; numbers with `z.coerce.number()`.227- Keys (`JWT_*`, `TOTP_ENCRYPTION_KEY`, `*_SIGNING_KEY_V1`) are optional — `loadKeys()` fills them228 from `core.secrets`, generating them on first start.229230## OpenAPI Spec231232One spec for the whole service under `packages/tereo/openapi/` (`openapi.yaml`,233`paths/<area>/`, `components/` with `components/<area>/`, generated `bundled-openapi.yaml`). Update234it with every route change — invoke the `openapi` skill.235236## Adding a Resource2372381. `src/routes/v1/{area}/…/{resource}/` with `index.ts`, `schemas.ts`, `controllers.ts`, plus239 `{item}/` for the `/:id` routes (see the `routes` skill)2402. Model in `prisma/schema.prisma` (right `@@schema`), migration via `--create-only`2413. `src/utils/db/{table}.ts`, added to `utils/db/index.ts`2424. Mount the router in its parent `index.ts` (respect registration order)2435. Permissions in `definitions/permissions.ts` (`PERMISSION_CATALOG` + `PERMISSIONS`), and in244 `definitions/roles.ts` if a system role should hold them2456. Event types in `definitions/eventTypes.ts`; `logAuditTx` + `emitTx` in every mutation2467. OpenAPI paths and schemas; tests mirroring the route under `src/tests/routes/` (see the `test` skill)247248## DO249250- Validate every input with `validateBody/Params/Query`; throw error classes for every failure251- Keep Prisma in `utils/db/`; pass `tx` through for writes inside a transaction252- `logAuditTx` + `emitTx` inside the mutation's transaction253- `requirePermission()` on every route; scope tenant data by the caller's organization254- Archive (`archivedAt`) instead of deleting; keep actor columns as FKs into `auth.users`255- `.js` on every relative import; imports sorted longest-first (`npm run sort-imports`)256- Log with Pino, object first: `logger.info({ orgId }, "msg")`257258## DON'T259260- Never `res.status(400).json(...)` — throw261- Never emit or audit outside the transaction, or fire-and-forget after commit262- Never seed permissions, roles or event types — declare them in `definitions/`263- Never put `requireAuth` on individual routes — it belongs to the area router264- Never read `process.env` outside `env.ts`, or sign/verify before `loadKeys()`265- Never write raw SQL without the schema prefix266- Never use `any` — `unknown` and narrow267- Never add external API integrations (they belong in [dianemo-plugins](https://github.com/dianemo/dianemo-plugins))268269## Additional Resources270271- Code examples (routers, schemas, controllers, db layer, raw SQL, definitions, Prisma model, env):272 [examples.md](examples.md)273- Related skills: `routes`, `outbox`, `openapi`, `test`274- Per-area notes: `packages/tereo/docs/{auth,files,webhooks,audit,registry,telemetry}.md`275- Conventions: `CLAUDE.md`, `docs/code-style.md`