Consider and set up a structure for Architecture Decision Records (ADR)

[tdlowden]

As a developer of the system, I'd like to be able to keep track of system architecture decisions and understand why they were made, including what trade-offs and alternatives might have existed at the time. I'd also like to keep track of these in a place that I can refer back to later for historical context.

Acceptance Critera

• ADR template is selected
• ADR folder is created in this repo (notifications-api)
• ADR template Markdown file is stored for future use

Implementation Sketch

There are several templates and recommendations we can draw from, including the following:

• GitHub's ADR Template and Process
• AWS' ADR Process
• 18F's recommendations (which refer to GitHub as an example)
• What is outlined on Wikipedia's article on Architectural Decisions

There are several others as well, including the template the cloud.gov team follows:

# *[short title of solved problem and solution]*

**User Story:** *[ticket/issue-number]* <!-- optional -->

*[context and problem statement]*
*[decision drivers | forces]* <!-- optional -->

## Considered Alternatives

* *[alternative 1]*
* *[alternative 2]*
* *[alternative 3]*
* *[...]* <!-- numbers of alternatives can vary -->

## Decision Outcome

* Chosen Alternative: *[alternative 1]*
* *[justification. e.g., only alternative, which meets KO criterion decision driver | which resolves force force | ... | comes out best (see below)]*
* *[consequences. e.g., negative impact on quality attribute, follow-up decisions required, ...]* <!-- optional -->

## Pros and Cons of the Alternatives <!-- optional -->

### *[alternative 1]*

* `+` *[argument 1 pro]*
* `+` *[argument 2 pro]*
* `-` *[argument 1 con]*
* *[...]* <!-- numbers of pros and cons can vary -->

### *[alternative 2]*

* `+` *[argument 1 pro]*
* `+` *[argument 2 pro]*
* `-` *[argument 1 con]*
* *[...]* <!-- numbers of pros and cons can vary -->

### *[alternative 3]*

* `+` *[argument 1 pro]*
* `+` *[argument 2 pro]*
* `-` *[argument 1 con]*
* *[...]* <!-- numbers of pros and cons can vary -->

Whatever we choose, we ought to keep it lightweight to start with and build from that.

Security Considerations

ADRs, by their very nature, contain many details about a system and often delve into a variety of related bits of information. This includes trade-offs of taking one approach over another, oftentimes with implications to the security and stability of the overall system. Therefore, we'll want to be mindful of the following:

• If the ADR is in reference to something that is publicly known and/or directly related to details that are already publicly shared, it is likely okay to have the ADR itself public (e.g., an ADR discussing a change in how invite expirations might work).
• If the ADR is in reference to something that is a change in infrastructure details (especially if dealing with internal program information), where only the outcome can potentially be shared publicly, the ADR itself will have to be kept internally.

[ccostino]

Flagging these resources as particularly useful references (they are linked to on the GitHub page):

• How to Create ADRs - and How Not To
• The Markdown ADR (MADR) Template Explained and Distilled
• The Ultimate Guide to Architectural Decision Records

There are a host of design considerations and anti-patterns noted in the first article, and great ideas for what to include in a template in the second and third.