# Tracking architecture decisions **URL:** \ **Category:** SX solution development\ **Tags:** best-practice\ **Created:** [April 7, 2023, 6:29am UTC](https://discuss.coding.social/t/tracking-architecture-decisions/313 "2023-04-07T06:29:06Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![aschrijver](https://discuss.coding.social/user_avatar/discuss.coding.social/aschrijver/32/3_2.png) [@aschrijver](https://discuss.coding.social/u/aschrijver)\ **Post date:** [April 7, 2023, 6:29am UTC](https://discuss.coding.social/t/tracking-architecture-decisions/313/1 "2023-04-07T06:29:06Z")
| | | | --- | --- | | Name | **Architecture Decision Records** | | Summary | Strategic cooperation whereby different projects, groups or communities, while each operating independently, agree to collaborate and evolve an ecosystem collectively. They anticipate each other’s needs, align roadmaps, features, etc. | | Keywords | Architecture, Software, Non-functional requirements, Documentation, Collaboration | | Type | [Best-practice](https://discuss.coding.social/c/documentation/practices/9) | | FSDL position | [Architecture design / Architecture notebook](https://discuss.coding.social/t/brainstorm-components-of-the-free-software-development-lifecycle-wiki-post/53/2) | This is a placeholder best-practice that was inspired by @Ryuno-Ki who has experience in using them. ---
**Author:** ![Ryuno-Ki](https://discuss.coding.social/user_avatar/discuss.coding.social/ryuno-ki/32/44_2.png) [@Ryuno-Ki](https://discuss.coding.social/u/Ryuno-Ki)\ **Post date:** [April 7, 2023, 2:05pm UTC](https://discuss.coding.social/t/tracking-architecture-decisions/313/2 "2023-04-07T14:05:32Z")
Thanks for opening this thread. In the past I have worked with [https://adr.github.io/](https://adr.github.io/) in professional settings. It proved to be useful using the wiki software that was provided by the client. The elements are crucial: - Title (a summary to make it easier to search) - Timestamp (allows for assessing the relevance) - Status (e.g. proposed, accepted, rejected, deprecated, superseded) - Context (what is the environment in which a decision has to be made, constraints and similar) - Decision (out of several options which one is the way the team agreed to continue with?) - Consequences (what are the next action items caused by the decision) Writing ADRs allows us to have a track record about decisions that were made in the past. Since I’m working in web frontend industry, this could be the decision on using SCSS vs. CSS-Modules vs. CSS-in-JS for example. There were instances that made us reconsider a decision because the environment changed and we had to adapt. Having written down the context and possible options saved us time on research. Institutionalising knowledge is also beneficial for team transitions (easier to onboard new people, less reliant on a single person and so on). I can highly recommend adopting this practice. ---
**Author:** ![aschrijver](https://discuss.coding.social/user_avatar/discuss.coding.social/aschrijver/32/3_2.png) [@aschrijver](https://discuss.coding.social/u/aschrijver)\ **Post date:** [April 7, 2023, 3:03pm UTC](https://discuss.coding.social/t/tracking-architecture-decisions/313/3 "2023-04-07T15:03:07Z")
> [@Ryuno-Ki](#): > > The elements are crucial I looked at some templates e.g. the ones listed [in this repo](https://github.com/joelparkerhenderson/architecture-decision-record) by Joel Henderson. There’s quite a big difference in formality, the amount of fields and information to track. Some lend themselves more for large organizations, multiple teams, complex software. For instance [Decision record template by Jeff Tyree and Art Akerman](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-jeff-tyree-and-art-akerman/index.md) would be overkill for most FOSS projects. There’s a big risk that the formality will lead to the documentation chore not happening. But your field list looks reasonable. The [Decision record template by Michael Nygard](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md) appeals to me, mostly free-form text, only tracking paragraphs: - **Title** - **Status** : E.g. proposed, accepted, rejected, deprecated, superseded. - **Context** : What is motivating this decision or change? - **Decision** : What is the change that we’re proposing and/or doing? - **Consequences** : What becomes easier or more difficult to do because of this change? A slight variation is the [Decision record template for Alexandrian pattern](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-for-alexandrian-pattern/index.md) (a long-used pattern). Yet another variation is [Decision record template by Paulo Merson](https://github.com/pmerson/ADR-template), where some additional process is described: > ### Usage guidelines > > - Each ADR is a plain text, 1-2 page document > - ADRs should be numbered > - ADRs should be stored within each software project repo > - Create a separate repo for crosscutting ADRs > - Track ADRs in the backlog > - Review ADRs > - Create ADRs for _significant_ design decisions The [ADR markdown template](https://github.com/pmerson/ADR-template/blob/master/ADR-template.md) itself is just as simple, having free-form text and a few paragraph sections. Here’s an example (click to expand): > **ADR 005: Use a CQRS Pattern** > > > # ADR 005: Use a CQRS Pattern > > > > We have a microservice architecture with several REST services that would need to read and write data. > > Sometimes it’s difficult to design those services to do both tasks efficiently. > > In the Farmacy Food system, the design of writes (commands) is primarily concerned with the integrity of data and business rules, > > whereas the design of reads (queries) has performance (response time) as a key requirement. > > > > ## Decision > > > > We will use the [CQRS pattern](https://udidahan.com/2009/12/09/clarified-cqrs/) applied to microservices with this design: > > > > - an independently deployed service takes care queries. It reads data from a query view that is optimized for data reads. > > (“Optimized” means using DB technologies and techniques that favor performance, such as: NoSQL, denormalized view, memory cache, sharding, replication.) > > - an independently deployed service takes care of commands. It may be a REST service that gets POST commands or a reactive service > > that subscribes to a pub-sub topic and gets messages that updates the primary database for the scope of that service. > > - a batch component (example: K8S cron job or logic activated by database-triggered events) synchronizes the data between > > the primary database and the query views. The frequency of data synchronization varies–it can be trigger-based, > > every 5 minutes, every hour, …, once a day, etc. > > > > In our design, we have used CQRS for: > > > > - Inventory > > - Orders > > - Subscription > > > > ## Rationale > > > > We expect that the app will issue far more query requests than commands. For example, the inventory is checked in many customer > > operations, such as looking at a catalog meal item. > > The [CQRS pattern](https://udidahan.com/2009/12/09/clarified-cqrs/) is used to address performance (response time) > > requirements on queries. > > > > ## Status > > > > Proposed > > > > ## Consequences > > > > - The CQRS pattern uses data replication for query views and hence _eventual consistency_. Therefore, query services may > > operate on stale data (during the interval between data synchronization from primary db and query view). > > - Need to monitor data synchronization tasks, with notification and proper action in case of failure. * * * Only a bit more elaborate template is [MADR](https://adr.github.io/madr/), or Markdown Any Decision Records. It comes in a long and short form, listing options and where the long form indicates per option what is good and what is bad. MADR has several tools available for management (both for the CLI and a GH integration to make ADR management easier). ---
**Author:** ![aschrijver](https://discuss.coding.social/user_avatar/discuss.coding.social/aschrijver/32/3_2.png) [@aschrijver](https://discuss.coding.social/u/aschrijver)\ **Post date:** [April 5, 2024, 4:24am UTC](https://discuss.coding.social/t/tracking-architecture-decisions/313/4 "2024-04-05T04:24:41Z")
Some more examples of ADR’s in-the-wild. In this case using ADR’s for an open standard specification, namely JSON Schema. Here’s the issue on adopting ADR’s: > > > We had a \[Discussion\](https://github.com/json-schema-org/community/discussions/1…5) to see if we should adopt Architecture Decision Records (ADRs). There were no strong objections and a few clear benefits. > > We should add ADRs to this repo, the spec repo, and the test repo. > I suggested we use ISO date as the file prefix as opposed to incrementing numbers, as this is less likely to cause a conflicts. This approach was also \[adopted for proposals\](https://github.com/OAI/OpenAPI-Specification/pull/2604#issuecomment-854020447) in OAI. > > Work to be done: > > \- \[x\] Set up template as per https://adr.github.io/madr for this repo - (#21 ) > \- \[x\] Add ADR badge to this repo - (https://github.com/json-schema-org/community/commit/59adf96a3ebd246246021a6ae7437949de1c0c49) > \- \[x\] Update CONTRIBUTING.md in this repo - (#33 ) > \- \[x\] Create minimal Issue and PR templates in this repo (https://github.com/json-schema-org/community/pull/36) > \- \[\] Add the same to all repos\* > > \\\* I'm not currently clear if "all repos" is appropriate. For example, it wouldn't make sense for the mostly empty vocabularies repo. I think it makes sense to put these in a \`.github\` repo for the org, but I'm not sure they are currently working as \[expected\](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). Here are the specs ADR’s: [https://github.com/json-schema-org/json-schema-spec/tree/main/adr](https://github.com/json-schema-org/json-schema-spec/tree/main/adr) (While there aren’t too many decisions in the list, I found it interesting to mention this as example of using ADR’s beyond direct code projects).