QA
packages/qa is the team's QA recording surface at qa.greengoods.app:
a deployed checklist where two people can record the same test case at the same time, each keeping
their own verdict and notes. It exists because a shared artifact checklist could only ever have one
writer; this is the same interface with a real store behind it.
How it stays correct with two writers
The design is small but sharp, and worth reading as a case study in conflict-free coordination:
- Each tester owns exactly one blob shard, keyed by their address, and only ever writes that one. Two testers touching the same case touch different objects, so there is nothing to merge between them.
- Within one tester (a phone on the PWA and a laptop on admin at once), saves send field-level deltas conditioned on the ETag that was read; a losing write re-reads and retries instead of overwriting blind.
- Ordering trusts server arrival time, never client clocks, and every keystroke lands in
localStoragebefore any network call, so a crash or failed save never costs anyone their notes.
Identity is the signing address: the server accepts reads and writes only from a valid session for an allowlisted address. Display names are labels, never authority.
Map
| Path | What lives there |
|---|---|
index.html | The checklist interface itself |
api/state.ts | Saves and reads each tester's results: one shard per tester, per run |
api/runs.ts and runs.ts | QA runs: one team pass over the catalog, versioned in the store |
api/auth.ts and auth.ts | Sign-In With Ethereum, checked against the allowlist |
store.ts | The Vercel Blob side of the store, shared by both endpoints |
build.mjs and dev.mjs | The build that copies the page and pins the test-case catalog beside it, and the local rehearsal server (node dev.mjs) |
locales/ | The interface strings in every supported language |
Run and build
bun run --cwd packages/qa build
The app deploys through Vercel, and each deployment pins the test-case catalog revision it shipped with. When catalog changes merge, redeploy the QA app and regenerate the docs page; CI rejects a stale copy.
How it connects
The catalog source is scripts/data/qa-test-catalog.json, shared with the generated
Test Cases page, and the app is the recording half of the
Product QA practice.
Go deeper
packages/qa/AGENTS.mdis the package contract: catalog ID retention, the public and private evidence boundary, fail-closed authentication, locale alignment, and the validation path a change has to run.packages/qa/README.mdexplains the concurrency design in full, including the caching and retry details that look like bugs if you don't know them.