Documenting your decision

Introduction: The Decision is Made. Now What?

In our last post, you ran a critical spike to validate your architectural hypothesis. The experiment was a success, providing the crucial, evidence-backed confidence to proceed with an Event-Driven Architecture for CityPulse. You have the data. You have the justification. But a decision that lives only in your head or on a spreadsheet is worthless.

What happens in six months when a new developer joins the team? What happens in a year when you need to evolve the system? This is where most teams fail. They suffer from “Architectural Amnesia.” Decisions are made, people move on, the context is lost, and future teams are left wondering, “Why on earth did they do it this way?” This leads to bad changes, technical debt, and frustrated engineers.

The final, critical step in your framework is to effectively document and communicate the what and the why of your decision. For this, you’ll use two powerful, practical tools: Architectural Decision Records (ADRs) and the C4 Model for diagrams.

Capturing the “Why”: Architectural Decision Records (ADRs)

Your first task is to record the “why” behind your choice. You don’t need a 100-page document that no one will ever read. You need something lightweight, clear, and focused. You need an Architectural Decision Record (ADR).

An ADR is just a short, simple text file, usually written in Markdown, that captures a single architectural decision. Think of it as a journal entry for your architecture. Here’s a practical template:

 1# Title: Event-Driven Architecture for Core Ticketing Flow
 2
 3**Status:** Accepted
 4
 5**Context:**
 6
 7We need an architecture for CityPulse that can handle high-throughput, 
 8transactional spikes during major concert sales, while allowing us to launch
 9within a tight, 3-month deadline. A monolith risks failing under load, while
10a traditional microservices approach is too complex to build quickly.
11
12**Decision:**
13
14We will adopt an Event-Driven Architecture for the core ticketing workflow.
15The initial implementation will focus on the `TicketPurchaseRequested` event
16and the services that consume it. We will precede this with a two-week, 
17time-boxed spike to prove out the technology and our team's ability to manage
18it.
19
20**Consequences:**
21
22*   **Positive:** This style directly addresses our critical scalability and
23reliability drivers. It decouples our services, making the system more 
24resilient to individual component failures. It provides a foundation for
25future, real-time features.
26
27*   **Negative:** We accept the significant upfront complexity and learning
28curve associated with asynchronous systems and eventual consistency. This poses
29a risk to our timeline, which we are mitigating with a focused spike. Debugging
30and end-to-end testing will be more difficult than in a monolith.

Communicating the “What”: The C4 Model

Now that you’ve captured the ‘why,’ you need to explain the ‘what.’ How will this new system look? But who is your audience? A common mistake is to draw one massive, overly complex “big ball of mud” diagram that tries to show everything to everyone. It’s confusing and ultimately useless.

The solution is to create different maps for different audiences. The C4 Model is a simple, powerful way to do this.

For the CEO, you start at Level 1: The System Context Diagram. This is a simple, high-level map of the world. It shows CityPulse as one box in the middle, with the users who interact with it (like the ‘Event Goer’ and ‘Organizer’) and the other systems it talks to (like the ‘Payment Gateway’ and ‘Email Service’). It shows the big picture and nothing more.

For your lead engineer and the development team, you zoom in to Level 2: The Container Diagram. This map shows the major technical building blocks inside CityPulse. For your new EDA, this might show a ‘Web App’ that publishes events to a ‘Message Broker,’ and several services that consume those events, like the ‘Ticketing Service’ and the ‘Notifications Service,’ each with its own database. It shows how the major pieces of your architecture fit together.

You can zoom in further to Components (Level 3) and Code (Level 4), but for communicating a new architectural style, these first two levels are the most critical.

A Decision, Documented

And with that, you have executed every step of the formal decision-making framework. You started with a vague business problem, translated it into measurable drivers, analyzed your options, made a data-driven decision, and now you’ve documented and communicated it clearly. This is the complete, repeatable process for making a high-stakes architectural choice.

But is your job as an architect over? Not even close.

In our final post of this foundational series, we’ll look at what happens after the decision. We’ll explore the architect’s ongoing role in guiding the system’s evolution, managing technical debt, and ensuring the vision becomes a reality. It’s where the real work begins.

Further Reading

• “Documenting Architecture Decisions” by Michael Nygard. The original blog post that introduced and popularized the concept of Architectural Decision Records (ADRs).
• The C4 model for visualizing software architecture. The official website for the C4 model, created by Simon Brown. It includes a full description of the notation and its levels.

What’s the biggest challenge you face with documentation in your team? Have you ever used ADRs or C4? Share your experiences in the comments.