Architecture Decision Records (ADRs) are short, structured text documents that capture significant software design choices made by a development team. They explain what decision was made, the context behind it, and the consequences—both positive and negative—of that choice. By storing these records directly inside a software repository alongside the source code, teams maintain a permanent, searchable history of their architectural evolution over time.
Imagine buying a historic house that has been remodeled by five different owners over fifty years. You notice an odd, diagonal wall in the middle of the dining room that narrows the hallway. Frustrated by the awkward layout, you decide to knock it down during a weekend renovation project, only to realize too late that the wall contained the central electrical conduit and a critical load-bearing pillar for the upper floor. If the previous owners had kept a simple house logbook in a kitchen drawer detailing why that wall was placed diagonally, you would have saved thousands of dollars and prevented structural damage. ADRs serve as that kitchen drawer logbook for software codebases.
In fast-paced software engineering teams, developers constantly face choices: Should we use MySQL or MongoDB? Should we handle state with React Context or a third-party library? Should our Node.js API use REST or GraphQL? Without ADRs, these discussions happen in ephemeral Slack channels, verbal meetings, or pull request comments that get buried over time.
ADRs matter on a daily basis because they prevent Chesterton's Fence syndrome in software development—where engineers delete or refactor complex code simply because they do not understand why it was built in the first place. When a new engineer joins the team, reading the docs/adr folder provides an instant historical overview of why the architecture looks the way it does. Furthermore, when someone suggests changing a core design pattern, the team can reference past ADRs to avoid repeating old mistakes or re-debating settled decisions.
Below is an example of a Markdown-formatted ADR stored inside a Node.js and Express backend repository, documenting the decision to implement connection pooling for MySQL database queries:
# ADR-004: Implement MySQL Connection Pooling in Express API ## Status Accepted ## Date 2024-03-15 ## Context Our Express.js API server handles heavy user traffic spikes during peak hours. Currently, each incoming HTTP request creates an individual database connection to MySQL and closes it after executing the SQL query. Creating new TCP connections on every request adds roughly 40ms of handshake latency and occasionally exhausts available database sockets under peak loads. ## Decision We will replace single database connections with a MySQL connection pool using the `mysql2/promise` library in Node.js. Incoming Express route handlers will borrow an active connection from the pool rather than initiating a new handshake. ## Code Implementation
javascript
// db.js - Database connection pool configuration
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
host: process.env.DB_HOST || 'localhost',
user: process.env.DB_USER || 'app_user',
password: process.env.DB_PASSWORD || 'secret',
database: process.env.DB_NAME || 'production_db',
waitForConnections: true,
connectionLimit: 10,
queueLimit: 0
});
module.exports = pool;
## Consequences ### Positive - Reduces API response latency by eliminating per-request connection overhead. - Prevents connection starvation under concurrent user spikes. ### Negative - Requires careful tuning of `connectionLimit` to avoid exhausting MySQL server memory. Architecture Decision Records turn silent assumptions and lost meeting notes into active, version-controlled documentation. By capturing the context, alternatives, and trade-offs of every major choice directly in your repository, you ensure that your team's collective wisdom survives employee turnover, rapid scaling, and code refactoring.
Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!
Originally published on my blog. You can read the alternative breakdown here.
