Engineering overview
Status: Scaffolded 2026-09-24
Four repos, one baseline. Every repo carries the same governance files (SOUL.md, PRODUCT-PRINCIPLES-CHECKLIST.md, AGENTS.md, CODEOWNERS, the PR template) and the same tooling, so switching between them costs nothing and a rule learned once holds everywhere. The repo dependency map shows how they relate; this page is about how they are kept honest.
The baseline
| Concern | Tool | Where it runs |
|---|---|---|
| Lint and format | Biome 2.5.x, one shared biome.json | editor, pre-commit, CI |
| Pre-commit | husky + lint-staged | every commit |
| Secrets in the working tree | secretlint on every staged file | every commit |
| Secrets in history | gitleaks | CI, full history |
| Dependencies | Dependabot, weekly, minor and patch grouped | GitHub |
| Contract | npm run validate | local before a PR, CI on every PR |
| Commit subjects | Conventional commits (feat:, fix:, docs:, chore:, refactor:, test:) | review |
| Merge | Squash into main | GitHub |
| Branch protection | ruleset: PR only, code-owner review, validate required, admin bypass | GitHub |
The admin bypass exists because there is one maintainer. It lets a solo merge happen without a second reviewer; it does not skip validate, and the PR summary block is still filled in. See the development workflow.
What validate means per repo
validate is the CI contract. CI does nothing you cannot run locally, and CI runs nothing else. If it is green on your machine it is green in CI, and the reverse.
| Repo | validate runs | Not in validate |
|---|---|---|
vegan-grove-api | biome check, tsc --noEmit, vitest run, tsc -p tsconfig.build.json | seed scripts |
vegan-grove-web | biome check, tsc --noEmit, next build | Playwright smoke (test:e2e) |
vegan-grove-mobile | biome check, tsc --noEmit, check:prod (release guard) | EAS builds |
vegan-grove-docs | biome check, tsc, pokedocs check, docusaurus build | nothing |
Details: linting and formatting, testing, pre-commit hooks.
CI shape
.github/workflows/ci.yml has two jobs on every pull request to main: validate (Node from .nvmrc, npm ci, npm run validate) and secrets (gitleaks over the full history). The docs repo adds a cached Playwright chromium step because Mermaid renders to SVG at build time. validate is the required status check in the ruleset. A gitleaks finding is handled as an incident, not a red X to retry.
What is deliberately absent
No Docker in any repo (the API runs under PM2 on one host, see backend deployment). No ESLint or Prettier next to Biome. No error-tracking SaaS: errors are logged locally by pino, because a hosted tracker with request context is a third party holding member data. No coverage gate yet; the testing page says what every route test must include instead.