Vergeo5

Mobile-first, multi-vendor commerce-powered discovery platform for Zambia.

Prerequisites

• Node.js 22 (see .nvmrc / .node-version)
• pnpm 9 (corepack enable)

Quick start

pnpm i
pnpm dev

Workspace layout

apps/customer   apps/vendor   apps/admin        # Next.js 15 apps
services/api                                     # FastAPI backend
packages/ui     packages/types  packages/config  packages/i18n
supabase/migrations  supabase/seed  supabase/tests
infra/          .github/workflows/

Commands

Command	Description
pnpm dev	Start all dev servers (turbo)
pnpm build	Build all packages
pnpm lint	Lint all packages
pnpm typecheck	Type-check all packages
pnpm test	Run all tests
make dev	Same as pnpm dev
make verify-scaffold	Run scaffold verification script

Copy .env.example to .env.local (or service-specific env files) and fill in values locally — never commit secrets.

Required CI checks

The CI and Performance budgets workflows must be green before merging to master. In GitHub branch protection, mark these jobs as required:

Job	Purpose
js	Turbo-affected lint, typecheck, test, build
python	API ruff, mypy, unit pytest
ask-evals	Deterministic Ask Vergeo grounding evals
staging-guards	Staging separation, seed, and config syntax guards
secret-scan	Blocking gitleaks + n8n plaintext-secret scan
deps-audit	Blocking pnpm/pip audit, with documented accepted advisory allowlist
security-gates	Headers manifest + route x role authz matrix
migrations	Fast Dockerless migration replay (scripts/ci/migration-replay.sh)
db	Supabase db reset + typegen drift on packages/types/src/db.ts
rls	Blocking curated DB-backed integration set; demo seed + broad RLS advisory
money-db-triggers	Release/accounting/reconcile trigger integration
cod-container-smoke	Real API container COD smoke, heavy steps path-filtered
perf	Bundle guard, image lint, and blocking Lighthouse CI

i18n-lint is intentionally warning-only in ci.yml. Also enable “Do not allow bypassing the above settings” so admins cannot merge past a red required check (the process fix for the 0009 migration escape). See docs/ops/ci.md for setup details.

Commit conventions

Conventional commits enforced via commitlint + lefthook. Example: feat: add cart summary.