ADRs

Engineering teams should create an ADR whenever they make a sufficiently complicated or significant architectural decision. Use the link above to create a new ADR using our standard template.

One of the most effective ways of documenting architecture decisions is through Architectural Decisions Records (ADRs). ADRs were first evangelised by Michael Nygard in his blog post […]. An ADR consists of a short text file (usually one to two pages long) describing a specific architecture decision.

• “

Software Architecture: The Hard Parts"

See also…

• https://adr.github.io

• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

• https://github.com/joelparkerhenderson/architecture-decision-record

Example

From “Software Architecture: The Hard Parts":

2022-11-16: Use Orchestration for Primary Ticket Workflow

# Context

For the primary ticket workflow, the architecture must support easy tracking of lost or mistracked messages, excellent error handling, and the ability to track ticket status. Either an orchestration solution illustrated in Figure 1 or a choreograph solution illustrated in Figure 2 will work.

[Figure 1]

[Figure 2]

# Decision

We will use orchestration for the primary ticketing workflow.

We modeled orchestration and choreography and arrived at the trade-offs in Table 1

[Table 1]

# Consequences

Ticketing workflow might have scalability issues around a single orchestrator, which should be reconsidered if current scalability requirements chage