code-style

Code style, TypeScript, and naming

When to use: Biome formatting, import style, strict TypeScript, naming (including React file names), or generated files. For where domain code lives, see architecture-boundaries.

Code style (Biome)

Biome config (biome.json) is the source of truth:

• Indentation: 2 spaces
• Max line width: 120
• Strings: double quotes
• Semicolons: as needed
• Ignore generated/output paths: dist/**, coverage/**, .turbo/**, node_modules/**, **/*.gen.ts, **/models.dev.json
• Prefer package-local formatting: pnpm --filter @app/api format

Imports

• Prefer static imports; avoid dynamic import patterns unless justified
• Use import type { ... } for type-only imports
• Keep imports explicit and grep-friendly
• Preserve clear grouping/order (external, internal alias, then relative)
• Avoid wildcard exports/imports when explicit named exports are practical
• Avoid barrel files (index.ts re-exporting from the same directory); import from the specific module
• Use .ts/.tsx extensions in relative imports (not .js). The codebase uses TypeScript source extensions for module resolution

TypeScript

Base config: tsconfig.base.json. Typechecking runs under tsgo (TypeScript 7 beta, via @typescript/native-preview) — use tsgo -p tsconfig.json --noEmit in typecheck scripts, never tsc.

• strict: true is enabled; keep code strict-clean
• Module system: NodeNext + ESM ("type": "module" in packages/apps)
• For new domain data contracts, define the canonical shared shape as a Zod schema first when runtime validation is required, then infer TypeScript types from that schema or from Drizzle schemas where appropriate.
• Treat schemas in src/entities/<entity>.ts as the canonical domain contract. Schemas and types elsewhere in the same domain or at app/platform boundaries should derive from or reuse those entity shapes whenever practical instead of restating identical fields.
• Canonical entity schemas should treat system-managed fields such as id, createdAt, and updatedAt as core entity fields. Do not split an entity into a business payload plus an appended "persistence" wrapper unless there is a truly distinct boundary/input DTO that needs that separation.
• Enum-like contracts should use literal-string unions or as const objects, not TypeScript enums.
• Use shared domain schemas to validate data crossing from app/platform boundaries into domain use-cases.
• If a boundary schema must differ materially from the entity shape, reuse domain constants, field schemas, and literal unions before introducing duplicated inline limits or sentinel values.
• Configurable thresholds, weights, debounce windows, sentinel values, and similar tunables should live in named constants inside the owning domain package rather than as scattered inline literals.
• Types and schemas that exist only as the inputs of one use-case should stay in that use-case file unless several use-cases truly share the same contract.
• Prefer explicit domain types/interfaces over loose objects
• Methods/functions with more than one argument should default to a single named-arguments object rather than positional arguments
• Use readonly fields for immutable domain data shapes
• Avoid any; use unknown + narrowing
• Avoid unnecessary type assertions (as { ... }); prefer relying on inferred types from libraries
• Validate boundary inputs early (API input, queue payloads, external IO)