Skip to main content

Local Dev Environment QA Buildout

Updated: 2026-06-12

This document records what the local QA system can prove today. It is a support reference, not a planning ledger. Shipped, superseded, or abandoned QA plans belong in git history, not in this doc.

Use scripts/test-local.sh as the canonical entry point:

./scripts/test-local.sh doctor
./scripts/test-local.sh quick
./scripts/test-local.sh contracts
./scripts/test-local.sh local
./scripts/test-local.sh no-heavy
./scripts/test-local.sh full
./scripts/test-local.sh external-gates

scripts/local-validation/qa.sh remains an internal focused-check helper for stubs, seed checks, route coverage, docs checks, and external-gate probes. Do not reintroduce the retired coverage matrix, obligation rollup, findings ledger, manual-run ledger, tracking-rollup, or generated inventory workflows as active gates.

Current Local Stack​

./scripts/local-validation.sh up starts the local app stack backed by the Spanner emulator, Firebase Auth emulator, and local provider substitutes.

Current microservice surfaces:

  • auth
  • merchant-api
  • management-api
  • terminal-api
  • terminal-onboarding
  • tx-bundler
  • status
  • kitchen-api
  • ai-api

Current website surfaces:

  • Retail portal
  • Support portal
  • Shared portal package
  • peakpos.co redirect app
  • Landing page
  • Design-system UI and kit

The retired peak-api, standalone PeakPro portal, and apps/sandbox tree are not local QA surfaces. Useful PeakPro workflows now live behind current retail, support, management-api, merchant-api, and ai-api ownership boundaries.

Locally Testable​

These surfaces can be proved locally through Bazel, scripts/test-local.sh, or focused scripts/local-validation/qa.sh scopes:

  • Repo-wide Bazel build and unit/component/static tests.
  • Spring service unit tests for current microservices.
  • Local image build/startup checks for current Cloud Run services.
  • Spanner-emulator-backed SQLDelight schema and repository behavior.
  • Firebase Auth emulator login and tenant fixtures.
  • Retail and support portal lint, tests, and local Playwright flows when the required dev servers are available.
  • Landing page local build behavior.
  • Shared UI package tests and visual/consumer contracts.
  • Local provider substitutes for Gateway, notifications, integrations, images, AI, cloud status, security tokens, internal auth, terminal mTLS, and seed workflows.
  • OpenAPI and generated SDK drift checks.
  • Dafny verification and generated IAM engine handoff tests.
  • Android JVM/unit tests and debug APK build; emulator/device execution when a reachable device is available.
  • iOS and Peak Mobile structural/build-evidence checks when host prerequisites are available.
  • Docs index/render checks.
  • Terraform formatting/static validation and CI workflow static checks.

External Gates​

These cannot be fully proved by local stubs:

  • Cloud Run ingress, traffic tags, IAM invoker enforcement, workload identity, autoscaling, and deployed revision behavior.
  • Cloudflare DNS, WAF, edge routing, Pages deploy behavior, and public redirect domains.
  • Real Cloud Spanner staging/production performance, backup/PITR, roles, and DDL application.
  • Secret Manager payload availability and enabled latest versions.
  • Private CA, edge mTLS, terminal certificate revocation, and real terminal domain validation.
  • Gateway/provider staging credentials, hosted checkout/payment pages, webhook delivery, card-present runtime approvals, and real-card movement.
  • Third-party OAuth/provider consoles and live webhook delivery.
  • SendGrid/SMS provider deliverability, suppressions, and carrier behavior.
  • HubSpot/OpenAI/live vendor APIs.
  • Google Play, App Store Connect, TestFlight, Firebase production services, and physical-device distribution evidence.

Use:

./scripts/test-local.sh external-gates

to record current availability and missing inputs without pretending those external proofs ran locally.

Current Buildout Priorities​

Add new local proof as Bazel tests or as focused scripts/local-validation/qa.sh scopes that are called by scripts/test-local.sh. Prefer small executable checks over new ledgers.

Good candidates:

  • More local proxy coverage for path-routed staging shapes.
  • More deterministic provider-stub scenarios for Gateway and third-party integration failures.
  • More portal behavior tests for degraded, denied, empty, and retry states.
  • More Android emulator/device automation once a stable device bridge exists.
  • More staging smoke preflight checks that name missing credentials without hiding them as local PASS results.