Search across all documentation pages
A case study, in this documentation's sense, is a record of a real technical decision made under specific constraints - team size, deadline, existing stack, business risk tolerance - along with what happened as a result. It is not a tutorial, and it is not a template meant to be copied wholesale into an unrelated system.
This section holds two kinds: reference architectures like Reference: B2B SaaS API, which are annotated snapshots of a working system, and before/after stories like Before/After: Express → Fastify, which document a specific migration with measurable results. This page doesn't narrate either one - it's the mental model for reading any case study in this genre well: what to look for, what to weigh, and where the reasoning actually transfers versus where only the code does.
Every case study answers one implicit question: given these constraints, what did this team decide, and what happened? Reading one well means reconstructing that question before evaluating the answer.
The constraints section - team size, deadline, tenant count, existing dependencies, risk tolerance - is what makes a case study transferable or not. A reference architecture built for a three-service B2B SaaS product with under 500 tenants is not automatically the right shape for a 30-service platform with enterprise customers demanding data isolation; the architecture didn't fail, it just answered a different question than the one you're asking. Reference: B2B SaaS API states this explicitly in its multi-tenancy table - row-level tenant_id for under 500 tenants, schema-per-tenant only at compliance request - precisely so a reader can check whether their own constraints match before adopting the pattern.
A useful analogy: a case study is closer to a court case record than a recipe. A recipe says "do these steps and you'll get this result, regardless of who's cooking." A case record says "given these specific facts, this was the ruling" - and a good legal reader studies the facts of the case as carefully as the ruling itself, because the ruling only transfers when the facts line up.
Evidence vs. anecdote is the second foundation. "Much faster" is an anecdote; "+35% RPS on the same hardware, k6 script attached" is evidence. A case study without numbers, a load-test reference, or a before/after comparison on comparable hardware isn't wrong to read, but it should be weighted as a story, not as proof that a pattern works.
Reading a case study efficiently means scanning for a small number of specific things, in a specific order, rather than absorbing the whole document linearly.
Start with the date and stack version. Reference: B2B SaaS API is annotated 2026-07 against Node 24.18.0, NestJS 11, and Prisma 6 - and that annotation isn't decoration, it's a claim about applicability. A reference architecture written against Express 4 and callbacks tells you less about how to structure a service today than one written against current framework majors, even if the underlying reasoning (separate the HTTP layer from domain logic) still holds.
Next, look for the "what we deliberately skipped" section. This is often the most honest and most useful part of a reference architecture, because it tells you what the authors judged not worth the complexity given their constraints - GraphQL, a service mesh, event sourcing - which is exactly the information you need to judge whether your own, different constraints would tip that decision the other way.
Then check for a motivating ADR. A well-formed case study links back to the architecture decision record that produced the choice being documented, which is where the actual criteria and trade-off weighing lives - the case study shows you the destination, the ADR shows you the reasoning that got there.
Reading order for a reference architecture:
1. Date + stack version -> still applicable to your stack?
2. Constraints stated -> do they match your situation?
3. Deliberate omissions -> would your constraints change that call?
4. Metrics / load evidence -> is this evidence or anecdote?
5. Linked ADR -> what was the actual reasoning?For a before/after story specifically, the mechanics shift slightly: the thing to check is whether the comparison is fair. Before/After: Express → Fastify-style pages are only useful if the before and after numbers came from comparable hardware and comparable load, and if the migration's engineer-week cost is stated alongside the throughput gain - a before/after that reports the win without the cost is telling half the story.
Case studies age, and reading one without noticing its staleness is a quiet way to inherit outdated defaults. A reference architecture pinned to Node 20 and Express 4 might still contain sound reasoning about module boundaries, but its specific dependency choices, pool sizing, or auth pattern may already be behind what a current audit would recommend - which is why this section's own best-practices page recommends revisiting case studies when major versions ship and reviewing them on a fixed cadence rather than treating them as permanently current.
Transferability also has a scale dimension worth naming explicitly: a pattern proven at one team's scale doesn't automatically prove itself at a very different scale in either direction. A worker-fleet pattern built for bursty batch jobs at moderate volume, as in Reference: Worker Fleet, can be over-engineered for a team with ten jobs a day, and under-provisioned for one running ten thousand. The case study proves the pattern worked there - it doesn't prove it's the right size for here.
Organizationally, case studies serve a few distinct purposes that pull in slightly different directions: onboarding (a fast, concrete way for a new engineer to understand "how we build things" without reading every section), historical record (traceability back to the ADR and, if relevant, the incident that motivated a change), and calibration (checking a new proposal against what's already been tried). A team that only uses case studies for onboarding tends to let them go stale, since nobody revisits them once someone's ramped up; a team that treats them as living calibration references tends to keep them current, because the pressure to update comes from active use, not scheduled maintenance alone.
| Type | Strength | Weakness | Best Fit |
|---|---|---|---|
| Reference architecture | Shows a coherent, working system shape end to end | Easy to cargo-cult without checking constraint fit | Starting-point design for a new service in a similar domain |
| Before/after migration story | Concrete, comparable metrics; cost and benefit both visible | Only as reliable as the fairness of the comparison | Justifying or sizing a similar migration |
| Post-mortem / retrospective | Grounded in a real incident; high credibility on failure modes | Narrower scope, one specific failure rather than a general pattern | Learning what not to do, or calibrating incident response |
The sharpest failure mode across all three types is treating a composite or generalized reference as if it were literally one company's private production system. Most reference architectures in a documentation set like this are composite patterns distilled from common practice, not a leaked internal repo - which makes the constraints section even more important to read carefully, since it's standing in for a real team's actual situation rather than describing one verifiably.
A documented record of a real technical decision made under stated constraints, along with what resulted - this section covers two forms: reference architectures (a system snapshot) and before/after migration stories (a specific change with measured impact).
They're composite references based on common, proven patterns rather than one company's literal private repository, which is exactly why the constraints section matters - it's standing in for a real situation, and you have to check it against your own rather than assuming it was verified end to end for you.
The constraints - team size, tenant count, deadline, risk tolerance - because those determine whether the architecture is answering a question close to yours or a substantially different one.
Its stack version ages relative to current majors, and the specific defaults it recommends (pool sizes, dependency choices, an auth pattern) can drift behind what a fresh audit would recommend, even while the underlying structural reasoning stays sound.
Evidence is a specific, checkable number under stated conditions - "+35% RPS on the same hardware, k6 script attached" - while an anecdote is a qualitative claim like "much faster" with no way to verify or reproduce it.
Because that list reveals the judgment call behind the architecture, not just its outcome - it tells you what the authors decided wasn't worth the added complexity given their constraints, which is exactly the information you need to check whether your different constraints would flip that call.
Only after checking that the before and after numbers were measured on comparable hardware and load, and that the migration's cost (engineer-weeks, risk, downtime) is disclosed alongside the gain - a win reported without its cost is an incomplete comparison.
An ADR documents the decision-making process itself - options considered, criteria, the actual debate; a case study documents the resulting system or migration and what happened afterward. A well-formed case study links back to the ADR that motivated it so a reader can see both the destination and the reasoning that produced it.
A case study proves the pattern was appropriate for one team's specific volume and complexity, not that it scales linearly in either direction - a worker-fleet or queue pattern sized for moderate, bursty load can be needlessly complex for very low volume and undersized for very high volume.
After a major migration or a significant incident with a real, measurable before/after - writing it down while the reasoning and numbers are fresh turns institutional knowledge into a reusable reference instead of something that only lives in a few people's memory.
On a regular cadence, commonly quarterly, and especially whenever a major dependency or framework version ships - the goal is catching staleness before a new reader inherits an outdated default without realizing it's outdated.
Stack versions: This page is conceptual and not tied to a specific stack version.
Reviewed by Chris St. John·Last updated Jul 15, 2026