Build ADR persistence layer with versioning and supersede chains — lab audio overview

Host: Welcome back to GenAI Architecture and Design Patterns. You're in the chapter on the GenAI Architecture Decision Record Engine — and an Architecture Decision Record, which we'll just call an ADR from here on, is a short written document that captures one important technical choice your team made, why you made it, and what you considered before settling on it. This chapter is about automating those records for GenAI systems. And today's skill — keeping a permanent, trustworthy history of those decisions — is something every serious engineering team wrestles with. Expert: Picture a mid-sized company, maybe two hundred engineers, that's been shipping GenAI features for about a year. They started with one model from one vendor. Six months in, they switched to a cheaper model for a specific use case. Three months after that, they moved one workload from a cloud provider to their own hosted setup because of data privacy rules. Now a new architect joins, asks a simple question — "why are we using this model here?" — and nobody can answer. The original Slack thread is gone. The person who made the call left. There's a document somewhere, but it's been edited fourteen times and nobody knows which version was actually approved. This is the exact pain that drives teams to build a proper decision record system. Without it, every architectural choice becomes folklore. With it, you have a timeline — you can see that decision number seven replaced decision number three, which replaced decision number one, and you can read the reasoning at every step. That traceability is what you're going to build today. Host: In the previous exercise you built the scoring engine — the part that takes several options, like three different models you're choosing between, rates each one against weighted criteria like cost and accuracy and latency, and tells you which one wins. So now you have decisions being made. The question becomes: where do those decisions live, and how do you track them over time? So what exactly will we build in this final exercise? Expert: You're going to build two things that work together. The first is a storage layer — think of it as a filing cabinet that lives in memory while your program runs. It holds every decision record your system has ever created. You can drop a new record in, pull one back out by its identifier, or ask it to replace an old record with a newer one in a single, safe operation. The second piece is a history tracker that sits on top of that filing cabinet. Its job is to understand that decisions aren't one-offs — they evolve. When you replace an old decision with a new one, the new one points back to the old one like a chain. The history tracker can walk that chain, tell you which version is currently active, and hand you back the full timeline from the very first decision to the latest one. Here's the key idea that makes this whole thing click: decisions are never deleted. They are superseded. That word just means "replaced by a newer version, but the older one is kept on the record." It's like version history in a document editor — you can always see what it used to say, who changed it, and when. In architecture, that's not a nice-to-have. It's how you defend past choices to auditors, new hires, and your future self. Host: Every exercise has one spot where people stumble. What should the listener watch out for here? Expert: The tricky part is what we call the atomic replace. When you supersede one decision with another, two things have to happen together — the old record has to get marked as replaced, and the new record has to get stored and linked back to the old one. If only one of those happens, your history is broken forever. You'll have an orphan record, or a chain that points to nothing, or two decisions that both think they're active. The fix is to treat the whole swap as a single, indivisible step — either both changes land, or neither does. When you're writing this, resist the urge to do it in two separate stages with a gap in between. Do the checks first, then make both updates as one move. The second smaller gotcha: when you walk the chain to find the current active version, make sure you handle the case where the chain is just one link long — the very first decision, which hasn't been superseded by anything yet. That edge case catches people. Host: So after this exercise, you'll be able to take any architectural decision your team makes, store it with a full audit trail, replace it safely when circumstances change, and reconstruct the complete decision timeline on demand. That's a building block your team can drop straight into a governance discussion — the kind of foundation that turns scattered decisions into a defensible architectural record. And with this done, you've now built the complete GenAI decision record engine: structured models, weighted scoring, and versioned persistence. Three exercises, one working system you can bring back to your team's architecture reviews. Thanks for listening, and good luck with the build.