The Cloudwrit Web Engineering Handbook,
written so your next hire ships on day eleven.
A seventy-eight page account of how a document platform's web estate stays shippable as the team triples. Nineteen findings. Three critical. Twenty-seven decisions recorded. One opinion about the rendering boundary that we hold firmly.
Sanitized sample · Not a real engagementChapter 01 The web estate today, in one page.
Cloudwrit's public web surface is two applications and a content layer. The marketing site is 240 pages on Next.js 14, migrated from Create React App in mid-2024. The admin app is 320 routes, also Next.js 14, with a rendering boundary that was drawn sensibly at the time and has held up with exactly one exception. Combined test coverage sits at 68 percent, which is above your peer group median. Lighthouse is 88 / 96 / 100 / 91 on marketing, and 62 / 94 / 91 / 78 on admin, which is the specific number this handbook exists to change.
The thesis of this handbook is that your codebase is one sprint of attention away from very good, and three quarters away from excellent. There is no rewrite here. There is a cluster of bounded fixes, a rendering-boundary document your entire engineering team should read once, and a CI gate that will keep the work from regressing after we leave.
We wrote this for three readers. R. Ahmed, who will own the web platform day to day. J. Kim, who approves the quarterly engineering budget. And the senior you will hire in Q3, who needs to understand which decisions are load-bearing and which are reversible, without interviewing anyone.
Chapter 02 Three things to fix this quarter.
We ran an eight day engagement across your marketing repo, your admin repo, your CI configuration, and a representative slice of the CMS. Nineteen findings total. Three we believe require action inside this quarter. The remaining sixteen are sequenced in chapter six.
Admin main bundle is 512kb, blocking first interaction on 3G
The admin app main bundle is 512kb gzipped. Time to interactive on a throttled Moto G4 (the Chrome team baseline) is 4.1 seconds. Analysis shows 186kb of the main bundle is an icon library loaded wholesale, and 94kb is a chart library used on three routes. Code-splitting both would land main under 250kb with no feature change.
Eight admin pages fail WCAG 2.2 AA on keyboard and screen reader
Specifically: missing accessible names on icon-only buttons (four pages), focus traps absent from two modals, form fields without visible focus indicators (three forms), and one color-contrast failure in the sidebar. Axe and manual screen reader testing confirmed. Fix code is inline in Appendix B.
CMS preview route intermittently SSR-breaks on product pages
The marketing CMS preview renders correctly for blog posts and case studies. On product pages, roughly 1 in 8 previews shows a hydration mismatch warning and the metadata block falls back to client render. Root cause: a useEffect that reads navigator.userAgent on first render, inside a component that the marketing editor added in February. Fix is two lines.
The common thread across the three is not skill; it is the absence of an automated gate. Each of these would have been caught by a CI check that does not exist yet. Chapter 05 defines that gate. Chapter 06 sequences the fixes and the gate together, so the gate turns on the week after the fixes land.
Chapter 03 Findings, with evidence and fix code.
The full chapter reproduces all nineteen findings with the repro command, the measured metric before and after, the proposed fix (inline code, not a link), and an initials field for the engineer who closes it. The transcripts of Claude's reasoning for each finding are in Appendix D so your team can audit, disagree, or extend.
A fragment follows. The full chapter is omitted from the sample.
Chapter 04 How your rendering boundary actually works.
Two people at Cloudwrit can draw this accurately. By the end of this chapter, all of engineering can. That matters because three of your last six P2 incidents had the same shape: a component was moved across the boundary without the author realising, and the failure mode was subtle enough to ship. Your postmortems name the component, not the pattern. This chapter names the pattern.
- What renders on the server, what renders on the client, and why the split was made in October 2024.
- The four hydration rules and the specific APIs that break them (useEffect, useLayoutEffect, window reads, crypto.randomUUID).
- The three “sharp edge” components currently straddling the boundary and the reasoning for leaving each there.
- The four places in the codebase that do something non-obvious for performance reasons, with the before-and-after metric that justifies each.
- Where we believe the boundary should move in 12 months, and why not sooner.
Chapter 05 Performance budgets and the CI gate.
Every bundle bloats between audits, not because anyone is careless, but because nothing stops it. This chapter defines three budgets, the GitHub Action that enforces them, and the failure mode when a PR blows the budget. The budgets are: main bundle under 250kb gzipped on admin, Lighthouse performance above 85 on every route, and zero axe-core violations on every PR. Each budget has a one-week warning window before it starts blocking merges, so your team can respond rather than be surprised.
Chapter 06 The six month roadmap, sequenced.
Everything in the handbook resolves to this chapter. Nineteen findings plus three structural initiatives (the boundary doc, the CI gate, and the performance culture shift), ordered by when they should happen under your current staffing. Every line has an owner, an estimate, a definition of done, and a reviewer. If we have done our job, this chapter survives contact with your sprint planning without modification.
The remaining pages continue in this register: plain, sequenced, specific. There is an appendix with measured before-and-after numbers for every fix we recommend, a record of Claude's reasoning chain on each finding, and a decision log that starts today and keeps a running record of every web architecture choice you make for as long as this handbook is live.