Reading the Architecture Before Writing the Code

A partner developer I work with as Technical PM brought me this project through Exprovia: an established, company-approved arrangement, not a one-off favor. I run his client onboarding, system design, sprint planning, and client meetings while he builds, and he has agreed to this case study being published. His client's proposal was unusually detailed: an inventoried lecture library, a phased scope, and testable acceptance criteria for an offline-first learning platform for professionals across Africa.

Most projects fail from a plan too thin to check. This one was detailed enough that nothing looked wrong at a glance, which was the real risk: every assumption was stated clearly enough to verify, and none of them had been.

I read the vendor documentation behind every platform named and priced every cost assumption. Four would not survive production. The deployment platform could not run the application: several core requirements hit structural serverless limits. The database chosen for being cost-efficient was actually the expensive option, since its billing rewards databases that idle and this one would not. The storage choice was right, but its cost model was incomplete: transcoding the library into a streamable format is a cost the project has to own separately, not one the storage line covers. And one acceptance criterion could not pass: the other target platform's own storage limits fall below what a single video lecture needs.

Finding the problems was the easy part. Raising four objections to a client proud of a plan he had just finished, without the meeting becoming a defense of it, was the actual work. I asked to meet the client directly rather than send a written list, since writing invites a written defense. Three things I held to: open with everything I was accepting unchanged, so the objections read as considered, not reflexive; name my own side's earlier mistake first; and say 'I don't know' where I did not, flagging it as a verification item with a named owner and deadline. I also moved the timeline out rather than protecting it, sequencing video after launch so revenue starts sooner.

The offline requirement was rewritten, not dropped: text, quizzes, and interactive activities work offline everywhere; video download is scoped to the platform that can support it, with an honest message on the one that cannot. I am now running system design and sprint planning: schema, tenancy, offline sync and conflict resolution, and a milestone-mapped sprint plan.

Discovery is agreed, the architecture is settled, and every open verification item has a named owner and a deadline. System design and sprint planning are in progress. The four issues were invisible at proposal stage and would otherwise have surfaced mid-build as delivery failures instead of a shared assumption caught early, for free.

A good plan needs auditing more than a bad one. A thin proposal gets questioned by everyone who reads it; a detailed one gets trusted, because the detail itself reads as diligence, which is exactly what makes it dangerous. What prevented this was reading vendor documentation and doing the arithmetic before agreeing to anything, not clever engineering. Disagreement is a delivery skill, not a technical one: the same objections delivered badly produce a client defending his document; delivered in person, with the arithmetic visible and my own error named first, they produced a revised architecture and a client who trusted the next four.