Conventions

TypeScript, formatting, import order, component design, and dependency rules enforced across the Aurea monorepo.

TypeScript

• Strict mode is on in every package ("strict": true via @repo/typescript-config/base.json).
• any is forbidden. Use unknown and narrow, or reach for a proper generic.
• All configs extend @repo/typescript-config — base.json, nextjs.json, or react-library.json.
• tsc --noEmit (or next typegen && tsc --noEmit for Next.js apps) is a required CI step.

Formatting — Prettier

All files are formatted by Prettier with these settings (.prettierrc.js):

module.exports = {
  semi: false,
  singleQuote: true,
  trailingComma: 'es5',
  tabWidth: 2,
  printWidth: 100,
  endOfLine: 'auto',
}

Formatting is enforced in CI (bun run format:check) and applied automatically by lint-staged on every commit via Husky.

Import ordering

Imports are sorted in three groups, separated by blank lines:

1. Node built-ins (node:fs, node:path, …)
2. External packages (npm — alphabetical within group)
3. Internal / workspace paths (@/*, @repo/*, relative ./)

Example:

import { readFileSync } from 'node:fs'

import { Injectable } from '@nestjs/common'
import { z } from 'zod'

import { CasesService } from '@/modules/cases/cases.service'
import { toMcpContent } from './helpers'

The ESLint import/order rule (via @repo/eslint-config/base) enforces this automatically.

Component design — atomic design

@repo/ui follows a strict atomic design hierarchy:

Apps consume components via the @repo/ui workspace package — never by copying files.

API auth & tenancy

• Auth-by-default. Every GraphQL query/mutation and the /mcp endpoint require a verified Clerk bearer token (ClerkAuthGuard). Agency-only operations add @Roles('agency_member') + RolesGuard. The guard memoizes the local users row on the request (req.dbUser) - one indexed query, no Clerk API round-trip.
• Tenancy scoping is server-side. Services build their Drizzle where with scopeByRole(dbUser, { clientField }): agency members see all rows, clients only their own. The SPA never filters by role.
• Subscriptions use graphql-ws on the same /graphql path; the socket authenticates via connectionParams.Authorization at connect time and is closed 4403 otherwise.
• Enums follow the three-sided pattern: canonical const array in @repo/shared/constants, compile-checked pgEnum tuple in the Drizzle schema, and a const-object GraphQL enum. The API imports @repo/shared types only (import type) - its swc/node runtime cannot load the package's raw .ts sources.

File storage (S3-presigned)

• Metadata in Postgres, bytes in S3-compatible storage. Confidential client files (Document Center) never touch the public Payload CMS and are never proxied through the API process.
• Authorize-before-presign. The API is the single authorization point: it role/ownership checks the caller, then mints a short-lived (~5 min) presigned URL (S3Service); the browser PUTs/GETs the bytes straight to the bucket. Object keys are server-generated (clients/<clientId>/<documentId>/<sanitized-name>) and never exposed via GraphQL.
• S3 is the source of truth for uploads. confirmUpload verifies the landed object via HeadObject (size/mime) instead of trusting client-reported values; violating objects are deleted and the row never flips to uploaded.

Commit messages

Commits follow Conventional Commits (feat:, fix:, chore:, docs:, etc.) enforced by commitlint + Husky.

Dependency direction

Turborepo's dependsOn config mirrors this graph so that build order is always correct.