Conventions

The rules of the road for working in this codebase. Several are non-obvious and exist to avoid real build breakages.

TypeScript & config

tsconfig extends uses relative paths, not package names — TypeScript doesn’t resolve package exports for tsconfig extends:

{ "extends": "../../packages/config/tsconfig/nextjs.json" }  // ✅
{ "extends": "@playlogiq/config/tsconfig/nextjs.json" }      // ❌

nextjs.json disables declaration output (declaration: false). Next.js apps don’t emit declarations; enabling it causes TS2742 when workspace packages export source directly. base.json keeps declaration: true for non-Next packages (e.g. sdk).
Supabase SSR cookie typing uses // @ts-ignore (the @supabase/ssr CookieSerializeOptions is incompatible with Next’s ResponseCookie). Keep the @ts-ignore — do not replace it with as any.

Migrations are sequential NNN_description.sql, idempotent where practical, and must be added to supabase/tests/run.sh.
Regenerate packages/db/src/types.ts after schema changes (supabase gen types). Some query files cast via (client as any) until types are regenerated — remove the casts once types exist.
Verify schema completeness after applying a batch: compare expected objects (every CREATE TABLE / CREATE [OR REPLACE] FUNCTION) against pg_tables / pg_proc. A migration was historically skipped in prod once — don’t assume a batch fully applied.

Three locales — en / it / es — with structurally identical dictionaries (packages/i18n/src/dictionaries/*.ts). The Dictionary type is typeof en, so it/es must mirror every key or typecheck fails.
Code and comments are in English; user-facing strings go through i18n.

apps/web/app/(dashboard)/ is a route group — pages render at /, /players, etc., not /dashboard/*. Post-login redirects point to /.

The public API enforces auth → rate-limit → validation → scoped writes.
Sensitive settings (API keys, webhooks, integrations, brands) are Tier 2 (super_admin) and gated in both RLS and the app layer.
Never disable TLS verification or weaken RLS to work around a problem.

Significant technical decisions get an ADR in docs/ADR/. See Decision records.