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 Industry Solutions 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 own template by adjusting the configmap k5-designer-backend-configmap in the cluster. The property defaultDecisionTemplate contains the template.

❗️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

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.

❗️info

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

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.

Connect decisions to model elements​

Decisions can 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 Related model elements tab of the decision's instance page.

To connect a decision to model elements:

  1. Navigate to the decision's instance page
  2. Open the Related model elements tab
  3. Click on the Add Model Element button
  4. Select the model elements you want to connect to the decision

Connected model elements are then visible in the Related model elements 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.