Cursor rule

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