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 work” 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”.
Note
This post is longer because chapter 5 introduces hierarchical decomposition (a.k.a. zooming in step by step):
start small, and only add detail when it prevents real misunderstandings.
What belongs in chapter 5 (and what does not)
The main job of chapter 5 of an arc42 document is to answer:
What are the main parts of the system, and what is each part responsible for?
What belongs here:
A building block hierarchy (level 1–3), from coarse to detailed.
Per building block:
responsibility (one sentence)
key dependencies
main interfaces (what it offers/needs)
The boundaries that matter: ownership, responsibilities, and “who is allowed to change what”.
When multiple teams work on the same system, building block boundaries often align with team ownership.
If changing a block requires coordination with another team, that boundary is worth documenting.
The structural consequences of your strategy from chapter 4
(e.g., modular monolith vs distributed, having a BFF, etc.).
Links to source code or generated docs when that helps (if building blocks map to modules/packages/repos).
What does not belong here:
Copy/pasting large parts of earlier chapters.
Refer back to the goals, constraints, and context when you need them,
but keep this chapter focused on responsibilities and boundaries.
Step-by-step flows, sequencing, or “and then it calls X” stories.
This chapter is about static structure, not behavior.
Environment-specific deployment and infrastructure details.
Keep those concerns separate so the building block view stays stable even when environments change.
Full interface specifications and contract catalogs.
You can link to OpenAPI/AsyncAPI or other specs, but avoid duplicating payloads and edge cases here.
Low-level implementation decisions that change frequently.
If it is likely to flip during sprints (a library choice, an internal pattern tweak),
it does not belong in the core structure.
The “white-box” metaphor
The core concept of this chapter is the black-box vs. white-box approach.
Chapter 3 was the black-box view: The system is a sealed opaque block.
We only described what crosses the boundary (interfaces) and who sits outside (neighbors),
but internals were invisible (hence “black” or opaque).
Chapter 5 is the white-box series:
We “open the lid” of the system. We look inside to see how it is constructed.
Level 1 opens the main black box. If a component inside Level 1 is complex,
we treat that component as a black box first, then open it up in Level 2 (its white-box view).
This hierarchical decomposition is standard in arc42 and aligns with the C4 Model “Zoom” concept.
Levels mean different things in different documents
First, a blunt disclaimer: The building block levels are a zoom tool, not a fixed taxonomy.
You stop decomposing when you can no longer explain why the detail matters to your architectural goals.
What “level 1–3” means depends on what you are documenting:
For a large system, level 1 might be products, level 2 domains/services, and level 3 microservices.
For a single (micro)service, level 1 might be the service boundary, level 2 internal modules, and level 3 namespaces.
For a platform/library team, level 2 might describe public APIs or even classes,
because that is what stakeholders integrate with,
and level 3 might be implementation details that only the owning-team needs to understand.
Tip
Pick the level of detail that matches your stakeholders.
A diagram is successful when it answers their questions, not when it contains more boxes.
Level 1 should match chapter 3
Level 1 is where you show the system boundary and the neighbors.
It should include the same external neighbors you introduced in chapter 3.
Warning
Do not confuse context with building blocks.
Chapter 3: Who/what is outside, and what crosses the boundary?
Chapter 5 Level 1: What are the main internal building blocks,
and how do they depend on each other and their connection to the external neighbors?
That creates a nice “thread” through the document:
chapter 5: how we are structured to deal with that
chapter 6: how the collaboration plays out at runtime (spoiler alert! 🫣)
Do not repeat interface details on every level
Interfaces show up on multiple levels, but you do not have to repeat everything.
Repeating payloads and contracts at every zoom level creates noise and maintenance debt.
A practical rule:
Level 1: Name the interactions (e.g., “Appointments”, “Status Updates”) so the relationship is clear.
Level 2/3: Document the interface where the contract lives (e.g., in the integration module or port)
and link to the source/spec.
When you are describing interfaces on a level, it could be helpful to separate them into:
If building blocks map cleanly to code, link them.
Some teams generate docs straight from source (Doxygen-style or similar),
which can make this chapter accurate and cheap to maintain.
Example (Pitstop)
Pitstop is my small demo system for this series.
It is intentionally simple, so the documentation stays shareable.
This is what chapter 5 looks like when filled in.
5. Building block view
5.1 White-box overall system
Building blocks (level 1)
Block
Responsibility
Key Interfaces
Admin Overview UI
Dashboard, coordination, customer comms support
HTTPS/JSON to Backend
Workshop View UI
Bay/task board, fast updates, degraded mode
WebSocket/JSON to Backend
Backend
Core domain + APIs + orchestration
HTTPS/JSON + WS + internal module interfaces
Sync & Integration
Mapping + sync strategy per planning vendor
REST/JSON, webhooks, retry
Audit/Event Log
Immutable history for accountability + analytics
Append/read APIs
DB
Operational persistence
SQL (implementation-specific)
5.2 Level 2 — Pitstop Backend
Notes
Modules contain domain rules.
The Integration Ports (a ports-and-adapters pattern, as chosen in chapter 4)
isolate vendor protocols and mapping, so domain modules do not depend on external systems directly.
Reporting read models can be optimized independently (avoid OLTP pain).
Building blocks (level 2)
Element
Responsibility
Depends on
Work Order Module
Core logic for orders
Customer, Audit
Workshop Module
Mechanic task management
WorkOrders, Audit
Admin Module
Configuration & overrides
Audit
Customer/Vehicle Module
Shared entity data
Audit
Reporting
Read-optimized views
(Domain Events)
Planning Port
Adapter for Planning Service
External
Notification Port
Adapter for Notification Service
External
Audit Writer
Centralized compliance logging
DB
API Layer
Protocol handling (HTTP/WS)
Auth, Modules
To browse the full Pitstop arc42 sample, see my GitHub Gist.
Note
A level 3 zoom into the Work Order Module could show its internal structure
(e.g., command handlers, domain entities, validation rules) if stakeholders need that detail.
For brevity, we leave it out here.
Common mistakes I see (and made myself)
Too much detail too early
If chapter 5 looks like a class diagram, it will not be maintained.
Start coarse, and zoom in only where complexity justifies it.
Building blocks without responsibilities
Boxes called Service and Manager are not responsibilities.
Each block should say what it owns: persistence, state transitions, messaging, integrations, etc.
Mismatch with chapter 3
If chapter 3 lists neighbors, level 1 should show them. As you document the white-box,
you might find a specific module that talks to an external system you forgot to list in chapter 3.
Consistency goes both ways!
Repeating interface specs everywhere
Do not duplicate protocol and payload details on every level.
Put the detail where it makes sense (often chapter 3) and link to it.
Forgetting “source of truth”
For important data: who owns it, and who is allowed to change it?
If you do not answer this, production will answer it for you.
Using technology names as architecture Kafka and PostgreSQL are implementation choices.
Building blocks should describe responsibilities (message bus, persistence, state, integrations),
so your diagrams remain useful when technology or deployment changes.
Done-when checklist
🔲 Level 1 includes the system boundary and the neighbors from chapter 3. 🔲 Each building block has a clear responsibility in one sentence. 🔲 External interfaces are referenced (and not duplicated) where documented. 🔲 Level 2/3 are used only when complexity or stakeholders require it. 🔲 A new team member can explain “what lives where” after reading this chapter.
Next improvements backlog
Add ADR links when boundaries or decomposition are disputed (chapter 9).
Add level 3 only for a few areas where deeper detail prevents misunderstandings.
Add links to code/docs where building blocks map cleanly to modules or repos.
Wrap-up
Chapter 5 is the map. 🗺️
It helps people find responsibilities, boundaries, and where to implement changes.
Next up: arc42 chapter 6, the runtime view, where we put this structure in motion and describe the most important end-to-end flows.
Chapter 4 opens the "How is it built and how does it work" group. It is where goals, constraints, and context from the first three chapters start to shape the design through a small set of guiding decisions.
In this article I show what belongs in chapter 4, what to keep out, how to handle open strategy questions, and a flexible structure you can copy, plus a small example from Pitstop.
This post opens the “How is it built and how does it work” group.
The first three chapters can feel like silos: each one introduces its own set of information.
Here, those inputs start to shape the design. This is where you set direction for the solution.
Your solution strategy should fit the goals from chapter 1,
operate within the non-negotiables from chapter 2,
and respect the boundaries and partners from chapter 3.
Early in a project this chapter can be short. That is normal.
The strategy grows as you learn, as constraints become concrete, and as decisions are made.
What belongs in chapter 4 (and what does not)
Chapter 4 of an arc42 document answers one question:
What is our approach, and which major decisions guide the design?
What belongs here:
A short list of guiding choices that shape the whole design.
For each choice a short rationale: why this direction fits the goals, constraints, and context.
The “heavy” decisions that should not change every sprint:
Major platform choices, integration strategy, monolith vs distributed, data approach, deployment style.
Trade-offs and rationale, linked back to earlier chapters where possible.
Consequences (direction and impact), so people understand what follows from the strategy.
Links to ADRs when they exist (chapter 9).
If your list grows over time, group the strategy items into a few buckets that fit your scope
(pick what matches your system), for example:
Detailed breakdowns of internal parts and their dependencies.
Step-by-step interaction flows or scenario descriptions.
Environment-specific operational details.
Small, sprint-level technical choices that are likely to change often.
Copy/pasting earlier chapters: link to the drivers instead and focus on what you decided and what it implies.
Note
Strategy is not the same as “technology list”.
A good strategy explains why a direction makes sense and what it implies.
This chapter often starts almost empty
Early in the design process, chapter 4 can be short.
That is normal.
As the design and build progresses, this chapter becomes the place where everything starts to connect:
quality goals, constraints, concepts, deployment choices, and runtime behavior.
If a strategy item is negotiable, keep it lightweight.
If it is truly a “heavy” direction setter, make sure it is backed by a constraint, a discussion, or an ADR.
Tip
Chapter 4 is also a good place to list open strategy questions that still need a decision.
A visible list of unknowns is more useful than pretending everything is decided.
The minimum viable version
If you are short on time, aim for a small set of strategy statements as concise bullets with just enough context to steer design.
A good “minimum viable” strategy statement usually contains:
Approach / decision (one line)
Rationale (one or two short lines: why this direction)
Consequence / impact (one short line: what this enables or constrains)
You do not need to hit an exact number of lines, you can combine them in a readable way.
The key is that the rationale and impact are clear and concise,
and that it is easy to see how the choice connects back to the drivers.
Copy/paste structure (Markdown skeleton)
Use this as a starting point and keep it small.
04-solution-strategy.md
## 4. Solution strategy
<1–3 short paragraphs: what is the overall approach and why?>
Strategy statements should be short.
If you need a full page to explain one item, you probably want to split details into another chapter and link to it.
Tip
Where you put open questions depends on how you work.
If your process is strategy-driven (pick direction first, then refine), keeping them in chapter 4 works well.
If your process is more risk-driven (track uncertainties and mitigation first),
you might prefer chapter 11 and link to them from here.
Example (Pitstop)
Pitstop is my small demo system for this series.
It is intentionally simple, so the documentation stays shareable.
This is what chapter 4 looks like when filled in.
4. Solution strategy
Pitstop is designed as an operational source of truth for work orders and status,
with near real-time synchronization between planning and workshop execution.
Modular monolith backend (initially)
Keep deployment simple and change-friendly while the domain stabilizes.
Modules are strict (no “grab-bag services”) and communicate via explicit interfaces.
Adapter-based integrations (Planning, Notifications, Parts status)
Each external system sits behind a port/adapter boundary to protect domain logic
and keep new integrations fast.
Traces to: Modifiability goal (≤ 2 days), Planning integration constraint.
Near real-time updates via push
Workshop and admin need shared truth quickly (≤ 2 seconds).
Use WebSocket/SSE where possible; fall back to efficient polling.
Traces to: Consistency goal, near real-time constraint.
Degraded-mode workshop operation
Workshop UI supports local queueing and later sync when connectivity returns.
Traces to: Resilience goal, degraded-mode constraint.
Audit-first changes for work order state
Every status change and important edits record who/when/why (immutable history),
enabling dispute resolution and throughput analysis.
Open strategy questions
Question: WebSocket vs SSE as the default push channel?
Affects real-time UX and infra constraints. Validate with UI needs + ops constraints.
Question: What conflict resolution approach do we use after offline edits?
Affects user trust and operational continuity. Define business rules with workshop stakeholders.
To browse the full Pitstop arc42 sample, see my GitHub Gist.
Common mistakes I see (and made myself)
No strategy statements
If chapter 4 is empty or just a placeholder, the architecture lacks direction.
Without strategy, designs drift and teams lose alignment.
Repeating the earlier chapters instead of linking
Chapter 4 should build on chapters 1, 2, and 3, not copy them.
Use links and focus on the consequences.
Only listing technologies We use Kubernetes is not a strategy. We deploy as containers because ops standardizes on it is.
No rationale
Without rationale, strategy statements look like preferences.
Tie each item back to a goal, constraint, or context boundary.
Treating consequences as a negative
Consequences are direction.
If a choice does not enable anything valuable for stakeholders, it is a smell.
Making it too detailed
Chapter 4 should be readable in a few minutes.
Details belong in other chapters and ADRs.
Hiding unknowns
If open questions only live in someone’s head, the team cannot contribute.
Making assumptions explicit invites feedback and prevents silent divergence.
Done-when checklist
🔲 Contains a small set of strategy statements (not a tech wishlist). 🔲 Each statement has a short rationale and a clear impact. 🔲 Statements link back to goals/constraints/context (chapters 1, 2, 3). 🔲 The choices feel stable enough to not change every sprint. 🔲 Open strategy questions are visible (here or in chapter 11), not hidden in someone’s head.
Next improvements backlog
Review strategy statements with ops and key external stakeholders for realism.
Add links to ADRs as decisions become concrete (chapter 9).
Add a short mapping from strategy to top quality goals.
Move unstable or controversial topics into “Open strategy questions” until decided.
Remove strategies that no longer serve stakeholder value (and document the change as an ADR).
Wrap-up
Chapter 4 is where the design starts to take shape.
It should be short, directional, and connected to the drivers you already captured in the first 3 chapters.
Chapter 3 draws the boundary of your system. If it is unclear what is inside and outside, integrations and expectations will break first.
In this article I show what belongs in chapter 3, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.
Chapter 3 is the last chapter in the “Why and where” group.
It is where you draw the line between your system and the outside world.
If that line is unclear, failures show up eventually:
unclear responsibilities, failing integrations, and mismatched expectations.
This chapter is split into two views:
Business context: who interacts with the system, and what value or information is exchanged.
Technical context: what interfaces exist, and how integration actually happens.
What belongs in chapter 3 (and what does not)
Chapter 3 of an arc42 document answers one question:
What is inside our system, what is outside, and how do we interact?
What belongs here:
A clear inside vs outside boundary.
External business actors and neighboring systems with responsibilities.
The direction of exchanges (who initiates, who responds).
Examples of value or data exchanged (not only APIs: files, emails, manual exports, spreadsheets, SFTP drops).
The most important interfaces (APIs, messaging, files, UI hand-offs, SSO, batch jobs).
Links to existing interface documentation (OpenAPI/AsyncAPI/specs) if it exists.
What does not belong here:
Internal building blocks and components (chapter 5).
Runtime scenarios and sequencing (chapter 6).
Deployment layouts (chapter 7).
Technical design details that do not cross the boundary.
Note
If there is no separate API documentation, chapter 3 is the place to document your interfaces.
Even when you can link to OpenAPI or AsyncAPI documents, include 1–2 small sample payloads here.
It makes the integration real and readable without forcing people to open a separate spec.
Diagrams: modeling tool or text-based
Diagrams make chapter 3 click.
You can draw them in a modeling tool like Sparx Enterprise Architect,
but you can also keep them close to the code using text-based diagrams.
I prefer PlantUML component diagrams for this chapter, because the system boundary and interfaces are easy to read.
Text-based diagrams work well because they are easy to diff, review, and version together with the documentation.
Tip
Use whatever keeps the diagram maintained.
A perfect diagram that nobody updates is less useful than a simple one that stays correct.
The minimum viable version
If you are short on time, aim for this:
One business context diagram (or a table) listing the key actors/systems and what they exchange.
One technical context diagram (or a table) listing the top interfaces with direction and protocol.
For the top 1–3 interfaces: add a short example (sample payload, file format snippet, or message shape).
That is enough to prevent most boundary and integration surprises.
When this chapter becomes high value
As soon as you have quality goals around availability, latency, or operational continuity,
your interfaces need a bit more than we call API X.
For your top interfaces, add:
SLA/SLO expectations and support windows
Failure behavior and fallback procedures
Retry/idempotency rules
Rate limits and quotas
Security and trust boundaries
This is often where the conversation moves from it depends to concrete trade-offs.
Pitstop is my small demo system for this series.
It is intentionally simple, so the documentation stays shareable.
This is what chapter 3 looks like when filled in.
3. Context and scope
3.1 Business context
Pitstop sits between planning and the workshop.
It keeps work orders and status in sync so people stop copying information between tools.
Actor/System
Responsibility
Exchanges with Pitstop
Customer
Brings car, receives updates
ETA updates (via advisor/portal)
Service Advisor
Manages appointment & expectations
Priority changes, notes, customer communication
Workshop Foreman
Orchestrates execution
Assignments, reprioritization
Mechanic
Performs work
Status updates, findings, time spent
Planning Service
Owns schedule/time slots
Appointment import, reschedule suggestions
Notification Service (optional)
Contact customers
SMS/email updates
3.2 Technical context
Peer
Interface
Owner
Direction
Protocol/Format
Notes
Planning Service
Appointments API
Planning vendor
Inbound
REST/JSON
Full import + incremental sync
Planning Service (optional)
Webhooks
Planning vendor
Inbound
HTTP/JSON
Push appointment changes
Planning Service
Status updates
Pitstop team
Outbound
REST/JSON
Delay, ready, reschedule proposal
Admin Overview UI
Work Orders API
Pitstop team
Bidirectional
HTTPS/JSON
RBAC, dashboards
Workshop View UI
Live Updates
Pitstop team
Bidirectional
WebSocket/JSON
Low latency, optimized payloads
Notification Service (optional)
Notifications API
Pitstop team
Outbound
REST/JSON
Customer updates
3.2.1 Interface: Appointments API
3.2.1.1 Examples
Appointment imported from planning:
{
"appointmentId": "A-10293",
"plate": "12-AB-34",
"start": "2026-01-12T09:00:00+01:00",
"service": "OilChange",
"customerRef": "C-4451"
}
3.2.2 Interface: Work Orders API
3.2.2.1 Examples
Workshop update from a mechanic:
{
"workOrderId": "WO-7781",
"status": "WaitingForParts",
"note": "Brake pads not in stock",
"updatedBy": "mechanic-17",
"updatedAt": "2026-01-12T10:41:00+01:00"
}
To browse the full Pitstop arc42 sample, see my GitHub Gist.
Note
Interfaces are not always APIs.
Manual exports, emailed files, spreadsheets, SFTP drops, and someone retypes it are also integrations.
If information crosses the boundary, document it here.
Common mistakes I see (and made myself)
Only naming neighbors, without exchanges
A box called CRM is not useful by itself.
Document what is exchanged and why.
Mixing business and technical context
Business context is about responsibilities and value.
Technical context is about protocols and integration mechanics.
Mixing them makes both harder to read.
Treating REST as the only interface
REST is common, but not universal.
File transfers, messaging, batch jobs, manual steps and spreadsheets all matter.
No ownership
If you do not document who owns an external interface, you will not know who to call when it breaks.
No direction We integrate with X is vague.
Who initiates, who is the source of truth, who is allowed to change state?
No examples
Even when you have OpenAPI or AsyncAPI, one small payload example prevents a lot of misunderstandings.
No expectations for critical interfaces
If availability or latency matters, document assumptions:
SLAs, failure behavior, retry rules, and fallback procedures.
Note
If an external stakeholder cannot recognize their responsibilities and expectations in this chapter,
the integration is not documented clearly enough yet.
Done-when checklist
🔲 The system boundary is clear (inside vs outside). 🔲 Business actors and neighboring systems are listed with responsibilities. 🔲 The top interfaces are listed with direction, protocol/format, and owner. 🔲 The most important integrations have 1–3 small examples (payload, file snippet, message shape). 🔲 Critical interfaces have expectations (SLA/failure behavior) or are explicitly marked as unknown.
Next improvements backlog
Add links to OpenAPI/AsyncAPI documents (or create them if missing).
Add SLA/SLO and failure behavior for the top 3 interfaces.
Add a short note about trust boundaries and data classification (if relevant).
Add examples for non-API integrations (file drop, manual export, batch job) if they exist.
Review chapter 3 with external stakeholders (planning vendor/team, ops, security) for recognition and correctness.
Wrap-up
Chapter 3 is where you make expectations explicit.
Most problems show up at the boundary first, so investing in this chapter pays off quickly.
This concludes the “Why and where” group of arc42 chapters.
Next, we move on to the “How is it built and how does it work” group.
Chapter 2 lists the non-negotiables that shape your design space. If you do not write these down early, they will still exist, but they will surprise you later.
In this article I show what belongs in chapter 2, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.
Chapter 2 is part of the “Why and where” group.
It is the chapter where you write down the rules you cannot break.
This is not about what you prefer.
It is about what your organization, environment, or stakeholders already decided for you.
If you do not document constraints early, they still shape the architecture.
You just discover them at the worst possible time.
Constraints also have a positive side: there are thousands of ways to build the same functionality.
A short list of non-negotiables helps you narrow down options early, before you invest in the wrong direction.
I have seen teams pick a public cloud technology because it fit the solution, while the product had to run air-gapped on-premises.
Or because it was “hot” (call it: conference-driven design), while operations would only support a single platform.
Money got wasted before someone finally said: this was never negotiable.
What belongs in chapter 2 (and what does not)
Chapter 2 of an arc42 document answers one question:
What limits our freedom, no matter what solution we pick?
What belongs here:
Organizational constraints (budget/time, team skills, governance, contracting).
Architecture choices you still get to make (save those for chapter 4 and chapter 9).
Personal preferences (I like microservices, we always use Kafka).
Detailed design, diagrams, protocols, or deployment layouts.
Note
A constraint is a rule you must follow.
A decision is a choice you make.
If you mix them, chapter 2 becomes a debate instead of a boundary.
Constraints exist on multiple levels
Organizations often have architecture and constraints at multiple levels (enterprise, domain, platform, product, application).
You can use arc42 at all those levels, but in practice most teams start at the bottom: an application or service.
That is also where chapter 2 becomes very practical:
many constraints already exist as company policies and standards.
Tip
Link to existing policies instead of rewriting them.
They tend to be stable, owned, and updated in one place.
Your chapter 2 should explain the impact, not duplicate the policy text.
Many policies ultimately follow from a company mission and vision.
So even if a constraint looks “technical”, it often exists for a business reason.
Writing down the rationale helps prevent this is stupid discussions later.
The minimum viable version
If you are short on time, aim for this:
8–15 constraints in a table
each constraint includes:
a clear statement
a type (organizational, technical, convention, integration, compliance)
a short rationale
the impact on design
a reference or owner (where it came from)
That is enough to prevent surprise constraints late and to make later decisions faster.
Copy/paste structure (Markdown skeleton)
Use this as a starting point.
02-architecture-constraints.md
## 2. Architecture constraints
Non-negotiables that shape the design space.
| Constraint | Type | Rationale | Impact on design | Reference |
- If a constraint has exceptions, describe the exception path.
- Link to standards, policies, or owners as references.
Note
A table is not mandatory.
If your constraints list grows, grouping them by type (e.g., organizational, technical, conventions, compliance) can be more readable.
The key is still the same: statement, rationale, impact, and source.
Example (Pitstop)
Pitstop is my small demo system for this series.
It is intentionally simple, so the documentation stays shareable.
This is what chapter 2 looks like when filled in.
2. Architecture constraints
Non-negotiables that shape the design space:
Constraint
Type
Rationale
Impact on design
Must integrate with Planning Service(s)
Integration
Existing ecosystem reality
API contracts, sync strategy, mapping rules
Near real-time UI updates
UX/Operational
Workshop coordination
Push updates (WebSocket/SSE) or efficient polling
Degraded-mode operation
Operational
Garage networks can be unreliable
Local cache/queue, retry, conflict handling
Containerized deployment
Platform
Standard ops model
Registry, base images, runtime policy
Automated CI + tests
Process
Fast feedback and reliability
Pipeline ownership + test environments
GDPR / minimal personal data
Compliance
Customer data
Data minimization, retention rules, audit controls
Deviations recorded as ADRs
Governance
Prevent silent divergence
ADR workflow and traceability (chapter 9)
To browse the full Pitstop arc42 sample, see my GitHub Gist.
Common mistakes I see (and made myself)
Writing constraints too late
If chapter 2 is empty, people will assume freedom that does not exist.
Then the first real constraint shows up during implementation, procurement, or security review.
Using vague words Secure, fast, cloud-ready are not constraints.
Write constraints as rules you can test against: must run on-prem, must be air-gapped, must use SSO.
Mixing constraints and decisions We will use PostgreSQL is usually a decision. We must use the company-managed PostgreSQL platform is a constraint.
If it is not truly non-negotiable, move it to chapter 4 or chapter 9.
No impact column
A constraint without impact does not help the team.
The value is in translating a rule into a design consequence.
Forgetting conventions and governance
Conventions feel boring until they break delivery: CI/CD rules, versioning, naming, documentation rules, ADR requirements.
Put them here so they are explicit.
Exceptions and experiments
Non-negotiable does not mean “never”.
Sometimes you run an experiment to learn, or you need an exception for a specific case.
Tip
When you make an exception, document it as an ADR and link it here.
The goal is not bureaucracy.
The goal is that the next team does not rediscover the same debate.
Done-when checklist
🔲 Chapter 2 contains the real non-negotiables, not preferences. 🔲 Each constraint has a clear impact on design and delivery. 🔲 Each constraint has a source (owner, standard, policy, or link). 🔲 The list is short enough to scan, but complete enough to prevent surprises.
Next improvements backlog
Review the list with ops, security, and the product owner (fast reality check).
Add links to central standards (security baseline, platform rules, CI/CD guidance).
Mark constraints that are assumptions and confirm them (or remove them).
Add ADR links for any local deviations from central architecture/platform rules.
Split the table into sub-sections if it grows (organizational, technical, conventions).
Wrap-up
Chapter 2 is where you protect your future self.
Constraints narrow the solution space, so later decisions become faster and more consistent.
Chapter 1 sets the direction for the entire architecture document. If you do not know why you are building this and who it is for, you cannot design it properly.
In this article I show what belongs in chapter 1, what to keep out, and a minimal structure you can copy, plus a small example from Pitstop.
Chapter 1 is part of the “Why and where” group. The audience for this chapter is everyone involved in the project.
Even nontechnical stakeholders should read and understand it.
It is the chapter that can prevent a lot of confusion later. You lay the foundation for everything that follows.
Not by adding too much detail (there are other chapters for that), but by making the intent explicit.
If you do not know why you are building this application and who it is for, you and your team cannot design it properly.
What belongs in chapter 1 (and what does not)
Chapter 1 of an arc42 document answers the “why” and “for whom” questions, without going into design.
What belongs here:
A short problem statement and what you are building.
The most important requirements (and explicit non-goals).
The top quality goals that will drive trade-offs later.
The key stakeholders and what they care about.
What does not belong here:
Component diagrams, deployments, protocols, and technical choices (save those for later chapters).
A complete requirements catalog (link to it if it exists).
Long background stories and project history.
Note
If you can only get one chapter right, get chapter 1 right.
Maybe quite obvious, but it is the chapter everyone will read first.
The minimum viable version
If you are short on time, aim for this:
One paragraph: what is the system and why does it exist?
5–10 bullets: the most important requirements.
3–5 quality goals: short and measurable.
A small stakeholder table.
That is enough to align a team and reduce surprises.
Tip
Chapter 1 is also a great place to add something recognizable, like a small logo or cover image.
It helps people quickly confirm they are reading the right document.
If you do not have a logo, an LLM image generator can help you create one quickly.
Copy/paste structure (Markdown skeleton)
Use this as a starting point and keep it small.
01-introduction-and-goals.md
## 1. Introduction and goals
<1–3 short paragraphs: what are we building, why now, what pain does it solve?>
Pitstop is my small demo system for this series.
It is intentionally simple, so the documentation stays shareable.
This is what chapter 1 looks like when filled in.
1. Introduction and goals
Garages struggle to keep planning and workshop execution in sync.
Most garages use a planning tool for appointments and a separate admin/workshop system for execution.
When jobs change (delay, extra work, parts missing), updates are handled manually.
Pitstop solves this by providing a single operational source of truth for work orders and status,
and synchronizing planning and workshop execution.
1.1 Requirements overview
Import appointments from one or more planning services.
Convert appointments into work orders (jobs/tasks, estimates, required skills, bay assignment).
Provide an admin overview (today’s workload, lateness, bay utilization, priorities).
Provide a workshop view (per bay/technician task list with fast status updates and notes).
Push status changes back to planning (delays, ready-for-pickup, reschedule proposals).
Explicit non-goals:
Pitstop is not the planning product.
Pitstop is not inventory management.
Pitstop is not billing/accounting.
1.2 Quality goals
Priority
Quality
Scenario (short)
Acceptance criteria (example)
1
Consistency
Admin + Workshop must show the same job state
Status updates visible in all UIs within <= 2 seconds under normal connectivity
2
Resilience
Workshop continues during flaky internet
Degraded mode works; updates sync when online
3
Modifiability
Add a new planning integration
New integration in <= 2 days for a typical planning REST API without changing core logic
To browse the full Pitstop arc42 sample, see my GitHub Gist.
Common mistakes I see (and made myself)
Only the name of the application
If chapter 1 starts with just System X and a few bullets, it does not help anyone.
Add 2–3 sentences that set the scene: what problem exists today, who feels the pain, and why building this is worth it.
Listing features instead of goals
Features are implementation ideas. Goals are outcomes.
If you can explain the outcome, the team can still choose the best solution later.
No explicit non-goals
Non-goals prevent scope creep and wrong expectations.
If something is out of scope, say so early, and say why.
No quality goals (or only vague ones)
If you do not write down quality goals, every trade-off later becomes a debate with no shared reference.
The hard part is that stakeholders often do not have a list.
A practical approach that works well:
Ask what would make this a success and what would make people complain.
Turn the answers into 3–5 short scenarios with one measurable criterion each.
Start with rough numbers. You can refine them later once you have usage data.
Stakeholders = the team or product owner
The development team is not the only stakeholder.
Everyone interacting with the system (directly or indirectly) is a stakeholder.
If you require something from them, or they expect a service from your system, include them.
A good way to expand the list:
End users (different roles, not one bucket)
Neighboring systems and their owners
Operations and support
Security, compliance, and governance
Business owners and managers
Done-when checklist
🔲 Chapter 1 fits on a few screens. 🔲 A new team member can explain the system after reading it. 🔲 Non-goals are explicit. 🔲 There are 3–5 quality goals with at least one measurable criterion each. 🔲 Stakeholders are mapped to expectations, not just listed.
Next improvements backlog
Add links to any existing requirement sources (backlog items, product brief, etc.).
Refine acceptance criteria based on observed production behavior.
Split stakeholders into “users” and “neighbors” if the list grows.
Add a short glossary entry in chapter 12 for any domain terms used in chapter 1.
Wrap-up
Chapter 1 is the compass. 🧭
It does not describe the architecture, it explains what the architecture must achieve.
