Skip to main content

Architectural Decisions

Introduction​

Architectural decisions shape the foundation of a software system, influencing its structure, scalability, and maintainability. These decisions, tracked via Architectural Decision Records (ADRs) address key aspects such as technology choices, system design patterns, and trade-offs betwenn different approaches. Documenting them ensures transparency, alignment, and long-term traceability.

In IBM DevOps Solution Workbench, you can create, maintain, and track the status of ADRs, as well as link them to other parts of your project.

Overview​

This page provides you with an overview of all architectural decisions within the project.

You can view the ADR itself as well as details of the decision by clicking on the respective label within the table or using the table row action Open. This opens the decision's instance page, where you can edit the ADR file directly in the editor, and view its details:

  • Details: Master data of the decision (see also Create a decision); all writable fields are editable here as well.
  • Loop: Here, you can find links and connections to other parts of the project.

The editor automatically displays a template for architectural decisions as a guidance for writing. You can also apply your custom template by changing the default template within the Admin Settings.

❗️info

Template changes will also affect existing ADR documents.

Additionally, you can find the following actions in the overflow menu of the details

  • Share decision:This open a dialog where you can copy the decision's URL or share it directly via email
  • Delete decision: Delete the whole decision (see [below](link to the delete section further down))

ADR Sidekick​

Get assistance writing your architectural decision, tailored to your needs.

Making and documenting architectural decisions is crucial, but it can be time-consuming. The ADR Sidekick streamlines this process by helping you draft clear, structured architectural decision records (ADRs) based on best practices, your preferred ADR template, as well as the context of the content you have already added.

With the ADR Sidekick, you can:

  • Auto-fill parts of your ADR, based on your provided template
  • Summarize sections of your ADR
  • Improve clarity and consistency accross your ADR documentation
❗️info

To make use of the ADR sidekick, it is required that you have an OpenAI API key set up for your user. To do that, please follow the steps described here.

The ADR Sidekick capability is based on gpt4o, provided by OpenAI. Read more about AI infused capabilities in the IBM DevOps Solution Workbench here.

Use the ADR sidekick​

To trigger the ADR Sidekick, click in to the section or select the text you need assistance for and click on the purple AI button in the top right corner of the editor. Based on the part you selected, the ADR Sidekick then suggests the best actions for the context you provided. Choose the action that best fits your needs and the Sidekick then will generate corresponding text that you can directly insert to the right place or copy for later.

If you can find no suitable option in the list of suggested actions, you can also choose the button for custom actions. This way, you can define your own action and execute it to complement your ADR. Besides that, the sidekick offers a refine action that you can execute on top of the generated text to make sure it fully reflects your needs.

Customize the ADR sidekick​

The behavior of the ADR sidekick can be customized by adding technical policies or writing guidelines within the global Admin Settings. Using those settings will allow you to create alignment, compliance and consistency on technical or writing related rules for the users working with the ADR sidekick. If custom rules are provided, the ADR sidekick will consider those when suggesting actions as well as when generating text for the decision.

Create a decision​

To create a new decision, use the Create decision capability to the right of the table tool bar.

Decisions are defined using the following master data:

  • Title: The title of the model element (required)
  • File name: Unique identifier for the ADR that is used in the repository to where it is saved. If not specified by the user, the Title is used as a base for the File name (required)
  • Status: Current status of the decision (Proposed, Accepted, Superseded, Deprecated), new decisions are always in status Proposed (required)
  • Summary: A short summary of the decision or of its outcome, respectively (optional)
  • Tags: To tag the model element (optional)

ADRs are saved in the form of .md (Markdown) files in the repository.

Edit a decision​

All editable fields can be directly edited within the details on the respective decision's instance page. Alternatively, you can edit the details of a decision by using the table row action Edit in the Decisions overview page.

Delete a decision​

The capability to delete a decision can be found in overflow menu at the end of each table row, as well as in the overflow menu of the details section of each model element.

⚠warning

You can only delete a decision if it is in the status Proposed. You will need to confirm the action before the selected decision is permanently deleted.

Loop​

Connect decisions to other decisions​

You can link decisions with other decisions to manage existing relationships between them and make successive decisions visible. Decisions that are connected to a decision are displayed in the Loop tab of the decision details on a decision's instance page.

To connect a decision to another decision:

  1. Navigate to the decision's instance page
  2. Open the Loop tab
  3. Click on the Add decision button
  4. Select the decision(s) you want to connect to the decision and specify their link type in the dropdown below

Decisions can be linked via the following link types:

  • Superseded by: The linked decision overrides the current decision.
  • Supersedes: The linked decision is overridden by this decision.
  • Relates to: Any other relationship between these two decisions.

Connected decisions are then visible in the Decisions part of the Loop tab, providing a clear overview of which other decisions are connected to this architectural decision. You can click on any decision card to navigate directly to its instance page.

❗️info

You can remove links to decisions at any time by using the remove action on connected decisions in the Decisions section of the Loop tab in the decision details.

Connect decisions to model elements​

Decisions can also be connected to relevant model elements to establish traceability and context within your project. Model elements that are connected to a decision are displayed in the Loop tab of the decision details on a decision's instance page.

To connect a decision to model elements:

  1. Navigate to the decision's instance page
  2. Open the Loop tab
  3. Click on the Add model element button
  4. Select the model element(s) you want to connect to the decision

Connected model elements are then visible in the Model elements part of the Loop tab, providing a clear overview of which parts of your project are affected by or related to this architectural decision. You can click on any model element card to navigate directly to its instance page.

❗️info

You can remove links to model elements at any time by using the remove action on connected model elements in the Model elements section of the Loop tab in the decision details.

Allows users to add, view, and remove external URLs in the "Links" section of the Loop panel for decisions. Users can easily associate relevant resources by adding links through a simple interface, and can access these resources by clicking on the link