The document discusses architectural decision records (ADRs), emphasizing their role in capturing the rationale behind design choices and promoting sustainable architectural practices. It provides guidelines for documenting decisions, including context, decisions, and consequences, along with specific examples and formats for effective communication. Additionally, it highlights the importance of understanding historical and technical contexts in making informed architectural decisions.

1. How did we get here?
@rdohms
A guide to Architectural Decision Records
📷 pixabay

2. “We need this feature completed by Friday”
— Product, always.

3. “Let’s just get this done, and we can fix it next week”
— Developer 1, the optimist.

4. “Who did this? Why did they do it this way? WTF!?”
— Developer 1, the year after.

5. “Oh, yeah, I think I remember this”
— Developer 1, after doing a git blame.

6. Have you been here before?
📷 negative space

7. Rafael Dohms
• Chloe’s Father
• Speaker
• That annoying Object Calisthenics guy
Architect @ GetFeedback
@rdohms
! "

8. Sustainable Architectural Design Decisions (InfoQ)
“Capturing the rationale of decisions is difficult and
has a high cost”

9. “Sustainable projects rely on Architectural
Knowledge”
Sustainable Architectural Design Decisions (InfoQ)

10. “Understanding where you came from can help you
figure out what your new options are.”

11. “Decisions are shaped based on the context,
understanding that context allows you to understand
those decisions and make better ones.”

12. We did it this way because of <<reason>>, if
<<condition>> happened we can now get rid of this code.
Otherwise, consider this <<consequence>> of doing it this
way.
📷 olia danilevich

13. ADR
Architectural Decision Record

14. Context
Decision
Consequences
ADR0001 - Record Decisions
Date: 2020-12-01
Status
Approved

15. Context
• Describe facts
• Outline the forces at play
• What is happening?
• What are the motivations to make a decision?
• What kind of pressure or conflicting priorities are at play?
• Political, social and technological

16. When creating the new platform, time pressure forced us to take some
shortcuts when it came to the design of our RESTful APIs (APIs from here on).
This ADR tries to rectify that, realign us and create a guideline for all future
APIs.
We subscribe to the Richardson Maturity Model for APIs. We are currently
comfortably floating somewhere near level 2 and are wondering if the effort
involved to get to level 3 is worth it.
To better support and decouple the Backend development from the Frontend
development, we want to introduce the Backend for Frontend (BFF)
architectural pattern in the form of a GraphQL component. That component will
serve all Frontend requests and talk to the backend microservices. Our
preferred implementation for that component is Apollo (Javascript). Apollo
currently reaps no benefits from having a maturity level 3 API since all relations
need to be defined by hand and are not deduced from HATEOAS.
Historical and political context
Technical context
Context
ADR0025 - RESTful API standards

17. Decision
• Use the active voice: “We will…”
• Explain the response to the forces described in the context
• Be clear about what the decision entails

18. Decision
{
"someProperty": "with a value",
"channels": [
"web-passive",
"web-active"
]
}
We will adopt a new JSON naming structure.
• properties should follow camelCase
• constant values should use kebab-case
Clear decision in active voice
Easy to read examples
ADR0013 - Use standard case for all json payloads

19. Consequences
• What the context will be after the decision is applied
• Side effects of decision
• Positive
• Negative
• Neutral
• What will not be possible anymore?
• What other decisions will be influenced?

20. Projects implementing this convention should not need to migrate downwards
anymore. Thus it is unnecessary, from a production environment perspective,
to have a down migration.
Any down migration may be kept in repositories for development purposes,
allowing tests to migrate back and forth speeding up the test suite in general.
However, the down migrations should never be part of deploy or
rollback process and should never be executed in production environments.
Consequences, positive.
Exceptions and how to handle them
Consequences
ADR0005 - Always ensure non-breaking migrations

21. Other formats
• Micheal Nygard Standard
Simple, straight forward, complete
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• MADR
Long, with many details: drivers, alternatives, pro/cons
https://adr.github.io/madr/
• Y-Statements
In the context of <use case/user story u>, facing <concern c> we decided for <option o> to achieve
<quality q>, accepting <downside d>.
https://www.infoq.com/articles/sustainable-architectural-design-decisions/

22. Your Decision
Designing Implementing
Write them before or after?

23. “ADRs are great conversation starters”

24. “ADRs are great to log Tech Debt”

25. Context
Decision
Consequences
ADR0001 - Record Decisions
Date: 2020-12-01
Status
Approved
When will we pay Tech Debt?
What was product’s restrictions?
Which other features are blocked now?

26. When and for what should I write ADRs for?

27. Impactful
changes
When and for what should I write ADRs for?

28. Impactful
changes
Bad
Decisions
When and for what should I write ADRs for?

29. Impactful
changes
Bad
Decisions
Technical
Debt
When and for what should I write ADRs for?

30. Impactful
changes
Bad
Decisions
Technical
Debt
Unconventional
Implementations
When and for what should I write ADRs for?

31. Old Decision
Superseded by
New Decision
Can we change an ADR?
Replaced by

32. Proposed Accepted
Deprecated
Superseded: by 0002
Amended: by 0002
*: by 0002

33. /docs/adr
Where should I put ADRs?

34. acme/user-managment acme/billing acme/content-creator acme/…

35. acme/user-managment acme/billing acme/content-creator acme/…
ADR-0003: Do not implement authentication layer for MVP

36. acme/user-managment acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP

37. acme/user-managment acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard

38. acme/user-managment
acme/architecture-chapter
acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard

39. acme/user-managment
acme/architecture-chapter
acme/billing acme/content-creator acme/…
acme/backend-chapter acme/frontend-chapter
ADR-0003: Do not implement authentication layer for MVP
ADR-0005: Adopt the Doctrine Coding Standard
ADR-0007: All API dates should be formatted in RFC3339

40. adr-tools
https://github.com/npryce/adr-tools

41. Demo

42. @rdohms
https://doh.ms
Thank you.
We are hiring!