Decision Logs User Guide

January 7, 2026 · View on GitHub

This guide explains how to use the Decision Logs feature to manage Architecture Decision Records (ADRs) in your data modelling workspace.

Overview

Decision Logs allow you to document and track architectural decisions using the MADR (Markdown Architectural Decision Records) format. Each decision captures:

The context and problem being addressed
The decision made
Considered alternatives
Consequences of the decision
Status and lifecycle

Requirements

Decision Logs require SDK 1.13.1 or later. Check your SDK version in Settings > About.

Creating a Decision

From the Decision Panel

Navigate to a domain or workspace
Open the Decisions tab
Click New Decision
Fill in the required fields:
- Title: A concise description of the decision
- Category: The type of decision
- Context: Background information and the problem being solved
- Decision: The actual decision made

Decision Categories

Category	Use For
Architecture	System structure, patterns, components
Technology	Tools, frameworks, languages, platforms
Process	Development workflows, team practices
Security	Authentication, authorization, data protection
Data	Storage, schemas, data flows
Integration	APIs, external systems, protocols

Decision Status Workflow

Decisions follow a defined lifecycle:

Draft → Proposed → Accepted/Rejected
                        ↓
              Deprecated/Superseded

Status Descriptions

Status	Description
Draft	Work in progress, not yet ready for review
Proposed	Ready for team review and discussion
Accepted	Approved and should be followed
Rejected	Reviewed but not approved
Deprecated	No longer recommended but still valid
Superseded	Replaced by a newer decision

Changing Status

Open a decision
Click the status dropdown in the workflow section
Select the new status
Confirm the change

Note: Only valid transitions are allowed:

Draft → Proposed, Rejected
Proposed → Accepted, Rejected, Draft
Accepted → Deprecated, Superseded
Rejected → Draft

Decision Options

Document the alternatives you considered:

In the decision editor, scroll to Considered Options
Click Add Option
For each option, provide:
- Title: Option name
- Description: What this option entails
- Pros: Advantages of this option
- Cons: Disadvantages of this option

Decision Numbering

Decisions are automatically numbered in sequence:

ADR-0001
ADR-0002
etc.

The number is assigned when the decision is created and never changes.

Linking Decisions

Link decisions that are related:

Open a decision
In the Related Decisions section, click Add
Search for and select related decisions

Superseding Decisions

When a decision replaces another:

Open the new decision
Change status to Accepted
Open the old decision
Change status to Superseded
Select the new decision as the superseding decision

Link to Knowledge Base articles:

Open a decision
In the Related Knowledge section, click Add
Search for and select related articles

Domain Association

Decisions can be associated with specific domains:

When creating a decision, select a Domain
The decision will appear in that domain's Decisions tab
Decisions can also be created from within a domain

RACI Matrix

Document stakeholders using the RACI model:

Field	Description
Authors	People who wrote the decision
Deciders	People with authority to approve
Consulted	Subject matter experts consulted
Informed	People notified of the decision

Search and Filter

Search

Use the search box to find decisions by:

Title
Context
Decision content

Filters

Filter the decision list by:

Status: Show only Draft, Proposed, etc.
Category: Show only Architecture, Security, etc.

Click Filters to open the filter panel, then select your criteria.

Sorting

Sort decisions by:

Number: ADR number (default, newest first)
Title: Alphabetical
Status: By status value
Updated: By last update date

Exporting Decisions

Export to Markdown

Export decisions in MADR format:

Open a decision
Click Export → Export as Markdown
The markdown file will download

Export Format

The exported markdown follows the MADR template:

# ADR-0001. Use React for Frontend

**Status:** Accepted  
**Category:** Technology  
**Date:** 2024-01-15

**Deciders:** John Doe, Jane Smith

## Context

We need to choose a frontend framework...

## Decision

We will use React for our frontend...

## Considered Options

### Option 1: React

Popular component library...

**Pros:**

- Large ecosystem
- Good documentation

**Cons:**

- Learning curve

## Consequences

Team needs React training...