{"id":184,"date":"2025-03-21T09:19:42","date_gmt":"2025-03-21T07:19:42","guid":{"rendered":"https:\/\/thewebsiteengineer.com\/?p=184"},"modified":"2025-03-21T10:15:52","modified_gmt":"2025-03-21T08:15:52","slug":"what-is-an-adr-and-how-we-use-it-at-the-website-engineer","status":"publish","type":"post","link":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/","title":{"rendered":"What is an ADR and how we use it at The Website Engineer"},"content":{"rendered":"<p>At The Website Engineer, we recognise that informed architectural decisions are fundamental to delivering scalable and efficient web development solutions.\u00a0To systematically document these decisions, we employ Architectural Decision Records (ADRs), ensuring clarity and consistency across our projects.<\/p>\n<h2><strong>Understanding Architectural Decision Records (ADRs)<\/strong><\/h2>\n<p>An Architectural Decision Record (ADR) is a document that captures a significant architectural decision made during a project, along with its context and consequences.\u00a0This practice provides a structured approach to recording the rationale behind key decisions, facilitating better communication among stakeholders and serving as a valuable reference for future project phases.<\/p>\n<h2><strong>Our Approach to ADRs at The Website Engineer<\/strong><\/h2>\n<p>In our commitment to delivering top-tier web solutions, we integrate ADRs into our development workflow as follows:<\/p>\n<ol>\n<li><strong>Context Establishment<\/strong>:\u00a0We begin by clearly defining the problem or requirement that necessitates an architectural decision. This includes understanding the project&#8217;s goals, constraints, and the specific challenges we aim to address.<\/li>\n<li><strong>Decision Drivers<\/strong>:\u00a0We identify the key factors influencing our decision, such as scalability, performance, security, and maintainability. Recognising these drivers ensures that our choices align with both project requirements and client expectations.<\/li>\n<li><strong>Option Analysis<\/strong>:\u00a0Our team evaluates multiple architectural options, considering the pros and cons of each. This thorough analysis allows us to make informed decisions that best suit the project&#8217;s unique needs.<\/li>\n<li><strong>Decision Documentation<\/strong>:\u00a0Once an option is selected, we document the decision in detail, including the reasoning behind it and any anticipated consequences. This record serves as a transparent reference for all stakeholders.<\/li>\n<li><strong>Review and Confirmation<\/strong>:\u00a0We periodically review our ADRs to ensure they remain relevant and effective as the project evolves. This iterative process allows us to adapt to new insights or changing requirements.<\/li>\n<\/ol>\n<h2><strong>Benefits of Using ADRs<\/strong><\/h2>\n<p>Implementing ADRs within our projects offers several advantages:<\/p>\n<ul>\n<li><strong>Enhanced Communication<\/strong>:\u00a0ADRs provide a clear record of decisions, facilitating better understanding among team members and stakeholders.<\/li>\n<li><strong>Knowledge Sharing<\/strong>:\u00a0They serve as educational tools for new team members, offering insights into the project&#8217;s architectural evolution.<\/li>\n<li><strong>Informed Future Decisions<\/strong>:\u00a0Documenting past decisions helps prevent the repetition of discussions and allows for more informed decision-making in future projects.<\/li>\n<\/ul>\n<h2><strong>ADRs in Action: A Practical Example<\/strong><\/h2>\n<p>Consider a scenario where we need to choose a database solution for a client&#8217;s expanding user base.\u00a0An ADR would document the context (e.g., the need for scalability), decision drivers (e.g., data consistency, integration ease), considered options (e.g., PostgreSQL, MongoDB, Amazon DynamoDB), the chosen solution, and the rationale behind it.\u00a0This structured documentation ensures that all stakeholders understand the decision and its implications.<\/p>\n<p>Here\u2019s our template to create an ADR:<\/p>\n<pre><code class=\"language-bash\"># Example Title: Database Choice for User Data\n\n## Context and Problem Statement\n\nWe need a scalable database to store and manage user data efficiently as our user base grows.\n\n## Decision Drivers\n\n* Scalability\n* Data consistency\n* Ease of integration with existing services\n\n## Considered Options\n\n* PostgreSQL\n* MongoDB\n* Amazon DynamoDB\n\n## Decision Outcome\n\nChosen option: **PostgreSQL** because it provides strong data consistency and aligns well with our need for complex queries.\n\n### Consequences\n\n* **Good:** Supports ACID compliance, enhancing data reliability.\n* **Bad:** May require more tuning to achieve high performance with large datasets.\n\n### Confirmation\n\nWe\u2019ll confirm this decision through periodic load tests and performance reviews as the user base scales.\n\n## Pros and Cons of the Options\n\n### PostgreSQL\n\n* **Good:** ACID compliance, robust community support.\n* **Neutral:** Setup and tuning can be time-consuming.\n* **Bad:** Lacks native horizontal scaling.\n\n### MongoDB\n\n* **Good:** Schema flexibility, horizontal scaling.\n* **Bad:** No ACID compliance across collections, limiting data integrity.\n\n## More Information\n\nFor additional details, see the database performance evaluation [here](link-to-evaluation).\n<\/code><\/pre>\n<h2>Inspiration<\/h2>\n<p>Drawing inspiration from AWS&#8217;s robust architectural decision-making process, we&#8217;ve adapted their systematic approach to ADRs while maintaining our unique perspective at The Website Engineer. Like AWS, we recognize that methodical documentation and clear decision-making processes are fundamental to building scalable, reliable systems. Our ADR implementation reflects AWS&#8217;s commitment to well-documented architecture decisions, fostering a culture of intentional design and collaborative problem-solving that has proven successful in large-scale enterprise environments.<\/p>\n<p><a href=\"https:\/\/docs.aws.amazon.com\/prescriptive-guidance\/latest\/architectural-decision-records\/adr-process.html\">https:\/\/docs.aws.amazon.com\/prescriptive-guidance\/latest\/architectural-decision-records\/adr-process.html<\/a><\/p>\n<h2><strong>Conclusion<\/strong><\/h2>\n<p>At The Website Engineer, our utilisation of ADRs reflects our dedication to meticulous planning and transparent communication in web development.\u00a0This practice not only enhances our internal processes but also assures our clients of our commitment to delivering scalable and well-considered solutions.\u00a0For potential new hires, understanding our ADR process offers insight into our collaborative and methodical approach to tackling architectural challenges.<\/p>\n<p>By embedding ADRs into our workflow, we uphold a culture of continuous improvement and shared knowledge, positioning ourselves to meet the evolving needs of our clients effectively.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>At The Website Engineer, we recognise that informed architectural decisions are fundamental to delivering scalable and efficient web development solutions.\u00a0To systematically document these decisions, we employ Architectural Decision Records (ADRs), ensuring clarity and consistency across our projects. Understanding Architectural Decision Records (ADRs) An Architectural Decision Record (ADR) is a document that captures a significant architectural &#8230; <a title=\"What is an ADR and how we use it at The Website Engineer\" class=\"read-more\" href=\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\" aria-label=\"Read more about What is an ADR and how we use it at The Website Engineer\">Read more<\/a><\/p>\n","protected":false},"author":4,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[11],"tags":[],"class_list":["post-184","post","type-post","status-publish","format-standard","hentry","category-culture"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v24.7 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>What is an ADR? How 10x Engineers document their work<\/title>\n<meta name=\"description\" content=\"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"What is an ADR? How 10x Engineers document their work\" \/>\n<meta property=\"og:description\" content=\"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\" \/>\n<meta property=\"og:site_name\" content=\"The Website Engineer\" \/>\n<meta property=\"article:published_time\" content=\"2025-03-21T07:19:42+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2025-03-21T08:15:52+00:00\" \/>\n<meta name=\"author\" content=\"webeditor\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"webeditor\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\"},\"author\":{\"name\":\"webeditor\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/c96580a5fb7ec07dfef80b78d7a5047b\"},\"headline\":\"What is an ADR and how we use it at The Website Engineer\",\"datePublished\":\"2025-03-21T07:19:42+00:00\",\"dateModified\":\"2025-03-21T08:15:52+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\"},\"wordCount\":609,\"publisher\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/#organization\"},\"articleSection\":[\"Culture\"],\"inLanguage\":\"en-ZA\"},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\",\"url\":\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\",\"name\":\"What is an ADR? How 10x Engineers document their work\",\"isPartOf\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/#website\"},\"datePublished\":\"2025-03-21T07:19:42+00:00\",\"dateModified\":\"2025-03-21T08:15:52+00:00\",\"description\":\"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.\",\"inLanguage\":\"en-ZA\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/\"]}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#website\",\"url\":\"https:\/\/thewebsiteengineer.com\/\",\"name\":\"The Website Engineer\",\"description\":\"\",\"publisher\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/thewebsiteengineer.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-ZA\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#organization\",\"name\":\"The Website Engineer\",\"url\":\"https:\/\/thewebsiteengineer.com\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-ZA\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/thewebsiteengineer.com\/wp-content\/uploads\/sites\/2\/2023\/09\/cropped-cropped-WebEng-Icon-Navy-BG-favicon-192x192-1.png\",\"contentUrl\":\"https:\/\/thewebsiteengineer.com\/wp-content\/uploads\/sites\/2\/2023\/09\/cropped-cropped-WebEng-Icon-Navy-BG-favicon-192x192-1.png\",\"width\":192,\"height\":192,\"caption\":\"The Website Engineer\"},\"image\":{\"@id\":\"https:\/\/thewebsiteengineer.com\/#\/schema\/logo\/image\/\"}},{\"@type\":\"Person\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/c96580a5fb7ec07dfef80b78d7a5047b\",\"name\":\"webeditor\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-ZA\",\"@id\":\"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/4dbc80b999f7f24953c8e85d78b4506c?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/4dbc80b999f7f24953c8e85d78b4506c?s=96&d=mm&r=g\",\"caption\":\"webeditor\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"What is an ADR? How 10x Engineers document their work","description":"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/","og_locale":"en_US","og_type":"article","og_title":"What is an ADR? How 10x Engineers document their work","og_description":"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.","og_url":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/","og_site_name":"The Website Engineer","article_published_time":"2025-03-21T07:19:42+00:00","article_modified_time":"2025-03-21T08:15:52+00:00","author":"webeditor","twitter_card":"summary_large_image","twitter_misc":{"Written by":"webeditor","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/#article","isPartOf":{"@id":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/"},"author":{"name":"webeditor","@id":"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/c96580a5fb7ec07dfef80b78d7a5047b"},"headline":"What is an ADR and how we use it at The Website Engineer","datePublished":"2025-03-21T07:19:42+00:00","dateModified":"2025-03-21T08:15:52+00:00","mainEntityOfPage":{"@id":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/"},"wordCount":609,"publisher":{"@id":"https:\/\/thewebsiteengineer.com\/#organization"},"articleSection":["Culture"],"inLanguage":"en-ZA"},{"@type":"WebPage","@id":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/","url":"https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/","name":"What is an ADR? How 10x Engineers document their work","isPartOf":{"@id":"https:\/\/thewebsiteengineer.com\/#website"},"datePublished":"2025-03-21T07:19:42+00:00","dateModified":"2025-03-21T08:15:52+00:00","description":"Discover how Architectural Decision Records (ADRs) enhance clarity and efficiency in web development at The Website Engineer for scalable solutions.","inLanguage":"en-ZA","potentialAction":[{"@type":"ReadAction","target":["https:\/\/thewebsiteengineer.com\/blog\/what-is-an-adr-and-how-we-use-it-at-the-website-engineer\/"]}]},{"@type":"WebSite","@id":"https:\/\/thewebsiteengineer.com\/#website","url":"https:\/\/thewebsiteengineer.com\/","name":"The Website Engineer","description":"","publisher":{"@id":"https:\/\/thewebsiteengineer.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/thewebsiteengineer.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-ZA"},{"@type":"Organization","@id":"https:\/\/thewebsiteengineer.com\/#organization","name":"The Website Engineer","url":"https:\/\/thewebsiteengineer.com\/","logo":{"@type":"ImageObject","inLanguage":"en-ZA","@id":"https:\/\/thewebsiteengineer.com\/#\/schema\/logo\/image\/","url":"https:\/\/thewebsiteengineer.com\/wp-content\/uploads\/sites\/2\/2023\/09\/cropped-cropped-WebEng-Icon-Navy-BG-favicon-192x192-1.png","contentUrl":"https:\/\/thewebsiteengineer.com\/wp-content\/uploads\/sites\/2\/2023\/09\/cropped-cropped-WebEng-Icon-Navy-BG-favicon-192x192-1.png","width":192,"height":192,"caption":"The Website Engineer"},"image":{"@id":"https:\/\/thewebsiteengineer.com\/#\/schema\/logo\/image\/"}},{"@type":"Person","@id":"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/c96580a5fb7ec07dfef80b78d7a5047b","name":"webeditor","image":{"@type":"ImageObject","inLanguage":"en-ZA","@id":"https:\/\/thewebsiteengineer.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/4dbc80b999f7f24953c8e85d78b4506c?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/4dbc80b999f7f24953c8e85d78b4506c?s=96&d=mm&r=g","caption":"webeditor"}}]}},"acf":[],"_links":{"self":[{"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/posts\/184","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/comments?post=184"}],"version-history":[{"count":6,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/posts\/184\/revisions"}],"predecessor-version":[{"id":192,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/posts\/184\/revisions\/192"}],"wp:attachment":[{"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/media?parent=184"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/categories?post=184"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/thewebsiteengineer.com\/wp-json\/wp\/v2\/tags?post=184"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}