Problem
GUT Music is a platform for emerging artists. An artist builds a profile, uploads reels and applies to auditions, and gets a wallet with vouchers to spend on premium services from GUT and its partners. Anyone can browse artists, auditions, reels, events and collections. Staff approve new artists and manage the content from a CMS.
Both apps sit on an API written by a separate backend team, and a change in a response could break a screen without warning. Before every release, someone went through the QA checklist by hand. It took a full day.
Architecture
The artist app and the CMS are two React clients. Every request goes through a contract layer (Zod schemas and a typed client) on its way to the backend API, and the end-to-end tests reuse the same schemas. Woodpecker CI builds and deploys both apps. Before a release, the end-to-end suite runs against staging.
I read the API code to agree on contracts with the backend team, but I don’t change it.
Scope
Mine
- The artist PWA and the CMS, from routing to forms
- The typed API client, with runtime validation on every response
- Instant reopen and offline reads through a persisted query cache
- Unit and end-to-end suites, and the link between the tests and the QA checklist
Other teams
- Backend API and data model (backend team)
- Product decisions and visual design (product and design)
- Final sign-off of a release, still done by hand on the checklist
Key decisions
Validate every API response at runtime
Why. When the backend team changes a contract, the Zod error names the field that changed and the screen falls back to an error state.
Trade-off. Each contract change means updating a schema by hand. The apps and the tests take their types from those schemas, so the update happens in one place.
Persist the query cache in the PWA
Why. Artists open the app on their phones, often on a weak connection. I save the query cache to storage, so the last data shows up straight away, even offline.
Trade-off. I clear the cache on logout and on account switch. Queries that hold private or short-lived data opt out of persistence, each one explicitly.
Link the end-to-end tests to the QA checklist
Why. Each row of the checklist either has a test or is marked as manual. A test run then reports a pass or a fail for every row, in the terms QA already uses.
Trade-off. When QA renumbers the checklist, the links go stale. A script remaps them.
In code
One domain of the contract layer, trimmed down:
const Reel = z.object({
uuid: z.string(),
title: z.string(),
status: z.enum(["draft", "pending", "published"]),
createdAt: z.string(),
});
export type Reel = z.infer<typeof Reel>;
// A changed field fails here, with its path, not in the UI
export const useArtistReels = (artistId: string) =>
useQuery({
queryKey: ["artists", artistId, "reels"],
queryFn: async () =>
z.array(Reel).parse(await api.get(`/artists/${artistId}/reels`)),
});Results
- 1 day → 1 h
- to check every use case in the QA checklist before a release
- 128
- end-to-end tests, about 107 linked to rows of the QA checklist
- ~1,160
- unit tests across the app and the CMS
Someone still signs off each release by hand. They now start from a test run that goes through every use case on the checklist, the same way each time.