Skip to content
/ Michaël Hompus

, , ,
Chapter 9 is your decision timeline. It records the important architectural choices you made along the way, so you can see what was decided, why, and which options were not picked. This chapter often starts small, but it grows as the system grows. In this article I explain what belongs in chapter 9, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

This post is about chapter 9: Architectural decisions, the second chapter in the “Reusables, decisions, and qualities” group.

Chapter 8 captured reusable patterns and practices. Chapter 9 captures the choices that shape the system, including the strategy choices from chapter 4.

I treat this chapter as a timeline. It often starts small, because you have not made many decisions yet. But it is still the start of the decision trail, and every meaningful choice you make later can land here.

read more…
/ Michaël Hompus

, , , ,
Chapter 8 is the patterns and practices chapter. It captures the reusable concepts that keep your domain code lean and your runtime scenarios readable: security, resilience, observability, integration rules, and other "plumbing" that should be consistent. In this article I explain what belongs in chapter 8, what to keep out, a minimal structure you can copy, plus a small example from Pitstop.

This post is about chapter 8: Cross-cutting concepts, the first chapter in the “Reusables, decisions, and qualities” group.

Chapters 5, 6, and 7 described structure, runtime, and deployment. Chapter 8 is where I document the reusable ideas that make those chapters readable and maintainable.

I think of chapter 8 as the patterns and practices chapter. It is often the “non-functional” code. Not the business logic, but everything needed to make that core behave correctly.

read more…
/ Michaël Hompus

, , , , , ,
This post is about chapter 7: Deployment view, the last chapter in the "How is it built and how does it run" group. Chapter 7 answers: where do your building blocks run, in which environments, and with which settings? This chapter turns "it works on my machine" from tribal knowledge into shared documentation. No more guessing which settings matter or where things actually run.

This post is about chapter 7: Deployment view, the last chapter in the “How is it built and how does it run” group.

Small milestone: chapter 7 means we are past the halfway point of the 12 arc42 chapters.

Chapter 5 gave us the map (building blocks). Chapter 6 showed how those blocks collaborate at runtime. Chapter 7 answers the next question: where do those blocks run, in which environments, and with which settings?

read more…
/ Michaël Hompus

, , , , , ,
Chapter 6 describes runtime behavior: how building blocks collaborate in the scenarios that matter, including alternatives, exceptions, and the bits that tend to hurt in production. It is also the third chapter in the "How is it built and how does it run" group. In this article I show what belongs in chapter 6, what to keep out, a flexible structure you can copy, plus a small example from Pitstop.

This post is about chapter 6: Runtime view, the third chapter in the “How is it built and how does it run” group.

Chapter 5 gave us the map (building blocks and responsibilities). Chapter 6 shows how that map is used in real life: who talks to whom, in what order, and why.

The arc42 template keeps this chapter intentionally “empty” by default. It is basically a container for scenarios: one subchapter per runtime process you want to document.

read more…
/ Michaël Hompus

, , , , , ,
Chapter 5 turns strategy into structure using white-box decomposition. It describes the static building blocks of your system, their responsibilities, and the most important dependencies, without diving into runtime flows. Learn what belongs in chapter 5, what to keep out, and get a copy/paste template plus a real example from Pitstop.

This post is about chapter 5: Building block view, the second chapter in the “How is it built and how does it run” group.

Chapter 4 set direction; chapter 5 makes it tangible. Here you describe the static structure of the system: the building blocks, what each one is responsible for, and which dependencies matter.

The goal is not to document everything. The goal is to give readers a mental map of the solution, so changes and discussions stop happening “in someone’s head”.

read more…