| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 2 | 0% |
| Commands | 0 | 0 | 3 | 0% |
| Section tags | 1 | 0 | 1 | 50% |
What each file covers
Sections
0 shared · 1 only in A · 2 only in B- − ClickHouse Conventions
- + API Service
- + API Service Conventions
Commands
0 shared · 0 only in A · 3 only in B- + pnpm start:api:dev
- + npm run lint:openapi
- + npm run migration -- ./migrations/<path>.ts
Section tags
1 shared · 0 only in A · 1 only in B- + api
- code-style
Line diff
novuhq/novu · .cursor/rules/clickhouse.mdc
@@ −1 @@
1---
2description: Rules for working with ClickHouse analytics and trace logging
3globs:
4 - "**/analytic-logs/**"
5 - "**/clickhouse-migrations/**"
6alwaysApply: false
7---
8
9### ClickHouse Conventions
10
11**Service layer**
12- Use `ClickHouseService` for single queries/inserts and `ClickHouseBatchService` for high-throughput writes.
13- Both are registered as custom providers (`clickHouseService`, `clickHouseBatchService`) in each app's `shared.module.ts`.
14- Never instantiate ClickHouse clients directly — always inject the providers.
15
16**Repositories**
17- All ClickHouse repositories extend `LogRepository` in `libs/application-generic/src/services/analytic-logs/`.
18- Each repository has a corresponding schema file defining the table columns and types.
19- Always include `_environmentId` and `_organizationId` in queries for tenant isolation (same pattern as MongoDB DAL).
20
21**Migrations**
22- ClickHouse migrations are numbered `.sql` files in `apps/api/migrations/clickhouse-migrations/`.
23- Run locally with `cd apps/api && pnpm run clickhouse:migrate:local`.
24- New migrations must be additive — never alter or drop columns that existing queries depend on. Use temp tables and exchange patterns for schema refactors (see migration 4/5 for the established pattern).
25
26**Feature flags**
27- Gate new ClickHouse-dependent behavior behind a feature flag (see `packages/shared/src/types/feature-flags.ts` for existing flags like `IS_CLICKHOUSE_BATCHING_ENABLED`).
28
novuhq/novu · .cursor/rules/api.mdc
@@ +1 @@
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
@@ −1 +1 @@
11 ---
2−description: Rules for working with ClickHouse analytics and trace logging
3−globs:
4− - "**/analytic-logs/**"
5− - "**/clickhouse-migrations/**"
2+description: Rules for working in the API service (NestJS backend)
3+globs: apps/api/**/*
64 alwaysApply: false
75 ---
86
9−### ClickHouse Conventions
7+## API Service
108
11−**Service layer**
12−- Use `ClickHouseService` for single queries/inserts and `ClickHouseBatchService` for high-throughput writes.
13−- Both are registered as custom providers (`clickHouseService`, `clickHouseBatchService`) in each app's `shared.module.ts`.
14−- Never instantiate ClickHouse clients directly — always inject the providers.
9+**Stack:** NestJS + Express · MongoDB (via `libs/dal`) · Redis + Bull · ClickHouse (analytics/traces) · Clerk or Better Auth · `@nestjs/swagger`
1510
16−**Repositories**
17−- All ClickHouse repositories extend `LogRepository` in `libs/application-generic/src/services/analytic-logs/`.
18−- Each repository has a corresponding schema file defining the table columns and types.
19−- Always include `_environmentId` and `_organizationId` in queries for tenant isolation (same pattern as MongoDB DAL).
11+**Run:** `pnpm start:api:dev` — port 3000, OpenAPI at `http://localhost:3000/openapi`
2012
13+**Tests/lint:** see testing.mdc
14+
15+**Key directories:**
16+```
17+apps/api/src/app/ # Route controllers and modules
18+apps/api/src/ee/ # Enterprise-only features
19+apps/api/migrations/ # MongoDB migrations
20+apps/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+
2147 **Migrations**
22−- ClickHouse migrations are numbered `.sql` files in `apps/api/migrations/clickhouse-migrations/`.
23−- Run locally with `cd apps/api && pnpm run clickhouse:migrate:local`.
24−- New migrations must be additive — never alter or drop columns that existing queries depend on. Use temp tables and exchange patterns for schema refactors (see migration 4/5 for the established pattern).
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.
2551
26−**Feature flags**
27−- Gate new ClickHouse-dependent behavior behind a feature flag (see `packages/shared/src/types/feature-flags.ts` for existing flags like `IS_CLICKHOUSE_BATCHING_ENABLED`).
52+**Canonical example:** @apps/api/src/app/tenant/tenant.controller.ts
2853
