Skip to content

Code Standards ​

This page documents the non-negotiable code standards enforced across the PPP monorepo. Every rule here is wired into CI as a blocking gate, not a linting suggestion.

Type Safety ​

TypeScript strict mode is enabled repo-wide and enforced at two layers: the shared base config at packages/config-tsconfig/tsconfig.base.json sets strict: true, and every PPP-specific package (instances/ppp/, api/backend-ppp/, packages-shared/ppp/) re-asserts it in its own tsconfig.json.

No any types ​

The any type is prohibited across the PPP codebase. CI enforces this via the "PPP no-any type gate" (node .github/scripts/check-no-any.mjs) which runs ESLint @typescript-eslint/no-explicit-any across instances/ppp/, api/backend-ppp/, and packages-shared/ppp/.

  • Do not introduce the any type anywhere in PPP packages.
  • Do not use as any escape hatches.
  • Do not use // @ts-ignore to bypass typing issues.
  • Prefer explicit types, narrow unions, generic parameters, or well-typed helper utilities.
  • If a third-party library has missing or broken types, write a minimal local declaration file under instances/ppp/src/types/ or api/backend-ppp/src/types/ rather than disabling type checking.

Run pnpm lint:no-any from any PPP directory to check locally before pushing.

Logging Discipline ​

console.log, console.info, and console.debug are not allowed in production code. The rule is enforced by lint:no-console and runs in CI.

  • Backend (api/backend-ppp/, api/backend-core/): use baseLogger or ctx.logger. These pipe into the structured logging stack that feeds Azure Log Analytics.
  • Frontend (instances/ppp/): console.warn and console.error are allowed for error handling. console.log / console.info / console.debug are not. If you need a rare exception, document it inline:
    ts
    // eslint-disable-line no-console -- <justification> // no-console-ok
  • Test files and Storybook stories: no-console is a warning, not an error. You can use console.log freely during test development without breaking CI.

TODO and FIXME Comments ​

All TODO/FIXME comments must include a GitHub issue number. Bare placeholders fail lint.

ts
// TODO(#123): description of what needs to happen and why
// FIXME(#456): description of the known issue

Enforced by the unicorn/expiring-todo-comments ESLint rule across all PPP packages. If you're writing a TODO that doesn't have a tracking issue yet, create the issue first and then reference it.

Database Schema Changes ​

Drizzle schema changes in packages-shared/ppp/src/schema.ts require a migration in the same PR. CI enforces this via the migration-check job (check-migration-drift.sh).

Workflow for any schema change:

  1. Edit packages-shared/ppp/src/schema.ts
  2. From packages-shared/ppp/, run pnpm db:generate — this writes a new drizzle/NNNN_tag.sql file plus updates drizzle/meta/_journal.json
  3. Commit the generated SQL file and the updated journal in the same commit as the schema change
  4. Also create a sibling drizzle/NNNN_tag.validate.sql file that proves the migration's effect — CD runs scripts/migrate-with-validation.mjs to execute the validator post-migration and will fail the deploy if the DDL silently no-opped

Validator examples:

MigrationValidator
ADD COLUMN fooSELECT foo FROM <table> LIMIT 0;
CREATE TABLE fooSELECT 1 FROM information_schema.tables WHERE table_name = 'foo';
CREATE INDEX ix_fooSELECT 1 FROM pg_indexes WHERE indexname = 'ix_foo';
CREATE TRIGGER foo_trgSELECT 1 FROM pg_trigger WHERE tgname = 'foo_trg';

Missing migrations break every query on the affected table across all environments — see incident #4379.

Database Access ​

Use database views, not tables, for read access. The PPP database provides mb_user_view, mb_role, mb_task_view, and others specifically so backend code can read through a stable projection layer that survives column renames and soft-delete filters.

  • Use double quotes for case-sensitive column names in raw SQL: u."firstName", r."updatedAt".
  • Backend tests create isolated test data with unique IDs and clean up in afterAll — never test against ambient production data.

Code Style ​

  • TypeScript strict mode, no any (see above)
  • Prettier handles formatting — configuration lives at .prettierrc.json, enforced by the husky pre-commit hook via lint-staged
  • Comments start with 🤗 emoji in the PPP codebase (frontend and mobile) for visual consistency
  • Single-line if statements do not need brackets when the body is a single statement
  • Prefer clear, descriptive variable names over abbreviations

Enforcement Summary ​

RuleToolCI Gate
Strict TypeScripttsconfig.json + tsc --noEmitTier 1 (blocking)
No any@typescript-eslint/no-explicit-anyTier 1 (blocking)
No console.logeslint-plugin-no-consoleTier 1 (blocking)
TODO must reference issueunicorn/expiring-todo-commentsTier 1 (blocking)
Drizzle migration requiredcheck-migration-drift.shTier 1 (blocking)
Prettier formattingHusky + lint-stagedPre-commit hook

Every rule on this page is already enforced; this page is a reference for developers who want to know why CI is failing on them and what the canonical expectation is.

Internal documentation — org members only