Every software project is a series of decisions. Which database? What authentication strategy? Monolith or microservices? REST or GraphQL? Each choice shapes the system for years to come. Yet most teams document none of them. The code reflects what was decided, but the why — the context, the constraints, the alternatives considered — vanishes the moment the pull request is merged.
At Apptitude, we document every significant technical decision using Architecture Decision Records (ADRs). It is one of the simplest practices we have adopted, and one of the most valuable.
What Is an Architecture Decision Record?
An ADR is a short document that captures a single architectural decision along with its context and consequences. The concept was popularized by Michael Nygard in a 2011 blog post, and it has since become a staple of mature engineering organizations.
The key insight behind ADRs is that architecture is not a diagram — it is the sum of all the decisions that shaped a system. A database schema diagram tells you that you are using PostgreSQL. An ADR tells you why you chose PostgreSQL over MongoDB, what trade-offs you accepted, and what circumstances would warrant revisiting that choice.
ADRs are not design documents. They are not RFCs. They are deliberately lightweight — a single decision, captured in a structured format, written in plain language. A good ADR takes 15 minutes to write, not an hour.
The Cost of Undocumented Decisions
We have all lived with the consequences of undocumented decisions. A new engineer joins the team and asks, "Why are we using Redis for session storage instead of database-backed sessions?" Nobody remembers. The person who made the decision left the company two years ago. So the team either spends a week re-evaluating the decision from scratch, or — worse — they just accept it without understanding, building on assumptions they cannot verify.
The costs compound over time:
- New team members guess at intent. Without documented reasoning, onboarding engineers fill gaps with assumptions. Sometimes those assumptions are wrong, and they build features that subtly conflict with the original architectural vision.
- Settled debates get re-litigated. Every six months, someone proposes switching to the alternative that was already evaluated and rejected. The team spends hours in meetings covering the same ground, because there is no record of the original analysis.
- Decisions get accidentally reversed. A well-meaning refactor undoes a deliberate choice because the developer did not know it was deliberate. The system breaks in ways that are difficult to diagnose because the failure mode was exactly the one the original decision was designed to prevent.
- Client handoffs lose critical context. When a consulting engagement ends and the client's internal team takes over, undocumented decisions become landmines. The internal team cannot distinguish intentional constraints from incidental ones.
ADRs eliminate these problems. They are cheap to write and extraordinarily valuable to read.
The Format We Use
We keep the format minimal. Every ADR follows this structure:
Title: A short noun phrase describing the decision. We number them sequentially.
Status: Proposed, Accepted, Deprecated, or Superseded (with a link to the replacement).
Context: The situation that motivated the decision. What problem are we solving? What constraints exist? What forces are in tension?
Decision: The choice we made, stated clearly and directly.
Consequences: What follows from this decision — both positive and negative. Every architectural decision has trade-offs, and we name them explicitly.
Here is a real example from a recent client project:
ADR-007: Use PostgreSQL Over MongoDB for Multi-Tenant SaaS Platform
Status: Accepted
Context: The platform requires multi-tenant data isolation, complex reporting queries across tenant data, ACID transactions for financial operations, and a flexible schema that can accommodate tenant-specific customizations. The team has strong experience with both PostgreSQL and MongoDB. The data model includes deeply relational entities (users, organizations, invoices, line items, payments) with referential integrity requirements.
Decision: We will use PostgreSQL with row-level security for tenant isolation.
Consequences: We gain strong transactional guarantees, mature tooling for complex queries and reporting, and row-level security as a proven tenant isolation mechanism. We accept that schema migrations require more planning than a schemaless approach, and that certain document-oriented access patterns will require JSONB columns rather than native document storage. If we encounter a high-volume write workload that exceeds PostgreSQL's capabilities, we will evaluate a dedicated write-optimized store for that specific use case rather than replacing the primary database.
That is the entire document. It took ten minutes to write. It will save hours of discussion over the life of the project.
Where ADRs Are Most Valuable
Not every decision warrants an ADR. Choosing between two equivalent utility libraries probably does not. But decisions that shape the system's trajectory — that are expensive to reverse, that constrain future choices, or that will puzzle future engineers — absolutely do.
Here are the patterns where we find ADRs most consistently valuable:
Database selection and data architecture. The choice of primary data store affects nearly every other technical decision. ADRs capture not just what you chose, but what workload characteristics drove the choice.
Authentication and authorization strategy. Auth decisions are notoriously difficult to reverse. Whether you are choosing between Cognito and Auth0, between JWTs and opaque tokens, between RBAC and ABAC — document it. Your future self will thank you when a security audit asks why you made the choices you did.
API design philosophy. REST vs. GraphQL vs. gRPC. Versioning strategy. Pagination approach. These decisions create contracts that external consumers depend on. The reasoning behind them matters.
Monolith vs. microservices (and everything in between). This is the decision most likely to be re-litigated. An ADR that clearly articulates the team size, deployment constraints, and operational capacity that drove the decision can prevent months of circular debate.
State management in client applications. Server state vs. client state. Which state management library, and why. What goes in local state vs. global state. These decisions shape every feature that follows.
Deployment and infrastructure strategy. Serverless vs. containers vs. traditional servers. The trade-offs are real and context-dependent. For example, one of our ADRs reads:
ADR-012: Use Serverless Over Containers for Event-Driven API — We chose AWS Lambda behind API Gateway because the workload is bursty with long idle periods, cold start latency is acceptable for this use case, and the team is small enough that minimizing operational overhead outweighs the need for fine-grained runtime control.
Cross-platform mobile strategy. Another common ADR from our practice:
ADR-003: Use React Native Over Native for Healthcare App — We chose React Native because the application is form-heavy with standard UI patterns, the client needs to ship on both platforms within a fixed timeline, the development team has deep React expertise, and the app does not require low-level device integration beyond camera and Bluetooth LE, both of which have mature React Native libraries.
How ADRs Improve Client Relationships
For a consulting studio like Apptitude, ADRs are not just an internal engineering practice — they are a client deliverable. Every project we hand off includes a complete set of ADRs, and clients consistently tell us it is one of the most valuable artifacts they receive.
ADRs create transparency during the engagement. Clients can see not just what we are building, but why we are making the choices we are making. This builds trust and reduces the anxiety that comes from delegating technical decisions to an external team.
ADRs enable knowledge transfer at handoff. When the client's internal team takes ownership of the codebase, ADRs give them a map of the decision landscape. They know which decisions were load-bearing and which were incidental. They know what trade-offs were accepted and what would trigger a reassessment.
ADRs provide future-proofing. Technology evolves. The right decision today may not be the right decision in two years. ADRs make it easy to revisit decisions when circumstances change, because the original context is preserved. If a decision was made because of a specific constraint — a small team, a tight deadline, a particular traffic pattern — and that constraint no longer applies, the ADR makes it obvious that reassessment is warranted.
Keeping ADRs Lightweight and Sustainable
The most common failure mode for ADRs is making them too heavy. If writing an ADR feels like writing a thesis, the team will stop writing them. Here are the principles we follow to keep ADRs sustainable:
Keep them short. An ADR should fit on a single screen. If you are writing more than a page, you are probably trying to capture multiple decisions in one document. Split them up.
Write them at decision time. Do not try to retroactively document decisions from six months ago. Write the ADR when the decision is fresh and the context is clear. If you are in a meeting where a significant technical decision is made, someone should write the ADR before the day is over.
Store them with the code. We keep ADRs in a docs/decisions directory in the repository. They are versioned with the code, reviewed in pull requests, and searchable with standard tools. They are not in a wiki that nobody checks.
Use a template. The five-field format (title, status, context, decision, consequences) removes the blank-page problem. You do not have to decide what to write — you just fill in the sections.
Accept imperfection. A brief, slightly informal ADR is infinitely more valuable than a perfectly polished ADR that never gets written. Do not let the perfect be the enemy of the good.
ADRs and Engineering Culture
ADRs are a reflection of a deeper principle: that engineering decisions should be intentional, transparent, and reversible. Writing an ADR forces you to articulate your reasoning, which often reveals gaps in your thinking before they become gaps in your architecture.
At Apptitude, ADRs are part of a broader culture of deliberate decision-making. We believe that the best engineering teams are not the ones that make the most decisions — they are the ones that make decisions well, communicate them clearly, and know when to revisit them.
If you are not documenting your architectural decisions, start today. Pick the next significant technical choice your team faces, spend 15 minutes writing an ADR, and commit it to your repository. You will be surprised how quickly it becomes indispensable.