Skip to content

Conventions ​

What code review checks. Most of these exist because the spec says so; the reason is next to each.

Access ​

  • All access rules live in packages/api/src/access.ts. Routers ask it for scope; they never compare roles ad hoc.
  • A record outside the actor's scope is NOT_FOUND, never FORBIDDEN, so ids cannot be probed. FORBIDDEN means the route itself is off limits for the role.
  • Declare who may call a procedure with roleProcedure("owner", ...). A bare protectedProcedure means "any signed-in role"; use it deliberately.
  • The UI hides what the server would refuse; it is never the only check.
  • Public pages are token-only, rate-limited per IP, and show only what that page needs.

Domain code ​

  • Shared vocabulary (roles, statuses, event types, settings, versioning helpers) lives in @shootgrow/domain and has no I/O. Both server and web import it.
  • A status or role is added in the domain package first, with its Zod schema; DB columns store text, not DB enums.
  • Money is integer pence. Time is epoch milliseconds in UTC. Never use floating-point currency.

Settings, not constants ​

A number or switch the owner might change (days before a shoot, auto-approve behaviour, limits) is a setting in the registry, not a literal in a handler. Prices and contract text are versioned templates. See Versioning.

Integrations ​

Email, payments and research are interfaces with a "not configured" implementation (packages/api/src/integrations). Feature code imports the interface, never a vendor SDK. An unconfigured integration reports not_configured; it never fabricates a result.

UI ​

  • Components come from @shootgrow/ui/components/motion/* (beUI). Do not add shadcn or Radix.
  • Colours come from tokens (bg-background, text-muted-foreground, border-border, text-primary). No raw hex in app code.
  • Every list has an empty state and an error state ("Nothing due" vs "Couldn't load"). A failed source must never look like an empty one.
  • A button that starts background work says what it will do before it does it.
  • Spaces and navigation are driven by apps/web/src/lib/spaces.ts; do not hand-write sidebars.

Code style ​

  • Oxlint + Oxfmt (bun run check). No other formatter.
  • TypeScript strict, noUncheckedIndexedAccess on (off only inside packages/ui for vendored beUI code).
  • Prefer deleting dead code to commenting it out. When a change makes something obsolete, remove it in the same change.
  • New ideas that are not part of the change in hand go on roadmap.md.

Tests ​

Test behaviour a consumer could see break: versioning maths, scope rules, schedule generation, state transitions. Do not test wiring or that a constant equals itself. The domain package uses bun test; place tests next to the code as *.test.ts.

Internal documentation. Not for clients.