Simpler.Grants.gov Public Wiki
Grants.govSimpler.Grants.govGitHubDiscourse
  • 👋Welcome
  • GET INVOLVED
    • Why open source?
    • How to contribute code
    • How to file issues
      • Report a bug
      • Request a feature
      • Report a security vulnerability
    • Community guidelines
      • Code of Conduct
      • Reporting and removing content
      • Incident response protocol
    • Community events
      • Fall 2024 Coding Challenge
        • Event Submissions & Winners
      • Spring 2025 Collaborative Coding Challenge
        • Event Submissions & Winners
    • Communication channels
  • Product
    • Roadmap
    • Deliverables
      • 🏁Static site soft launch
      • 🏁Static site public launch
      • 🏁GET Opportunities
      • 🏁Open source onboarding
      • 🏁Co-Design Group planning
    • Decisions
      • ADR Template
      • ADRs
        • Dedicated Forum for Simpler.Grants.gov Community
        • Recording Architecture Decisions
        • Task Runner for the CI / CD Pipeline
        • API Language
        • Use Figma for design prototyping
        • ADR: Chat
        • DB Choices
        • API Framework and Libraries
        • Back-end Code Quality Tools
        • Front-end Language
        • Communications Tooling: Wiki Platform
        • Use Mural for design diagrams and whiteboarding
        • Ticket Tracking
        • Front-end Framework
        • Front-end Code Quality Tools
        • Front-end Testing & Coverage
        • Backend API Type
        • Front-end Testing & Coverage
        • Deployment Strategy
        • Use U.S. Web Design System for components and utility classes
        • FE server rendering
        • Use NPM over Yarn Architectural Decision Records
        • U.S. Web Design System in React
        • Communications Tooling: Video Conferencing
        • Back-end Production Server
        • Communications Tooling: Analytics Platform
        • Commit and Branch Conventions and Release Workflow
        • Cloud Platform to Host the Project
        • Infrastructure as Code Tool
        • Data Replication Strategy & Tool
        • HHS Communications Site
        • Communications Tooling: Email Marketing
        • Communications Tooling: Listserv
        • Use Ethnio for design research
        • Uptime Monitoring
        • Database Migrations
        • 30k ft deliverable reporting strategy
        • Public measurement dashboard architecture
        • Method and technology for "Contact Us" CTA
        • E2E / Integration Testing Framework
        • Logging and Monitoring Platform
        • Dashboard Data Storage
        • Dashboard Data Tool
        • Search Engine
        • Document Storage
        • Document Sharing
        • Internal Wiki ADR
        • Shared Team Calendar Platform
        • Cross-Program Team Health Survey Tool
        • Adding Slack Users to SimplerGrants Slack Workspace
        • Repo organization
        • Internal knowledge management
        • Migrate Existing API Consumers
      • Infra
        • Use markdown architectural decision records
        • CI/CD interface
        • Use custom implementation of GitHub OIDC
        • Manage ECR in prod account module
        • Separate terraform backend configs into separate config files
        • Database module design
        • Provision database users with serverless function
        • Database migration architecture
        • Consolidate infra config from tfvars files into config module
        • Environment use cases
        • Production networking long term state
    • Analytics
      • Open source community metrics
      • API metrics
  • DESIGN & RESEARCH
    • Brand guidelines
      • Logo
      • Colors
      • Grid and composition
      • Typography
      • Iconography
      • Photos and illustrations
    • Content guidelines
      • Voice and tone
    • User research
      • Grants.gov archetypes
  • REFERENCES
    • Glossary
  • How to edit the wiki
Powered by GitBook
On this page
  • About ADRs
  • Why do we need to document architecture decisions?
  • What constitutes an architecture decision?
  • Examples of architecture decisions
  • ADR Process
  • Acknowledgements and Further Reading

Was this helpful?

Edit on GitHub
  1. Product

Decisions

PreviousCo-Design Group planningNextADR Template

Last updated 3 months ago

Was this helpful?

About ADRs

Why do we need to document architecture decisions?

Developing software involves making lots of decisions. Documenting these decisions and their outcomes achieves several important goals:

  1. Knowledge Preservation: Architectural decisions capture the rationale behind important choices made during the design and development process. They serve as a reference point for future developers, allowing them to understand the thinking and context behind the architecture. Without proper documentation, critical knowledge can be lost over time as team members change or move on to other projects.

  2. Communication and Collaboration: Documentation helps facilitate communication among team members and stakeholders. It allows the product owner, developers, and other stakeholders to share a common understanding of the software's architecture, its components, and the reasoning behind specific decisions.

  3. Decision Transparency: ADRs provide greater insight into the choices made throughout the project. It helps team members and stakeholders understand the factors considered, alternatives evaluated, and the trade-offs involved in the decision-making process. This transparency fosters trust, enables better collaboration, and allows for informed discussions and feedback.

  4. Risk Management: Documenting key decisions also allows project stakeholders to assess the potential impact of architectural changes, identify dependencies, and evaluate the consequences of modifying specific components. By having a clear understanding of the trade-offs associated with each option, teams can make more informed decisions and mitigate potential risks associated with changes or enhancements.

  5. Improved Maintainability and Adaptability: Software projects evolve over time due to changing requirements, new features, or technological advancements. Documentation ensures that future developers can understand the architecture's design principles, patterns, and constraints. It enables future maintainers to modify or extend the codebase in a consistent and coherent manner, reducing the risk of introducing unintended side effects or architectural drift.

  6. Onboarding and Knowledge Transfer: When new team members join a project, ADRs serve as a valuable resource for onboarding. They provide insights into the design choices, patterns, and best practices employed in the codebase. Documentation reduces the ramp-up time for new team members and helps them become productive more quickly.

What constitutes an architecture decision?

Almost all of engineering and code development involves making choices, so how do you know when a particular choices rises to the level of an architecture decision and requires an ADR?

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.

Source:

Another way to recognize when making a decision related to your project constitutes an architecture decision is to ask yourself three questions about that decision:

  1. Does this decision affect the structure, direction, or outcome of the project?

  2. Would someone unfamiliar with the project ask me to explain why I made this decision?

  3. Were there other viable alternatives I could have chosen?

If you answer "Yes" to at least one of these questions, then you've likely just made an architectural decision, and you should create an ADR to explain why you made that choice. Other contributors (and your future self) will thank you for it.

Examples of architecture decisions

While architecture decisions come in all shapes and sizes, some common examples include:

  • Setting up the repository's main file structure

  • Selecting a critical library, tool, or platform

  • Adopting a certain analytical framework or algorithm

  • Choosing not to build a particular feature

ADR Process

When an architectural decision needs to be recorded, please use the following steps:

  1. Identify the approvers for this decision, i.e. individuals or groups who must sign off on the decision before the ADR can be merged (ideally this happens before work starts on the ADR)

  2. Draft an ADR in a branch named after the ticket, then open a Pull Request (PR)

  • The ADR should use the status "Active"

  1. Invite the approvers to review the PR and provide feedback or approve the decision

  2. Once the approvers have signed off on the decision, merge the PR into the main branch

  3. Create any follow-up tickets that are needed to implement the decision outlined in the ADR (if necessary)

Acknowledgements and Further Reading

Use the {YYYY-MM-DD}-{description}.md naming convention and copy the into the directory (name the file with the date it was created, which may differ from the date the decision was made, PR was merged, or file was last modified)

If this decision deprecates an ADR, update its status to indicate the reason (e.g. "Superseded By [xxx](yyyymmdd-xxx.md)"), and move it to the directory

ADR GitHub Organization
Create a new ADR ticket in GitHub
template
adr
deprecated
ADR GitHub Organization
Joel Parker Henderson's ADR repo
GitHub Blog - Why Write ADRs