Architecture Decision Records: How we make better technical choices at MakerX

Have you ever joined a project midway and wondered, "Why on earth are we using this technology when there are better options available?" You're not alone.

At MakerX, we believe that transparent decision-making is essential for successful software delivery. That's why Architecture Decision Records (ADRs) play a key role in our development process.

What is an ADR?

An Architecture Decision Record is essentially a way to capture the reasoning behind significant technical choices. At its core, it's an advanced pros and cons list – but one with enough context and detail to prove invaluable months or years after the decision was made.

ADRs help us drive success by basing decisions on data rather than opinions allowing teams to make calculated decisions that deliver better outcomes for clients.

The ADR GitHub Organization provides excellent resources on how to implement ADRs effectively which we have used and adopted to suit our style.

A tale of technical decisions lost to time

Picture this scenario: It's one year into a project. The team is stuck on a problem, and a new developer asks, "Why are we using this provider? There are better options available."

Without proper documentation, the original reasoning becomes lost to time. Conversations that led to decisions get buried in chat histories or forgotten entirely. The team wastes valuable time either recreating past discussions or, worse, making changes without understanding the original constraints.

With an ADR, the team can quickly understand:

• Why the original decision was made
• What alternatives were considered
• What data informed the choice
• What constraints were present at the time

This aligns with Michael Nygard's influential work on documenting architecture decisions and enables informed reassessment when circumstances change – which they inevitably do in software development.

Where ADRs fit for MakerX

At MakerX, we initially focus on deeply understanding our clients' needs and problems to form a picture of what a successful business outcome looks like. We intentionally avoid getting into technical implementation details during pre-project discussions.

When a project kicks off, our first technical activity involves:

1. In-depth architecture exploration
2. Identifying what decisions need to be made
3. Prioritising decisions by risk
4. Creating ADRs for the highest-risk decisions first

This methodical approach ensures we make deliberate technical choices aligned with business objectives rather than naively rushing into implementation and that the rationale behind our decisions are understood and documented for the future.

The ADR template: A framework for decision-making

Our ADR template includes these key sections:

• Metadata
  • Status: The current state of the decision (draft, approved, superseded)
  • Ownership: Who created the ADR and who participated in the decision
  • Timeline: When the ADR was created, decided, and last updated
• Context: The project status, the goal of the decision, dependencies, and constraints
• Requirements: Technical and functional requirements (must-haves and nice-to-haves)
• Principles: High-level preferences guiding decision-making
• Options: List of alternatives being considered
• Evaluation: Pros and cons for each option
• Preferred Option: The recommended choice and reasoning
• Selected Option: The final decision (and why it might differ from the preference)

ADRs across different project scenarios

One of the strengths of our ADR approach is its flexibility across diverse technical decisions. At MakerX, we use ADRs for:

Complex technical infrastructure decisions

When selecting a blockchain network and wallet provider for a financial application, we broke down the decision into manageable steps, evaluating options against security, regulatory, and user experience requirements. This structured process helped us navigate, together with our client, a complex decision with far-reaching implications.

Infrastructure ownership and account management

For projects that may evolve into separate ventures, we use ADRs to document ownership decisions for critical infrastructure like cloud accounts, code repositories, and developer accounts. This approach clearly defines which assets should be client-owned versus MakerX-owned, enabling smooth transitions as projects mature and ensuring seamless handover when required.

Technology stack selection

From choosing between React Native and Swift for mobile development to selecting between various backend frameworks, ADRs help us evaluate options against principles like developer experience, maintainability, and time-to-market.

Data architecture and reporting

For business intelligence solutions, we use ADRs to document decisions around data filtering, ETL processes, and reporting methodologies, ensuring that technical choices align with both immediate needs and future scalability.

Breaking down complex decisions

For particularly challenging decisions, we sometimes break them down into sub-decisions. In one project involving blockchain wallet selection, we structured the decision process into five steps:

1. Who should control ownership of the wallet: the user, client or a trusted third party?
2. Which providers met our trust requirements?
3. Which met our technical requirements and cost constraints?
4. Which supported blockchain networks met our environmental and performance criteria?
5. Final selection based on weighing all factors

We used these steps as a decision tree to exclude options from the final decision. This approach helps prevent decision paralysis when facing numerous options and interdependent factors.

When preferred doesn't equal selected

One interesting aspect of our ADR process is the clear distinction between the "Preferred Option" and the "Selected Option". This separation acknowledges that the technically optimal choice isn't always the one implemented.

We've seen cases where:

• Time-to-market considerations led us to choose a simpler solution despite being a non-optimal technical solution
• Business constraints necessitated different choices than pure technical evaluation would suggest

By documenting both the preferred and selected options with their reasoning, we maintain transparency about why certain compromises were made—valuable context for future maintenance and evolution.

Making ADRs practical, not paralyzed

The key to effective ADRs is balance. Don't get stuck analyzing every option exhaustively. Instead:

1. Quickly eliminate options that don't meet core requirements or principles
2. Focus evaluation on how each remaining option aligns with project needs
3. Document your reasoning clearly but concisely

The goal isn't perfect decisions – it's informed decisions with transparent reasoning that teams can reference and revisit as needed.

How this blog post was created

This blog post was created using Claude 3.7 model in VS Code agent mode with MCP server for local filesystem access. We provided the AI with structured bullet points on ADRs and example files from MakerX's documentation, then extensively edited the generated content.

Want to go full circle with an AI summary? Here it is:

• ADRs defined: Structured documents capturing reasoning behind technical choices
• Problem: Prevent loss of decision rationale that often gets buried in chat histories
• Process: Understand business needs first, then explore architecture and create ADRs for high-risk decisions
• Template: Includes metadata, context, requirements, principles, options, evaluation, and both preferred/selected options
• Versatility: Used for infrastructure, technology stack, data architecture, and ownership decisions
• Practical approach: Focus on informed decisions with transparent reasoning that teams can reference later

The essence of ADRs is transparent decision-making that prevents knowledge loss and enables future teams to understand the context behind technical choices.