Skip to main content

LLM Guide — How to Contribute Code Safely

Purpose: A single page for humans and LLMs to follow when adding or changing code in this monorepo.

Pre‑read checklist​

  • Read the Engineering Handbook and all pages under engineering/* (stack, TS policy, testing, CI/CD, security, observability, ADRs).
  • If a deviation from the paved path is needed, draft an ADR per engineering/exceptions-and-adrs.

Where to put new code​

  • Apps (deployables) → apps/* (e.g., apps/web for Next.js, apps/functions for Firebase Functions)
  • Shared libraries → packages/*
  • Do not add new top‑level folders without an ADR.

Standard Next.js structure for features:

apps/web/src/
  app/                 # layouts, pages, route handlers
  features/
    <feature>/
      hooks/           # React Query hooks, side-effects
      services/        # fetchers/SDK wrappers
      components/      # feature-specific UI
      types.ts
  components/          # reusable UI (presentational)
  context/             # app-wide providers
  lib/                 # utilities (dates, firebase, stripe)
  state/               # Zustand stores & flags

Do and Don’t​

  • Do keep pages/route segments thin; put side-effects and network I/O in features/*/{hooks,services}.
  • Do validate env/config with Zod and read secrets from env; never hard‑code secrets.
  • Do add auth checks, error handling (RFC 7807 style on REST), and logging.
  • Don’t add new tooling/stacks without an ADR.
  • Don’t bypass Firestore Rules or suggest wildcard access.

Coding requirements​

  • TypeScript, strict mode, ESM‑first. Respect path aliases.
  • Frontend: Next.js App Router, prefer Server Components; Zustand for client state; Formik + Yup for forms.
  • Backend: Express‑style REST (/v1/...), plural resources, cursor pagination, RFC 7807 errors.

Testing​

  • Place tests under __tests__/ with *.test.ts.
  • Aim for ≥ 80% coverage. Prefer unit tests; use emulators for integrations where needed.

CI compatibility​

  • Ensure Node 20+ compatibility. Scripts to run successfully in CI: pnpm lint, pnpm typecheck, pnpm test, pnpm build.

When to write an ADR​

  • Introducing a new framework, datastore, CI system, or relaxing a guardrail.
  • Use the template in engineering/exceptions-and-adrs. Status lifecycle: proposed → accepted → deprecated → superseded.

PR checklist (Definition of Done)​

  • Lint + typecheck pass with no warnings
  • Tests pass with coverage ≥ threshold
  • Logs/errors present where relevant; feature flags used for incomplete work
  • Docs updated and linked to relevant engineering pages; request review from CODEOWNERS