Host: Welcome back. You're in GenAI Architecture and Design Patterns — a course about the blueprints behind real generative AI systems. This chapter is about something called an ADR engine. ADR stands for Architecture Decision Record — basically a written-down record of why your team picked one approach over another. And today's skill is something every AI team needs the moment their system grows past a prototype.
Expert: Let me paint the scenario. Imagine you're at a mid-sized company — say, two hundred engineers, maybe fifteen different AI-powered services in production. One team picked a large model from one vendor. Another team picked a smaller, cheaper model from a different vendor. A third team is fine-tuning their own model. A fourth team built a retrieval system — meaning the model looks up relevant documents before answering — instead of fine-tuning. Now a new engineer joins, or a security auditor shows up, or your cloud bill explodes, and someone asks a simple question: why did we make these choices? And nobody knows. The original engineers left. The Slack threads are gone. There's no paper trail. This is the mess that Architecture Decision Records exist to prevent. Every significant choice gets written down in a short, structured document — the problem, the options considered, the decision, and the trade-offs. But here's the catch. Having a system for writing these records doesn't mean teams actually write them. And that's the gap you're going to close in this exercise.
Host: So this is your starting point for this chapter. The overview walked through the big picture of decision records. Now let's get specific. What exactly are we building?
Expert: You're going to build what's called a coverage report. Think of it like a checklist scanner. On one side, you have a list of all the services your organization runs — every AI-powered product, every internal tool. On the other side, you have a catalog of the decision records that have actually been written. Your system will compare these two lists and tell you, for each service, which required decisions are documented and which are missing. The output is a gap report — a clear, structured summary that says "this service is missing a record about which model it uses" or "that service never documented why it chose retrieval over fine-tuning." Here's the key idea, the conceptual aha. You're not just checking whether any record exists. Different categories of services need different categories of decisions. A customer-facing chatbot needs a documented choice about which model to use, where it's hosted, and whether it uses retrieval or fine-tuning. An internal summarization tool might only need the model choice documented. So your coverage logic is category-aware — it knows what questions each type of service is required to answer, and it flags the ones that haven't answered them. That's what makes this a governance tool, not just a file counter.
Host: Okay, before we wrap — what's the tricky part? What trips people up on this one?
Expert: The trap is treating this like a simple "does the file exist" check. Students often write something that just looks for any decision record attached to a service and marks it covered. That misses the whole point. A service can have one record written — say, about the database it uses — and still be completely undocumented on the AI-specific choices that matter: which model, where it runs, and the retrieval-versus-fine-tuning question. So before you write any logic, slow down and map out the required categories of decisions for each service type. Write that mapping down first. Then your coverage check becomes: for each service, for each required category, is there a record that specifically addresses that category? Get the mapping right and the rest of the code is straightforward. Skip that step and you'll ship a report that looks green while your architecture is actually undocumented.
Host: Great warning. Let's land this. What will the listener walk away able to do, and where does this go next?
Expert: After this exercise, you'll be able to take a list of services and a catalog of decision records and produce a clear, category-aware report showing exactly which architecture choices are undocumented across your organization. That's a real governance capability. This is the kind of building block your team can plug straight into an architecture review process — the foundation for knowing, at a glance, where your documentation debt lives before it becomes an audit problem or a costly rewrite. Next, you'll extend this work into a review workflow. That means going beyond "is it documented" to "is it still valid" — adding approval gates so new decisions get reviewed by the right people, and expiry tracking so records about fast-moving things like model versions get re-examined on a schedule, while slower-moving decisions about hosting stay valid longer. So today you're building the detector. Next exercise, you're building the workflow around it. Together they become the backbone of the decision engine this chapter is named after. Good luck, and thanks for listening.
Want to go deeper? Explore disciplines with hands-on labs, quizzes, and chapter podcasts.