Cursor rule

1---
2description: Rules for working in the API service (NestJS backend)
3globs: apps/api/**/*
4alwaysApply: false
5---
6 
7## API Service
8 
9**Stack:** NestJS + Express · MongoDB (via `libs/dal`) · Redis + Bull · ClickHouse (analytics/traces) · Clerk or Better Auth · `@nestjs/swagger`
10 
11**Run:** `pnpm start:api:dev` — port 3000, OpenAPI at `http://localhost:3000/openapi`
12 
13**Tests/lint:** see testing.mdc
14 
15**Key directories:**
16```
17apps/api/src/app/                          # Route controllers and modules
18apps/api/src/ee/                           # Enterprise-only features
19apps/api/migrations/                       # MongoDB migrations
20apps/api/migrations/clickhouse-migrations/ # ClickHouse schema migrations
21```
22 
23---
24 
25### API Service Conventions
26 
27**Controllers**
28- Every protected route must use `@RequireAuthentication()`.
29- Routes accessible via user API keys or the official SDK must also use `@ExternalApiAccessible`.
30- Routes accessible via Clerk OAuth (DCR) access tokens must also use `@OAuthAccessible`.
31- Controller method names follow: `getEntityName`, `listEntityName`, `createEntityName`, `updateEntityName`, `deleteEntityName`.
32- List endpoints must support pagination and use `@SdkUsePagination`.
33- Group SDK endpoints with `@SdkGroupName` using `.` as the subresource separator (e.g., `Subscribers.Notifications`).
34 
35**Use-cases (CQRS)**
36- Business logic lives in use-case classes, not controllers.
37- Use-cases receive a typed command/query and return a typed result via `execute(command)`.
38- Never put database queries directly in controllers.
39 
40**Database**
41- Always use `libs/dal` repositories for all queries; see dal-repository.mdc for enforcement rules.
42 
43**OpenAPI**
44- Every endpoint must have `@ApiOperation`, `@ApiResponse`, and `@ApiTags` decorators.
45- Validate with `npm run lint:openapi` (run with API started) before submitting a PR.
46 
47**Migrations**
48- Place migration scripts in `apps/api/migrations/<change-description>/<change-action>.ts`.
49- Run via `npm run migration -- ./migrations/<path>.ts`.
50- Never rename existing migration scripts — they are referenced in user-facing docs.
51 
52**Canonical example:** @apps/api/src/app/tenant/tenant.controller.ts
53