Skip to main content

Engineering Handbook — Guardrails & Paved Paths

Purpose: Defines the guardrails (non‑negotiables) and paved paths (default choices) for how software is designed, written, tested, deployed, secured, and observed across our monorepo. Intended for humans and LLMs.

Scope: Applies to all repos inside the monorepo unless an ADR explicitly carves out an exception.

Quick Start​

  • Start here: pnpm i && pnpm run setup
  • Build and test everything: pnpm build && pnpm test
  • Run locally with emulators: pnpm dev
  • Deploy web (Vercel) / backend (Firebase Functions): via CI on merge to protected branches

Sections​

  • Repository & Workflow → engineering/repository-workflow
  • Stack & Styling → engineering/stack-and-styling
  • TypeScript Policy → engineering/typescript
  • Testing Strategy → engineering/testing
  • Linting, Formatting & Static Analysis → engineering/lint-format-static
  • CI/CD Policy → engineering/ci-cd
  • Environments & Feature Flags → engineering/environments-flags
  • API Conventions (REST) → engineering/api-conventions
  • Frontend Conventions (Next.js) → engineering/frontend-conventions
  • Secrets & Configuration → engineering/secrets-config
  • Observability → engineering/observability
  • Data, Storage & Async → engineering/data-storage-async
  • Security Guardrails → engineering/security-policy
  • Developer Experience → engineering/developer-experience
  • Exceptions & Decision Records → engineering/adrs
  • Appendices → engineering/appendices
note

For CI/CD runbooks and deployment procedures, see operations/ci-cd and operations/deployment.