Engineering Handbook

Purpose: This handbook defines the guardrails (non‑negotiables) and paved paths (default choices) for how software is designed, written, tested, deployed, secured, and observed across our monorepo. It is intended for humans and LLMs. If you are an LLM generating code for this org, follow the instructions in each section’s LLM Notes.

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 → Repository & Workflow
• Languages, Frameworks & Styling → Stack & Styling
• TypeScript Policy → TypeScript Policy
• Testing Strategy → Testing Strategy
• Linting, Formatting & Static Analysis → Quality Tooling
• CI/CD — GitHub Actions → CI/CD
• Environments, Deployments & Feature Flags → Environments & Flags
• API Conventions (REST) → API Conventions
• Frontend Conventions (Next.js) → Frontend Conventions
• Secrets & Configuration → Secrets & Configuration
• Observability → Observability
• Data, Storage & Async → Data, Storage & Async
• Security → Security
• Developer Experience → Developer Experience
• Exceptions & Decision Records → Exceptions & ADRs
• Appendices → Appendices

Final Note: These guardrails optimize for speed and coherence. If you need to diverge, propose an ADR. Prefer automation over policy—if it matters, enforce in code or CI.