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 the Soku monorepo. It is intended for humans and LLMs alike. If you are an LLM generating code for this project, follow the instructions in each section's LLM Notes.
Scope: Applies to all packages inside the monorepo unless an ADR explicitly carves out an exception.
Quick Start
pnpm install # Install all dependencies
pnpm build # Build all apps and packages
pnpm test # Run all tests with coverage
pnpm dev # Start web + functions in parallel
pnpm check # Run lint + typecheck + test (full validation)
- Deploy web — Automatically via Vercel on merge to protected branches
- Deploy functions —
pnpm deploy:functionsor via CI on merge
Technology Summary
| Layer | Technology | Details |
|---|---|---|
| Frontend | Next.js 16, React 19, TypeScript | App Router, RSC support |
| State | Redux Toolkit, React Query v5 | Slices for forms, RQ for server data |
| Styling | Tailwind CSS 3.4, Radix UI | Utility-first with shadcn/ui components |
| Backend | Express 5, Node.js 22 | Firebase Cloud Functions v2 |
| Database | Cloud Firestore | Native mode, Admin SDK |
| Queue | Google Cloud Tasks | Fan-out orchestration |
| Schemas | Zod | Shared via @soku/schema package |
| Testing | Jest, Cypress 15 | Unit + E2E |
| CI/CD | GitHub Actions, Turbo | Lint, typecheck, test, build |
| Logging | Pino | Structured JSON logs |
| Media | Sharp, FFmpeg | Image optimization, video transcoding |
Sections
| Topic | Link |
|---|---|
| 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 |
| Backend Conventions (Functions & Jobs) | Backend Conventions |
| Secrets & Configuration | Secrets & Configuration |
| Observability | Observability |
| Data, Storage & Async | Data, Storage & Async |
| Security | Security |
| Developer Experience | Developer Experience |
| LLM Development Guide | LLM Guide |
| 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 it in code or CI.