DEV Community: Adam Banaszkiewicz

Why ADRs Matter: Capturing Architectural Decisions with Purpose

Adam Banaszkiewicz — Mon, 07 Apr 2025 09:30:00 +0000

Why ADRs Matter: Capturing Architectural Decisions with Purpose

Have you ever looked at a piece of code and asked yourself, "Why did we do it this way?"

Welcome to the world of Architecture Decision Records (ADR) — a simple but powerful technique to preserve the "why" behind technical decisions in your projects.

What Problem Does ADR Solve?

In every software project, decisions are made. We decide which framework to use, why a service communicates over REST instead of gRPC, or why a particular domain model was split into two bounded contexts. But over time, people leave, contexts shift, and the reasoning behind those choices gets lost.

ADR is the answer to the question “Why did we do this?”

It gives a voice to decisions, capturing not just the what, but more importantly, the why. It’s not enough to read the code — ADRs give you the intent behind it.

What Is an ADR?

An Architecture Decision Record is a short text document describing a single architectural decision. That’s it. Each ADR should be:

Immutably stored – Once created, the document should not change. And should not be removed!
Dated and versioned – You need to know when the decision was made.
Status-driven – A decision can be Proposed, Accepted, Deprecated, Superseded, or Obsolete.
Tracked over time – The collection of ADRs forms a historical timeline of the architecture.

The Structure of an ADR

A typical ADR document includes the following sections:

Title – Short and descriptive (e.g. “Use PostgreSQL as main data store”)
Status – Current state of the decision (Accepted, Rejected, etc.)
Context – The background and forces at play when the decision was made.
Decision – What was decided, clearly stated.
Consequences – What happens as a result of this decision.

If you're wondering where the "why" is captured — it's mainly in the Context section. This is where you describe the situation, constraints, trade-offs, or previous options that led to this particular choice. Without it, the decision is just a fact. With it, it becomes a rationale.

Why Not Just Use Jira Tickets or Docs?

Because those are too broad or ephemeral. ADRs are focused, atomic, and always close to the codebase. They’re typically stored in the repository itself, usually in a folder like /docs/adr/, making them accessible to everyone in the team — including reviewers, future contributors, and stakeholders.

They’re also just Markdown. This simplicity ensures they’re easy to read, version, and integrate into your tooling.

Sylius ADRs

Looking for real-world examples? Sylius, an open-source e-commerce platform, uses ADRs to capture and document its architectural decisions. These records are publicly available in their GitHub repository and provide a great reference for how ADRs can be structured and written in practice.

👉 Check out the full list here: https://github.com/Sylius/Sylius/tree/2.1/adr

GitHub ❤️ ADRs

Did you know that GitHub officially encourages the use of ADRs?

Check out GitHub’s own ADR guide which provides templates and best practices for writing and managing ADR documents. This standardization is helping teams across the world stay aligned on their architectural decisions.

Make ADRs Work For You: Pistacy.io

If you're looking for a more structured and collaborative approach to managing your ADRs, Pistacy.io has you covered.

Pistacy is a free Software Architecture Platform for developers and architects, focused on organizing and maintaining software architecture documentation in one place. The platform includes a dedicated ADR management module that supports:

✅ Creating and editing ADR documents
🔄 Managing document lifecycle using state machines (e.g. from Proposed → Accepted → Obsolete)
🔁 Replacing, archiving, or marking ADRs as obsolete
🔄 Converting accepted RFCs into ADRs
📥 Importing Markdown ADRs directly from your repository using the Pistacy API

This makes ADRs not just useful, but manageable at scale.

Don’t let important decisions fade into git history. Start writing ADRs — and if you want to level up your documentation game, give Pistacy.io a try.

5 tips: How to find time to improve dev skills?

Adam Banaszkiewicz — Wed, 12 Jul 2023 06:23:44 +0000

Developer's life is difficult. Neverending need of improving skills and learning new things can be painful, especially when You have familly, school, or other time consuming private things.

This small tips are proposals of how to find time in life, which is full of private time consuming things.

1. Buy Yourself a book

First step, something that is required to begin. What do You want to know, to learn? Find a book of that topic and buy it. Remember, this book will be Your trigger to do something. Place this book in some visible place. For example I placed book next to my monitor. This reminds me that I need to use it.

2. Read a book when "sitting over the water"

This is not a Joke - but looks like :) Man has some behavior, that forces us to read something while sitting on the toilet seat :D Why not use that 10 minutes to read few pages of book? The book that lies next to monitor ;)

3. Watch 10-15 minutes tutorials/vlogs/dev videos awaiting for wife/kids before bed

This tip is little dificult when You have more than one kid. When You kid or wife is taking a bath, You have 15 minutes to take some action. Why not watch some short videos on Youtube? There are plenty channels with short videos, just take it!

4. Watch 5-10 minutes tutorials/vlogs/dev videos at breakfast

That's my favourite! My wife goes to work when I eat breakfast. I have 10 minutes, which I can use to watch tutorials lesson or some vlog.

5. Make use of break at work

Nowadays, working remotely we don't have stimulants outside, so we can focus on ourselves in home and use break at work to whatever we want to. While eating dinner, You can also listen some audiobook.

Conclusion

As You probably notice, the point is to find small periods of time in Your routine, and place there some additional activity. I've started reading a book when "sitting over the water" and in that way I've readed 3 books over past year.

Most important thing is to start, and do the baby steps. Remember, take one day at a time. If this small activities begin Your new routine, after one Year you'll notice that You have learned new technology and You have read couple times more books then in last year.

It is possible to create CMS using DDD?

Adam Banaszkiewicz — Tue, 20 Jun 2023 06:44:08 +0000

CMS on it's basis is a software that resolve one generic problem - managing content on website. Joomla, WordPress and other popular systems are simple and generic, there is no domain there - just creating posts, showing them at partcular URL... But, are You sure?

When I started writing own CMS, I decided to try to do this using Domain Driven Design. At the beginning it was really painful, because of the mindset that was set by popular systems. Now, after research, hours of modelling and prototyping, I changed my mindset. Let me show You how I've done that.

From this article You will find out:

Where is Domain in CMS?
How to change thinking to find Domain in CMS?
How to crystalize behaviors from CMS?
Does every CMS needs a DDD?

This article assumes You have basic knowledge of DDD and software architecture. Some parts of the research and analysis of Domain will be ommited here, to allows author create short but contentfull article.

Where is the Domain in CMS?

The basic functionality of CMS is to create some content and show it in browser. To create content You need some form and controller that handles that request, and saves data in database. CRUD right? But, there is a catch - what If You could describe "how system behaves" instead of how it's build or where it stores data? System creates content, publish this content upon URL, assigns content to category etc. So, what not just think of how system behaves instead of where to save the data?

Every software system is built to provide some solution to business problem. CMS is same thing - here the business problem is to allow users to add and modyfy content of the website. Just like in shop, You can "add product to cart" or "increase quantity of product in cart". In CMS You can "create new post" and "publish it".

Every behavior of the system is already a part of Your Domain. The point is, You have to think of any system in categories of behaviors, not technical things. From those behaviors You can find out the Bounded Contexts, new Aggregates came up as new flowers on spring :)

Yes, You are right, not everywhere :) Part of Our job as an architects is to decide where, in system, will be better to use DDD, and where simple CRUD. When You have 'save node', 'update node' "behaviors" - You don't need DDD :)

The better way to find the "domain" is a Event Storming - it is a powerfull modelling method. But it works only when You can do the session with at least Your one coleague - doing sessions alone is a terrible idea :D

DDD in CMS in real project

To show You real project, I need to describe You the business logic that stands upon that project. I'll show You my way of doing this in the Tulia CMS.

Domain logic of Tulia CMS

The content elements are called Nodes. Those Nodes can be translatable to foreign languages, can has attribites that store simple details of the Node (for example: image, some links, content of the node etc.). Nodes can be assigned and unassigned to categories. Nodes has titles and slugs, that are generated from the titles. Nodes also have purposes that describes what for this node was created, and one Node can have imposed multiple purposes. Ok, let's move on.

From the description above You can pick behaviors that describe the system. We have:

create node
add/update/remove attribute
assign/unassign category
change title
impose/discontinue purpose

Aggregate

We have behaviors, so we can create aggregate! For this article I select only the Node behaviors, so is simpler to find the Aggregate, but always be aware of the "Aggregate rules" when You create it!

final class Node {
    public static function create(
        string $id,
        string $title,
        array $locales,
    ): self;

    public function changeTitle(
        string $title,
        ?string $alias = null,
    ): void;

    public function addAttribute(
        string $code,
        mixed $value,
    ): void;

    public function publish(
        ImmutableDateTime $publishedAt,
        ?ImmutableDateTime $publishedTo = null,
    ): void;

    /** Replace all purposes with new ones **/
    public function persistPurposes(
        string ...$purposes,
    ): void;

    public function assignToMainCategory(
        string $category,
    ): void;
}

Above code is a simplified version of real life Aggregate, that You can see here: https://github.com/tuliacms/cms/blob/master/src/Cms/Node/Domain/WriteModel/Model/Node.php.

The Node has title, attributes, category and purposes. As You might notice, there is no "content" - because content in Tulia CMS is a one of the Attributes. Static factory method is used to create objects in Tulia CMS, and $locales store all available locales in system (remember? Node is translatable).

The most important lesson here, there are no "technical things" here, such save/update, setters etc. - only behaviors. This is how system behaves, this is how system allows users to do anything with it. It helps You to find the Domain in any business problem, even so generic as CMS. You just have to stop thinking about things as technical system and force Yourself to think about the systems behaviors.

Does every CMS has a Domain?

Yes. Every system, because business has own Domain, is specialized in something. Not even CMS but every system, has some domain. Every system that solves any business problem has a domain, but question is... Does every CMS needs a DDD?

Does every CMS needs a DDD?

No, not every. If You build system that is simple, have only CRUD-like operations, or is way too generic (like reusable component for example), You do not need a DDD here. DDD affects of how much the code You need to write, and it's not worth it.

But, if Your system has specific behaviors, like in Tulia CMS, if exposes places where developers can extend this behavior - this is a good way to think about DDD here.

Conclusion

Every business-specific problem can be modelled with DDD, only if is not a CRUD :) Developing Tulia CMS was a really different approach to modelling system with DDD, because it wasn't obvious at first look where the domain in CMS is. When I changed my thinking to behaviour of system, everything changed.

If You are interested in how the whole domain od Tulia CMS is made, feel free to go here: https://github.com/tuliacms/cms/tree/master/src/Cms/Node. You can find whole Domain Model, with Aggregates, relationships between Entities, separation to Read Model and Write Model, and much more.