This post is about chapter 12: Glossary, the last chapter in the “Reality and shared language” group, and the final chapter of the arc42 template.

A glossary can be a simple list of abbreviations. That is useful, but it is not the main point. The real value is shared meaning: domain terms, recurring concepts, and words that teams use differently. If you practice Domain-Driven Design (DDD), this is where you document your Ubiquitous Language. If you do not use DDD, think of it as the vocabulary the whole team agrees on.

If readers have to ask “what do you mean by that?” while reading the document, the answer should probably live here.

The stakeholders you identified in chapter 1 are your target audience. Their vocabulary and assumptions should drive which terms you define.

What belongs in chapter 12 (and what does not)

Chapter 12 of an arc42 document answers:

Which terms do readers need to understand this document without guessing?

What belongs here:

• Domain terms that show up throughout the document:
  the core nouns and verbs of the system (work order, appointment, bay, reschedule, etc.).
• Abbreviations and acronyms:
  internal shorthand like ADR, RBAC, SSO, WS, SSE, OLTP.
• Architecture-specific terms and concepts you use repeatedly:
  for example “source of truth”, “degraded mode”, “idempotency key”, “read model”.
• Homonyms: words that look the same but mean different things in different contexts
  (for example “order”, “status”, “sync”).
• Synonyms: different words your team uses for the same concept.
  Pick one canonical term and document the alternatives as aliases.
• Ownership of meaning:
  when a term is a contract with an external neighbor, link to where it is specified (chapter 3 or an API spec).
• Translations and language mapping when the domain and the document use different languages:
  a consistent mapping from “local language term” ↔ “document term” so the whole team speaks the same language.

What does not belong here:

• Long tutorials or deep technical explanations.
  Keep definitions short and link to a concept section (chapter 8) when more detail is needed.
• A duplicate of the full domain model.
  If you need the full model, link to it, and keep chapter 12 as the shared vocabulary summary.
• Terms that are obvious to your audience and only used once.
  If it is not used, it does not belong.
• API field definitions and payload-level vocabulary.
  API reference docs have their own glossaries. Chapter 12 covers architecture-level terms, not message schemas.

Abbreviations are not enough

It is common to treat the glossary as an acronym list. That helps, but it does not solve the harder problem: shared understanding.

A better checklist for adding items:

• Does this term show up in multiple chapters?
• Could two stakeholders interpret it differently?
• Is this term used as a contract with a neighbor system?
• Would a new team member stumble on it?

If the answer is yes, it belongs here.

Translations and mixed-language domains

Some domains are bilingual by nature: the business uses Dutch terms, the code uses English, and the document ends up mixing both.

If your team runs into this, document the mapping explicitly.

A practical approach:

• Pick one primary term for the document (usually the one used in code).
• Add the alternative term as an alias.
• If needed, add a short note on where the term is used (UI label, code name, external system name).

This reduces friction in discussions and prevents subtle misunderstandings.

The minimum viable version

If you are short on time, aim for this:

• 5–10 terms: only the ones that are used repeatedly or can be misunderstood.
• 1–2 lines per term.
• Include acronyms that appear in headings, diagrams, or tables.

That is enough to make the document readable for newcomers.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 12. Glossary

<Short intro: what kinds of terms are defined here?>

### Terms and Abbreviations

<!-- Alphabetical order is not required, but most readers like it. -->

- **<Term or abbreviation>**
  <Meaning or description. Notes or aliases go here.>
- **<ABBREVIATION>**
  _<Full form>_
  <Meaning or description.>

### Translations (optional)

<Only if your domain and document use different languages.>

| Term (document) | Term (domain / UI) | Notes |
| :-------------- | :----------------- | :---- |
| ...             | ...                | ...   |

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a short example excerpt.

12. Glossary

Terms and Abbreviations

• ADR
  Architecture Decision Record
  A document that captures an important architectural decision, its context, and its consequences. Stored in chapter 9 of this document.
• Appointment
  A scheduled time slot owned by the Planning Service. Pitstop imports this and maps it to a work order.
  External term; owned by the Planning Service (see chapter 3). Also referred to as “slot” in the Planning API.
• Degraded mode
  A mode where the workshop UI can continue during connectivity loss. Uses a local queue and replay.
• Idempotency key
  A key that makes repeated messages safe to process multiple times. Prevents duplicate state changes on retries.
• RBAC
  Role-based access control
  A model that restricts system access based on the roles assigned to users.
• Source of truth
  The system that owns the authoritative state for a concept. Planning owns appointments, Pitstop owns work order status.
• Status
  In Pitstop, “status” always means work order status (the lifecycle from created → in-progress → done).
  The Planning Service uses “status” for appointment state (confirmed, cancelled, no-show), and the sync layer tracks its own sync status (pending, synced, failed).
  When reading this document, assume work order status unless the text says otherwise.
• SSE
  Server-sent events
  A server push technology that lets a server stream events to a browser over a single HTTP connection.
• Work order
  The unit of work in the workshop. Contains tasks, status, notes, and audit trail. Central aggregate (see chapter 8).
• WS
  WebSocket
  A protocol that provides full-duplex communication over a single TCP connection.

Translations

Term 🇺🇸 (document)	Term 🇳🇱 (domain / UI)	Notes
Work order	Werkorder	UI label used by garages.
Workshop	Werkplaats	Used in training materials and onboarding.

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Only listing acronyms
   Acronyms help, but they do not solve shared meaning for domain terms.

2. Defining terms that are never used
   A glossary is part of the architecture document, not a trivia list.

3. Definitions that are too long
   If a definition needs a page, you probably need a concept section (chapter 8) and a short summary here.

4. No alias handling
   If the same concept has two names, document both. Otherwise your team will keep arguing about words instead of system behavior.

5. Not maintaining it
   Every time you introduce a new recurring term, update the glossary. It is cheap work with high return. A practical trigger: review the glossary whenever you write an ADR, add an integration, or onboard a new team member.

Done-when checklist

🔲 Key domain terms used across the document are defined.
🔲 Acronyms and abbreviations are explained.
🔲 Ambiguous terms have explicit meaning for this system.
🔲 Mixed-language terms have a clear mapping (if relevant).
🔲 A new team member can read the document without asking “what does this mean?” repeatedly.

Next improvements backlog

• Add links from glossary terms to the first chapter where they are introduced.
• Add aliases for terms used in UI labels, code, and external systems.
• Review the glossary with a stakeholder who did not write the document.

Wrap-up

Chapter 12 is short, but the return is real. When the glossary is good, every other chapter becomes easier to read and easier to discuss.

This concludes the arc42 template itself.
The series is not done though.

I will add a follow-up post with practical notes on using a workflow to keep the document alive, not a one-off deliverable.

This post is about chapter 11: Risks and technical debt, the first chapter in the “Reality and shared language” group.

The first ten chapters built up the architecture story: goals, constraints, structure, runtime, deployment, concepts, decisions, and quality scenarios.

Chapter 11 is where we stop pretending everything is solved. It is where I write down what can still go wrong, what we knowingly postponed, and what we have not figured out yet.

What belongs in chapter 11 (and what does not)

Chapter 11 of an arc42 document answers:

What can still hurt us later, and what are we doing about it?

What belongs here:

• Architecturally relevant risks, including:
  • product and adoption risks (does the workflow fit reality?)
  • integration risks (vendor stability, contract changes, rate limits)
  • operational risks (backup, monitoring gaps, single points of failure)
  • security and compliance risks (data exposure, audit gaps, retention)
  • performance and scalability risks (hot paths, growth limits)
• Technical debt that affects maintainability, reliability, or delivery speed: the things you deliberately postponed that now need a visible trail.
• For each risk or debt item:
  • a clear statement
  • why it matters (impact)
  • how likely it is (roughly)
  • mitigation or next step
  • owner (a person, role, or team)
  • trigger or early warning (optional): how will you know this risk is starting to happen? This is different from mitigation: it is the signal that tells you to act. Think: a metric crossing a threshold, an error rate spike, a support ticket pattern.
• Cross-links to the rest of the document: constraints in chapter 2, strategy in chapter 4, runtime scenarios in chapter 6, deployment assumptions in chapter 7, reusable concepts in chapter 8, decisions in chapter 9, and quality scenarios in chapter 10.

What does not belong here:

• A full project management backlog. Keep chapter 11 focused on items that can materially impact the architecture.
• Sensitive vulnerability details in public documentation. It is fine to record security risks at a high level, but do not publish exploit steps, internal endpoints, or secret material. Link to a private ticket or security register if needed.
• A duplicate of chapter 9. Decisions belong in chapter 9, risks and debt belong here. When a risk is addressed by a decision, link to the ADR.

Risks vs technical debt

A simple distinction that works well:

• A risk is something that might happen. You manage it with mitigation, monitoring, and contingency plans.
• Technical debt is something that already happened. You chose a shortcut or postponement, and it has an interest rate.

Both are normal. Hiding them is what hurts.

Open questions and postponed decisions

Postponing architectural choices is often a very good practice. You wait for more certainty, more feedback, and more clarity before committing.

But not making a decision is also a risk. At best, you forget it still needs to be made. At worst, someone assumes it is already decided and starts building based on that assumption.

I use chapter 11 to make those “not-yet-decided” topics visible. It is not only a risk list, it is also a lightweight backlog of decisions that still need daylight.

The minimum viable version

If you are short on time, aim for this:

• 3–5 risks that could realistically derail delivery, operations, or stakeholder trust
• 3–5 technical debt items that you know will slow you down later

That is already enough to stop surprise work. You can always add more later.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 11. Risks and technical debt

Risks are phrased as: _what could hurt us_ + _why it matters_ + _what we will do about it_.

| Risk / debt item | Why it matters | Mitigation / decision |
| :--------------- | :------------- | :-------------------- |
| ...              | ...            | ...                   |

<!-- add likelihood, owner, trigger columns when your process is ready -->

### Known technical debt (optional)

- <intentional shortcut> → <why acceptable now> ; <when to revisit>
- ...

If you are more serious about risk management, you can add likelihood and impact columns as in a risk matrix, and maybe even assign an owner.

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a small example list. It is not meant to be complete, it is meant to show the style and the level of detail.

11. Risks and technical debt

Risks are phrased as “what could hurt us” + “what we will do about it”.

Risk / debt item	Why it matters	Mitigation / decision
Integration ambiguity per Planning Vendor	Each vendor has different semantics (cancellations, reschedules, no-shows), causing inconsistent work orders	Define a vendor mapping spec + contract tests; keep vendor-specific logic in adapters
Offline sync conflicts	Workshop can update while foreman/admin also edits → conflict resolution can become messy	Keep conflict rules simple (append notes; validate status transitions); provide “needs foreman review” path
Backlog growth in sync queue	Vendor outage or slow API can pile up updates, delaying customer comms	Monitor sync_queue_depth; circuit breaker; dead-letter queue + ops playbook
WebSocket instability in harsh networks	Real-time UX can degrade unpredictably in garages	Configurable fallback to polling (Realtime:FallbackToPollingSeconds); reconnect UX; track disconnect rates
Audit log volume / reporting load	Auditability creates data; dashboards can overload OLTP queries	Use read models; partition audit table; retention policies; optional replica for reporting

Known technical debt (intentional for v1)

• Single backend instance per garage (no HA) → acceptable for v1; revisit for chains.
• Minimal conflict resolution UI → acceptable initially; prioritize based on observed conflicts.

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Treating this as a shame list
   Chapter 11 is not for blame. It is for visibility and prioritization.

2. No owners
   A risk without an owner is a wish. Put a person, role, or team on it.

3. No next step
   A risk without a mitigation is just anxiety in table form. Even “decide in ADR-007” is better than nothing.

4. Only technical risks
   Adoption, workflow fit, vendor behavior, and operations are often where the real pain starts.

5. Deleting history
   Close items explicitly. If something was a risk and it is no longer a risk, document why.

6. No links back to the architecture story
   Risks should connect back to the drivers and trade-offs. Otherwise the list becomes isolated and nobody acts on it.

Done-when checklist

🔲 The chapter lists the risks that could realistically hurt delivery or operations.
🔲 Technical debt items are visible, not hidden in chat and backlog noise.
🔲 Each item has an owner and a next step.
🔲 Items link to the relevant chapters, concepts, decisions, or scenarios.
🔲 The list is reviewed on a cadence (even if it is just “every release”).

Next improvements backlog

• Add a simple severity sorting (impact × likelihood) to focus discussions.
• Add a trigger column to your table once the basic list is stable.
• Link security risks to a private register when details should not be published.

Wrap-up

Chapter 11 is what keeps the architecture document honest. You make risks and debt visible early, then refine them as you learn.

Next up: arc42 chapter 12, “Glossary”, where we build shared language so readers do not have to guess what terms mean.

This post is about chapter 10: Quality requirements, the third chapter in the “Reusables, decisions, and qualities” group.

Chapter 1 introduced quality goals at a high level. Chapters 8 and 9 captured patterns and decisions that often exist because of those goals. Chapter 10 is where I make qualities concrete: not as slogans, but as scenarios you can test, monitor, and verify.

One recurring problem: stakeholders and teams find it hard to write SMART quality requirements. They will say fast, robust, secure, and everyone nods. Then production teaches you that nodding is not a measurement.

What belongs in chapter 10 (and what does not)

Chapter 10 of an arc42 document answers:

Which quality requirements matter, and how do we know we meet them?

What belongs here:

• A quality requirements overview:
  the relevant quality characteristics for your system, grouped in a structure that is easy to scan. ISO/IEC 25010 is a common choice for this grouping, and Q42 is a useful catalogue for examples.
• A set of quality scenarios:
  situation-based, testable requirements with a stimulus, an expected response, and a metric or target. “Testable” means different things per type: validate a latency scenario with a load test or SLO alert; an auditability scenario with a timed export; a modifiability scenario by verifying the adapter boundary in a code review.
• A clear link back to quality goals from chapter 1.
  If chapter 1 says “auditability” is a top goal, chapter 10 should make that measurable.
• Cross-links to where quality is implemented:
  concepts (chapter 8), decisions (chapter 9), and sometimes deployment constraints (chapter 7).

What does not belong here:

• A technology shopping list.
  ”Kafka” is not a quality requirement, it is a potential solution.
• Purely functional requirements and business workflows.
  Those belong in use cases, building blocks (chapter 5), and runtime scenarios (chapter 6).
• Only vague adjectives.
  ”fast” and “secure” are direction, not requirements. Chapter 10 is where you turn them into something you can validate.

Why is quality so late in arc42?

It can feel strange that quality scenarios show up this far back in the arc42 structure. It can look like quality is an afterthought. It is not.

This is how I explain it:

• Quality goals are up front because they drive direction.
• Quality scenarios are later because they need context to be meaningful.
• The document is iterative: you refine goals, you make choices, you learn, you tighten scenarios.

In other words, chapter 10 benefits from having chapters 5–7 in place. A scenario like “p95 status update latency is ≤ 2s” only makes sense when you know what “status update” is, which building blocks collaborate, and where the system actually runs.

A structure that helps when people struggle with SMART qualities

If your stakeholders struggle with SMART wording, do not fight them with a blank page. Give them a ladder:

• Start with a quality tree to agree on vocabulary.
• Add a short overview per quality area: what matters and what does not.
• Convert the important items into scenarios with measurable targets.

Two helpful sources for vocabulary and inspiration:

• ISO/IEC 25010:2023 gives you a familiar top-level structure.
• Q42 is a companion project by the arc42 team. It gives you a large catalogue of quality characteristics with descriptions and example requirements you can adapt.

Use them as scaffolding, not as a checklist.

Quality tree diagram

A quality tree is a visual overview of which quality characteristics apply to your system. It works like a map: it shows the landscape at a glance, so you can decide where to focus.

It is useful because it makes trade-offs visible. When you can see all quality areas together, it becomes easier to say “this matters more than that”, and to explain that choice to others. It also prevents the “everything is important” trap: when everything is marked as a top priority, that is the same as having no priorities at all.

The minimum viable version

If you are short on time, aim for this:

1. A small quality overview, grouped by ISO/IEC 25010:2023 headings.
   (or your own headings if that reads better).
2. Pick 3–6 top items and write quality scenarios for them.
3. For each scenario, add a metric target you can validate later.

That is enough to stop quality from being a vibe.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 10. Quality requirements

<Short intro: why quality matters for this system and how we verify it.>

### 10.1 Quality requirements overview

<Group requirements using ISO/IEC 25010:2023 headings or another clear structure.>
<Mark "nice-to-have" items explicitly.>

### 10.2 Quality scenarios

<Scenario-based, testable requirements. Keep them short and measurable.>

| Scenario | Stimulus | Response | Metric/Target |
| :------- | :------- | :------- | :------------ |
| ...      | ...      | ...      | ...           |

<Add more tables per quality theme if that improves readability.>

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a shortened version of the Pitstop chapter 10. It shows the structure without drowning you in every possible scenario. Notice how overview headings and scenario groups mark which chapter 1 top goals they address. Consistency is a Pitstop-specific quality area that does not map to a single ISO/IEC 25010:2023 category.

10. Quality requirements

10.1 Quality requirements overview

Reliability (top goal: Resilience)

• Degraded-mode operation for workshop during flaky internet.
• Sync backlog does not block workshop core operations.

Consistency (top goal: Consistency)

• Status updates visible across all UIs within seconds.
• Idempotent handling of duplicate planning updates.

Maintainability (top goal: Modifiability)

• Add a new planning vendor adapter without changing core work order rules.
• Nice-to-have: automated contract tests with recorded fixtures.

Security

• Role-based access control with site scoping via garageId.
• Secure audit trail, prevent tampering with history.

Auditability / traceability

• Every significant change records who, when, and why.
• Timeline export supports disputes and compliance.

10.2 Quality scenarios

Reliability (top goal: Resilience)

Scenario	Stimulus	Response	Metric/Target
Wi-Fi outage	15 min disconnect	Workshop continues, actions queued locally	≥ 99% of actions queued without loss
Reconnect	Network returns	Queue replays and sync completes	drained within ≤ 60s

See also: degraded mode concept and ADR-001.

Consistency (top goal: Consistency)

Scenario	Stimulus	Response	Metric/Target
Status visible everywhere	Mechanic sets WaitingForParts	Admin and Workshop converge	≤ 2s end-to-end (p95)
Duplicate vendor update	Planning sends same appointment twice	Processed once, idempotent	0 duplicate work orders

Maintainability (top goal: Modifiability)

Scenario	Stimulus	Response	Metric/Target
Add planning vendor	New API and mapping	Add adapter, domain unchanged	≤ 2 days, core untouched

Security

Scenario	Stimulus	Response	Metric/Target
Cross-garage access	User tries other garageId	Denied	100% blocked
Audit tamper attempt	Try to edit history	Prevented + logged	100% blocked + logged

Auditability

Scenario	Stimulus	Response	Metric/Target
Customer dispute	”You promised 16:00”	Export full timeline	≤ 60s export

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Writing only adjectives
   ”fast” is not a requirement. A scenario with a measurable target is. Make sure to talk with stakeholders what the target should be and how to verify it.

2. Mixing requirements and solutions
   ”use Redis” is a decision, not a requirement. The requirement is something like “fast access to work order state”. If you have a decision that implements a quality requirement, write the requirement here, and link to the decision in chapter 9.

3. No link back to goals
   If chapter 1 lists top goals, chapter 10 should make them concrete. It would be strange if chapter 1 says “consistency” is a top goal, but chapter 10 does not have any scenarios to measure it.

4. Treating this as one-and-done
   Quality scenarios improve with iteration. Early drafts are allowed to be rough, as long as you refine them. Every time you add a scenario, building block, deployment, or decision, ask yourself if it has quality implications that should be captured here.

5. Too many scenarios without navigation
   A large system can have many scenarios. Group them, keep titles clear, and keep tables consistent. Link to documents if you have detailed test plans or runbooks.

Done-when checklist

🔲 Quality requirements are grouped in a structure people recognize (ISO/IEC 25010 or equivalent).
🔲 Top quality goals from chapter 1 are turned into measurable scenarios.
🔲 Scenarios include a stimulus, response, and a metric or target.
🔲 At least one quality area traces back to the concept or decision that implements it.
🔲 The chapter is treated as iterative, it will be refined as the system and insights evolve.

Next improvements backlog

• Add monitoring or test hooks for the most important scenario metrics.
• Add scenario coverage for important external neighbors and operational jobs.
• Tighten targets over time based on observed production baselines.
• Add a short note per top goal on how it is validated (test, metric, runbook).

Wrap-up

Chapter 10 is where quality stops being a wish and becomes a check. When a quality trade-off is accepted, document it here: note which quality was deprioritized, which won, and link to the decision in chapter 9 that captures the reasoning. You can start with rough scenarios, then refine them as you learn.

Next up: arc42 chapter 11, “Risks and technical debt”, where we capture the things that can still bite us later, and how we keep them visible.

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.

What belongs in chapter 9 (and what does not)

Chapter 9 of an arc42 document answers:

Which important architectural decisions were made, and what was the rationale?

What belongs here:

• A decision timeline that is easy to scan. A table works well, because it stays compact even when the list grows.
• Decisions that affect future work: structure, integration approach, deployment strategy, quality trade-offs, team boundaries, and platform choices. Strategy decisions from chapter 4 are a perfect match here.
• For each decision, at least:
  • the decision itself
  • a short motivation
  • a link to details (optional, but recommended)
• Considered options for decisions that can trigger future discussions. This is the part that prevents why did you not choose X? debates years later.
• Links to where the decision shows up: chapters 4–8 and the relevant code or infrastructure artifacts.

What does not belong here:

• Changes that are easy to undo. A practical test: if reverting the change does not hurt, it is probably too small to record as a decision.
• Meeting notes or chat transcripts. Keep the record curated.
• A concept guide. If the content is how we always do retries, put it in chapter 8 and link to it from here.

Decision timeline formats: list or ADRs

There is no required format here. The simplest valid version is a decision timeline with a short motivation per entry.

ADRs are an optional extension of that idea. They are not required by arc42, but they are a great format when a decision has real trade-offs and future consequences. This post is not an exhaustive guide on ADRs (there are entire books on that), but I will show you how to fit them into the concise style of arc42.

A simple rule of thumb for when to write an ADR: if the decision constrains future work and is hard to reverse, it deserves one. If reverting or changing it later is cheap, a one-liner in the timeline is enough.

A good workflow is:

• Keep the timeline in chapter 9.
• When an entry needs more detail, link to an ADR file.
• The timeline stays readable, and the details stay available.

ADR format

When I use ADRs, I put the decision before considered options. That gives a management overview without forcing readers through all the details.

A good ADR structure:

• Metadata (date, status, decision makers)
• Context (what problem or constraint triggered this decision)
• Decision (one short paragraph: what did we decide)
• Consequences (what changes and risks did we accept)
• Considered options (with a short “why not” for each)

Statuses are kept simple:

• Pending (draft, not yet accepted)
• Accepted
• Superseded by ADR-XXX (the replacement decision)

I do not use a “deprecated” status. Deprecating something is itself a decision, and that decision supersedes the old one. Also here you have to write down the consequences of deprecation, will you clean up, do you accept dead-code, etc.

The minimum viable version

If you are short on time:

• Start with a timeline table.
• For each entry, write 1–3 lines of motivation.

That is already enough to preserve the reasoning.

Copy/paste structure (Markdown skeleton)

Use this as a starting point.

## 9. Architectural decisions

<Short intro: how do we capture decisions and keep them current?>

| Date | Decision | Status |
| :--- | :------- | :----- |
| ...  | ...      | ...    |

<If you have decisions without ADRs, keep them here too.
The decision can just be plain text plus 1–3 lines of motivation.>

And an ADR template that matches the timeline:

### ADR-XXX <Decision statement>

- **Date:** YYYY-MM-DD
- **Status:** Pending | Accepted | Superseded by ADR-YYY
- **Decision makers:** <names or roles of the people who made the decision>

#### Context

<What problem or constraint triggered this decision?>

#### Decision

<One short paragraph: what did we decide?>

#### Consequences

- <what gets better>
- <what gets harder>
- <follow-up work / migration notes>

#### Considered options

1. <option A: short statement>
   - **Pros**:
     - <reason>
   - **Cons**:
     - <reason>
2. <option B: short statement>
   - **Pros**:
     - <reason>
   - **Cons**:
     - <reason>

#### References

- Affects: chapter 4/5/6/7/8 links (optional)
- Related concept: chapter 8.n (optional)
- Related code: <path or repo link> (optional)

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below is a small timeline table plus one ADR example.

9. Architectural decisions

Date	Decision	Status
2026-01-18	ADR-001 Add degraded mode for workshop updates	Accepted

ADR-001 Add degraded mode for workshop updates

• Date: 2026-01-18
• Status: Accepted
• Decision makers: Michaël (architect), workshop team (developers and testers)

Context

Workshop connectivity is not reliable in every garage. Status updates must remain possible during outages, and the system must recover safely.

Decision

Pitstop supports a degraded mode where the workshop UI can keep working while offline. Updates are queued locally and replayed later with idempotency keys to prevent double-apply.

Consequences

• Workshop UI becomes stateful and needs conflict handling.
• Backend needs idempotency storage and replay rules.

Considered options

1. Reject updates when offline
   • Cons:
     • blocks the workshop and causes lost work
2. Allow offline updates without idempotency
   • Cons:
     • unsafe replays and duplicate state changes on reconnect
3. Local queue with idempotency keys
   • Pros:
     • safe replay, workshop keeps moving

References

• Concept: degraded mode and idempotency
• Scenario: appointment import and status updates

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Not realizing you made a decision
   Many decisions show up as “small choices” in a sprint. If it shapes future work, record it.

2. Skipping considered options
   This is how you get time-travel debates later. A short “why not” list is often enough.

3. Decisions without consequences
   If there is no trade-off, it is probably not a decision. Write down what gets harder, not only what gets easier.

4. No successor trail
   Decisions can be overturned with new insights. Do not delete the old one, supersede it and link forward.

5. Logging everything
   If reverting the change does not hurt, it is probably too small for chapter 9. Keep this chapter high signal.

Done-when checklist

🔲 Chapter 9 contains a scan-friendly timeline of decisions.
🔲 Each entry has at least the decision and a short motivation.
🔲 Important decisions have considered options recorded.
🔲 Decisions link to where they show up (chapters 4–8).
🔲 Quality trade-offs connect to quality scenarios in chapter 10.

Next improvements backlog

• Add lightweight review: ADRs are accepted before major implementation work starts.
• Add cross-links from chapter 8 concepts back to the decisions that introduced them.
• Supersede decisions when they are changed, and link to the new one.

Wrap-up

Chapter 9 is the memory of your architecture. It keeps the reasoning visible, even when the team changes and the code evolves.

Decisions and quality requirements reinforce each other. A decision often accepts a trade-off, and chapter 10 is where you make those trade-offs measurable.

Next up: arc42 chapter 10, “Quality requirements”, where we turn quality goals into concrete scenarios and checks.

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.

What belongs in chapter 8 (and what does not)

The main job of chapter 8 of an arc42 document is to answer:

Which patterns and practices should be applied consistently across the system, and how do we do that?

What belongs here:

• Patterns and rules that apply across multiple building blocks or scenarios, not just one module.
• Reusable conventions you want implemented consistently over time, even if they currently apply only once.
• “Plumbing” that supports the domain but is not domain logic itself: the infrastructure behavior that makes core code work correctly.
• Concept-level configuration behavior: what a mode or flag means and which behavior changes when it toggles. The where and how to configure it usually lives in chapter 7.
• Shared domain definitions (aggregates, state machines, vocabulary) that every module depends on.

A simple test that works well:

• If you want developers to implement something the same way in multiple places over time, document it here.
• Link to it from the scenarios in chapter 6 and from relevant building blocks in chapter 5.

What does not belong here:

• Feature-specific domain rules and workflows.
  Those belong in the building blocks (chapter 5) and scenarios (chapter 6).
• A repeat of the runtime scenarios.
  Chapter 8 should let chapter 6 stay lean.
• A raw list of configuration settings.
  Chapter 8 should explain what a setting means and why it exists, not list every key in the system. The full reference is better placed in chapter 7 or a dedicated config reference.
• Highly local implementation details that are unlikely to be reused.
  Those belong close to the code, or in an ADR when it is a decision with consequences (chapter 9).
• Hard architectural constraints or enterprise policies.
  Mandates like “Cloud First” or compliance rules belong in chapter 2. Chapter 8 documents the reusable patterns you designed, not the constraints you were forced to follow.

Common concept categories

Not every system needs all of these, but this list helps as a starting point. Pick what applies:

• Security: identity, RBAC/ABAC, tenant scoping, service-to-service auth, secret handling rules
• Resilience: retries/backoff, circuit breakers, offline/degraded mode, idempotency rules
• Observability: correlation IDs, structured logging, key metrics, tracing, alerting conventions
• Data and consistency: source-of-truth rules, eventing/outbox patterns, read models, audit trail
• Integration conventions: contract versioning, error mapping, rate limits, vendor protection
• Configuration model: precedence rules, environment overrides, feature flags, safe defaults
• Domain model: aggregate boundaries, state machines, shared vocabulary, key invariants
• Test Strategy: test data management, standard tools, integration test patterns, performance constraints
• UI/UX Patterns: standard layouts, error notifications, accessibility rules, design system integration

Who this chapter is for

Most of the time, chapter 8 is primarily useful for the dev team and maintainers. It prevents five different implementations of the same thing.

External stakeholders usually do not care about your retry policy or correlation ID format. They might care when it explains system guarantees (auditability, safety, recovery time), or when they want inspiration as your team is the shining example sharing their awesome implementation in their arc42 document. 💎😉

Chapter 8 vs. Chapter 9: Concepts vs. decisions

A common question: when does something belong in chapter 8 versus chapter 9 (ADRs)?

The boundary is clearer than it first appears:

• Chapter 8 documents how we do X consistently: the pattern, the practice, the implementation standard.
• Chapter 9 documents why we chose X over Y: the decision, the alternatives considered, the trade-offs, and the context that made the choice make sense.

They work together:

• The ADR explains the choice and constraints.
• The concept explains how to implement it correctly and where it shows up.

Linking them:
Always cross-reference. The concept should link to the ADR. The ADR should link to the concept.

Aggregates, entities, and the shared domain vocabulary

In many systems, there are a few domain concepts that show up everywhere: work orders, customers, assets, cases, incidents, whatever your core “things” are.

When those concepts apply across the whole application, I document their aggregate boundaries and entity responsibilities in chapter 8. Not because chapter 8 is a domain chapter, but because these definitions act like a shared rulebook.

This helps in three places:

• It keeps chapter 5 focused on structure, not repeating the same domain definitions per building block.
• It keeps chapter 6 readable, because scenarios can reference “WorkOrder” and everyone knows what that means.
• It reduces accidental coupling, because aggregate boundaries become explicit.

What I put here is deliberately lightweight:

• Aggregate name and purpose
• What it owns (entities, value objects)
• Key invariants (rules that must always hold)
• State transitions and lifecycle notes
• Identity and scoping rules (IDs, tenant/site boundaries)
• Events published or important integration touch points (high level)

If you need a full data dictionary or complete schema documentation, do not force it into this chapter. Link to a domain model reference, or split it into a separate document and keep chapter 8 as the “shared rules” summary.

How to keep chapter 8 from becoming a junk drawer

This chapter is vulnerable to entropy. Everything is a “concept” if you stare at it long enough.

A few guardrails that help:

• Prefer “rules + rationale” over “technology lists”.
• Keep each concept small:
  • what it is
  • why it exists
  • how to implement it
  • how to test or verify it
  • where it shows up (links to scenarios, building blocks, ADRs)
• If a section becomes a wall of text, split it: move low-level specifics into a code-linked doc and keep chapter 8 as the overview.
• When a concept evolves, document both the current standard and the migration path. Mark old approaches explicitly as “legacy” or “deprecated” with a timeline, and link to the ADR (chapter 9) that explains why it changed. This prevents new code from following outdated patterns while giving teams visibility into what they need to update.

The minimum viable version

If you are short on time, aim for:

• 3–6 concepts that either:
  • already affect multiple parts of the system, or
  • are patterns you want future work to follow (even if they currently apply once)
• For each concept, include:
  • a short description
  • the key rule(s)
  • where it shows up (links)
  • one or two implementation notes that prevent mistakes

That is enough to keep future work consistent.

Copy/paste structure (Markdown skeleton)

Use this as a starting point. Keep it flexible.

## 8. Concepts

<Short intro: what concepts matter for this system and why?>

### 8.n <Concept name>

<1–3 short paragraphs: what it is and why it exists.>

#### Rules (optional)

- <rule 1>
- <rule 2>

#### Implementation (example-level, not every detail)

- <how it is implemented in this system>
- <where it lives in the code, if useful>

#### Configuration (optional)

- <which settings affect this concept and what they mean>
- <link to chapter 7 for where it is configured>

#### Verification (optional)

- <how do we know it works: tests, logs, dashboards, runbooks>

#### Where it shows up

- Scenario: chapter 6.x (link)
- Building block: chapter 5.x (link)
- ADR: chapter 9.x (link)

Example (Pitstop)

Pitstop is my small demo system for this series. It is intentionally simple, so the documentation stays shareable.

Below are four concept examples that make chapter 6 easier to read, and make chapter 7 configuration feel meaningful instead of arbitrary.

8.1 Identity and access (RBAC)

Pitstop uses role-based access control (RBAC) to keep workshop actions safe and auditable. The UI can hide buttons, but the server enforces authorization. The UI is not a security boundary.

Rules

• Every endpoint that reads or changes work orders requires an explicit policy.
• Authorization is validated server-side for both HTTP and real-time actions.
• Claims include a garageId to scope access per site.

Implementation

• Auth: JWT bearer tokens.
• Authorization: policy-based checks, mapped from roles and claims.

Claims (example)

• role: Mechanic, Foreman, ServiceAdvisor
• garageId: used for tenant or site scoping
• permissions: optional fine-grained list for exceptions (for example discount approval)

Where it shows up

• Scenarios: status updates and overrides in chapter 6.
• Deployment: token validation settings and identity provider wiring in chapter 7.

8.2 Work order (aggregate / domain model)

The work order is the central aggregate in Pitstop. Every module, scenario, and UI revolves around it. Documenting it here gives the whole team a shared definition to build against.

Aggregate boundary

A work order owns its tasks, status, notes, and parts dependencies. It does not own the appointment (that belongs to the planning service) or the customer record.

Lifecycle (state machine)

• Only forward transitions are allowed by default.
• WaitingForParts ↔ InProgress can toggle when parts arrive or a new dependency is found.
• A Foreman can force-transition to any state (override).

Key invariants

• A work order always has exactly one active status.
• Status changes are audited (who/when/why, see concept 8.4).
• Identity: WO-{sequence}, scoped by garageId.

Where it shows up

• Building blocks: Work Order Module in chapter 5.
• Scenarios: every chapter 6 scenario references work order state.
• Audit: status changes feed the audit log (concept 8.4).

8.3 Degraded-mode workshop operation (local queue + idempotency)

Workshop connectivity is not always reliable. Pitstop supports a degraded mode where the workshop UI can keep working and sync later.

Rules

• Workshop updates are queued locally when offline.
• Every queued item has an idempotency key so replays do not double-apply.
• Replay happens in order. Hard conflicts stop the replay and require user resolution.

Implementation

• Workshop UI stores updates in a local outbox queue (for example IndexedDB).
• Each item includes an idempotency key derived from work order, version, and actor context.

Queue item (example)

{
  "idempotencyKey": "WO-7781:v42:mechanic-17:2026-01-12T10:41:00Z",
  "workOrderId": "WO-7781",
  "command": "ChangeStatus",
  "payload": {
    "status": "WaitingForParts",
    "note": "Brake pads not in stock"
  },
  "queuedAt": "2026-01-12T10:41:00+01:00"
}

Configuration behavior

• If Pitstop:ConnectivityMode = OfflineFirst, the UI queues first and sends async.
• If OnlineFirst, the UI sends immediately and queues only on failure.

The meaning of ConnectivityMode is documented here. Where it is configured (env vars, config files) is documented in chapter 7.

Where it shows up

• Scenarios: status update flows in chapter 6.
• Deployment: the ConnectivityMode setting in chapter 7.

8.4 Observability

Every request and event carries a correlationId so ops can trace a flow end-to-end. Logs are structured (JSON), and a small set of metrics drives the alerting that lets ops sleep.

Rules

• Every log entry includes correlationId, workOrderId (when applicable), and garageId.
• Metrics are kept small and actionable:
  • sync_queue_depth: are outbound updates piling up?
  • status_update_latency_ms (p95): is the workshop experience degrading?
  • ws_connected_clients: are workshops connected?
• Alert example: sync_queue_depth > 100 for 10 minutes → vendor down or credentials broken.

Where it shows up

• Scenarios: every chapter 6 flow carries correlationId.
• Deployment: log sink and dashboard configuration in chapter 7.

To browse the full Pitstop arc42 sample, see my GitHub Gist.

Common mistakes I see (and made myself)

1. Treating “cross-cutting” as a hard gate
   Even if you are documenting something small like a microservice, service-wide concepts are still useful. The chapter title does not need to police you.
   Rename the chapter to “Concepts” if that helps, but do not skip it just because you think “cross-cutting” means “multi-service”.

2. Waiting until a pattern appears everywhere
   If you already know a rule should become standard, document it early. That is how you steer future work. Arc42 can start at the drawing table, even without any line of code written yet.

3. Turning chapter 8 into a dump
   A list of random libraries is not a concept chapter. Prefer rules, rationale, and where it shows up. Future team members or maintainers should be able to read this chapter and understand the key patterns without needing to read every line of it.

4. Repeating concept explanations in every scenario
   If you notice that chapter 6 starts to contain the same text multiple times, move it here and link to it.

5. No link back to reality
   If a concept never shows up in code, runtime scenarios, or configuration, it is probably planned but not yet implemented. That is fine, but mark it clearly and revisit it. Maybe new insights have emerged and it is no longer the right pattern.

Done-when checklist

🔲 The chapter contains concepts that are reused or intended to be reused over time.
🔲 Each concept includes at least one actionable rule, not only a description.
🔲 Concepts link to where they show up (chapters 5, 6, 7, and later ADRs in chapter 9).
🔲 The chapter helps keep runtime scenarios lean by avoiding repeated explanations.
🔲 A maintainer can implement a new feature without reinventing logging, retries, idempotency, or authorization.

Next improvements backlog

• Add links to code locations when concepts map cleanly to modules or packages.
• Add verification notes for concepts that can fail in production (dashboards, alerts, runbooks).
• Add concept-level configuration tables only for settings that change behavior significantly.
• Split large concepts into “overview here, details in a linked doc” when they grow.

Wrap-up

Chapter 8 is where I capture the reusable solutions that make the rest of the document cheaper to maintain. It keeps the domain code focused, and it keeps chapter 6 readable.

Next up: arc42 chapter 9, “Architectural decisions”, where we record all the decisions that we made along the way.