Architecture decisions (ADRs)

Diagrams show what the architecture is; decisions record why. CRAYON-C4 has first-class Architecture Decision Records (ADRs): short, structured records — context, decision, consequences — linked to the very elements they justify. When one of those elements is removed, the decision is flagged for review instead of silently going stale.

Decisions are a Pro feature. Your data is never gated: a project's decisions always round-trip through JSON export, import and backup on every tier — Pro unlocks the management screens.

Work with them in two places: select any element and its details pane carries a Decisions section (list what applies, start a new decision pre-linked to that element, or link an existing one — each opens in place, without leaving the diagram), and the Decisions screen in the app menu holds the full record table. In the viewers the decision opens as a read-only floating card — drag it by its header, resize it by its corner; it reopens where and how you left it. The edit dialog is resizable the same way.

What a decision looks like

Each record follows the standard MADR-style shape:

Title — what was decided ("Use Postgres for the order store").
Status — Proposed, Accepted, Deprecated, or Superseded.
Date — when it was decided.
Context / Decision / Consequences — markdown sections: the issue that motivated it, the change made, and what becomes easier or harder.
Categories — your own classification ("data", "infrastructure", …), as many per decision as apply. The vocabulary is whatever your project's decisions use: type in the category field and pick from the list, or type a new name to create it. Categories stay editable after acceptance — they classify the record, they aren't its content.
Linked elements — the parts of the model this decision is about.
A stable id (adr-0001, adr-0002, …) that never changes, whatever gets renamed.

Accepted means immutable. A decision is editable while it is Proposed. The moment you accept it, the record is frozen: its title, date and content can never change again, and it cannot be deleted. Changing course is done the ADR way — record a new decision and mark the old one superseded by it, or deprecate it. Links and review stamps stay manageable, because they are traceability about the model, not the decision's content.

Linking decisions to the model

A decision can link to any mix of:

C4 elements — persons, systems, containers, components, at any level;
Connections — the relationships between elements, not just the elements;
Deployment items and instances — deployment nodes, infrastructure, and container instances.

Links are many-to-many: one decision can cover several elements, and one element can carry several decisions. Every link stores both the element's stable id and its name and type as they were at link time — so a decision can always state what it links to, even after the element is deleted.

Select an element and its details pane lists the decisions that apply — open one in place, start a new decision pre-linked to that element, or link an existing record. Diagrams themselves stay clean: no decision markers are drawn on the canvas. Inside a decision, each link row shows whether the element is still live and opens the diagram where it appears.

The record table

The Decisions screen is a records-management table: sortable columns (id, title, status, linked items, date) and filters on free text (title, id, categories, linked-item names), status — including the Needs review queue — a specific linked element, categories, and a date range. A row opens the record; New decision starts a draft.

Two filters worth knowing:

Include children — widens the linked-element filter to everything underneath the picked element: its C4 children at every depth, the connections touching them, and the deployment items and instances that deploy any of them. Filter by a System and you see every decision recorded anywhere inside it.
Categories combine with AND — pick several and only decisions carrying all of them remain, so "data" + "infrastructure" narrows rather than widens.

When a linked element is removed

Deleting an element never deletes or edits your decisions — you decide whether a decision still holds:

Removing a linked element (or a connection a delete cascades away) flags every affected decision Needs review. The review queue is the "Needs review" status filter on the Decisions table.
The removed element's last-known name stays on the record — no decision is ever left pointing at an id with no name.
If the delete removed a decision's last live link, you're asked explicitly what should happen: keep it as a flagged historical record, re-link it to another element, or deprecate it.
When a decision still holds, press Still valid — the flag clears and the record is stamped with the confirmation date.

Only removal triggers review. Renames and other modifications never flag a decision — links follow the stable id, so they simply keep up.

Superseding a decision

Decisions replace each other in a straight line: mark a record superseded by a newer one and the two are chained (supersedes / supersededBy). Statuses cascade along the chain, and the whole chain is shown on each record so you can walk from the original decision to the current one. Deleting a mid-chain record bridges its neighbours, keeping the line intact.

Exporting decisions

From the Decisions table — the Export… button exports exactly the records the table currently shows (your filters apply), grouped your way: pick any combination of category, status and linked element, and arrange the nesting order by dragging. Download as Markdown, or Print / Save as PDF for the same document on paper. A decision with several categories or linked elements appears under each of them — unless a filter excludes that bucket, in which case it stays gone. The table offers the same grouping directly (Group…), with collapsible groups (per group, per level, or all). When grouping by linked element, the buckets follow the C4 containment chain by default — System › Container › Component — with a connection filed under its endpoints' common ancestor and a deployed container under the element it deploys; untick Nest by C4 hierarchy for a flat element list.

In the document export — the export page's Written details tab (under "What to export", now split into Document, Diagram images and Written details tabs) carries the Decisions (ADRs) options, both off by default:

A separate Decisions overview section at the end of the document — every record with its status, date, categories, linked items (removed ones shown by their last-known name), supersede chain and full Context / Decision / Consequences.
Name each decision on the linked elements' rows — every listed element, relationship and deployment item gains a Decisions column naming its records.
Decision statuses — pick which lifecycle states are exported (say, Accepted only); the pick narrows the overview and the element rows alike.

Decisions as their own file

Decisions ride inside the project bundle, but they can also travel on their own — for handing a decision set to another team, versioning it separately, or pushing it into another project without touching that project's diagrams.

Extract — the Export dialog's Decisions file (.json) button downloads the project's full decision set as one small data file (table filters don't apply — a filter is a view, not an extract). The file is kind-marked (crayon-c4-decisions) and follows a published schema, schema/v1/crayon-c4-decisions.schema.json.
Import into an existing project — the Decisions table's Import… button reads a decisions file or a whole project export (its decisions are extracted automatically). You review what would change before anything is written: new decisions are added, existing ones are updated by id where the file's record differs, and decisions the file doesn't mention are never removed. The imported records pass through the same healing and validation every project load runs.
Backup and restore — the all-projects backup carries each project's decisions inside its bundle, and restore handles bundles with or without them; nothing extra to configure.

Git-native files

ADRs live in your project like everything else and round-trip through the project JSON export. The Markdown (.zip) export additionally writes each decision as its own file in an adr/ folder beside the images — MADR-style markdown with a small frontmatter block — so decisions are diffable and reviewable in normal pull requests. The same decision always serializes to the same bytes: a re-export with no changes is a clean diff.

Where next

C4 model structure — the elements and connections decisions link to.
Deployment — the deployment items and instances a decision can cover.
Export — where the adr/ folder lands in the Markdown export.