---
id: arch.building-blocks-and-dependencies
title: Building blocks, boundaries and dependency rules
kind: practice
domain: architecture
description: Divide a system into building blocks with a reason, an owner and a public interface for each, and state the dependency rules between them as numbered rules that a check can enforce.
version: 0.1.1
status: review
authority: uask
applies_to: [core]
sources:
  - title: D. L. Parnas, "On the Criteria to Be Used in Decomposing Systems into Modules" (1972)
    url: https://dl.acm.org/doi/10.1145/361598.361623
    license: LicenseRef-All-Rights-Reserved
    accessed: 2026-11-21
  - title: Eric Evans, "Domain-Driven Design Reference" (2015)
    url: https://www.domainlanguage.com/ddd/reference/
    license: CC-BY-4.0
    accessed: 2026-11-21
  - title: C4 model — Container diagram and Component diagram
    url: https://c4model.com/diagrams/container
    license: CC-BY-4.0
    accessed: 2026-11-21
standards: [ISO/IEC/IEEE 42010:2022, arc42 template 9.1 (October 2026)]
requires: [arch.architecture-description, arch.c4-model, arch.context-and-interfaces]
related: [arch.adr, arch.quality-attributes, mgmt.governance-tiers, arch.architecture-review, arch.fitness-functions]
last_reviewed: 2026-11-21
review_every: 6
---

## Summary

A building block is a part of the system that has a reason to exist apart from the others, an owner, a public interface
and an inside that others do not touch. Where the blocks are cut decides how easy the system is to change, and the
rules about who may depend on whom keep the cuts from wearing away. This item says how to find boundaries (around a
decision that may change, around a meaning of the domain's words, around an owner), how to list the blocks in section 5
of the Blueprint, and how to write the **dependency rules** as numbered rules that an automatic check can enforce
(`arch.fitness-functions`).

## Rules

### Blocks and boundaries

- **R1.** Section 5 of the Blueprint (`arch.architecture-description`) MUST list every building block with an id (`B-1`,
  `B-2`, …) that is never reused, a name, one sentence on its responsibility, the decision or meaning it hides, the
  interfaces it offers, the blocks it depends on, its owner and its technology. The blocks are the containers of the
  container diagram and, where one is drawn, the components of a component diagram (`arch.c4-model`), under the same names.
- **R2.** A boundary MUST have a reason: a design decision that may change and that the block hides from the others, a
  meaning of the domain's words that holds inside it and not outside, or a unit that is deployed or owned on its own. A
  block with none of these SHOULD be merged into a neighbour.
- **R3.** Every block MUST have one owner, a person or a role that answers for it. A block that two owners share MUST be
  split, or its shared part MUST be named as a shared kernel (R10).
- **R4.** Other blocks MUST use a block only through its public interface. What the block does not list as public is
  internal, and other blocks MUST NOT depend on it. The interfaces between blocks inside one system are listed in section 5;
  the ones that cross the boundary of the system are rows of the inventory of `arch.context-and-interfaces`.

### Dependencies and their rules

- **R5.** Every dependency between blocks MUST be listed with its direction. Dependencies between blocks MUST NOT form a
  cycle. A cycle that exists MUST be broken or recorded in the technical-debt register with a date for its removal.
- **R6.** The Blueprint MUST state its dependency rules as numbered rules (`DR-1`, `DR-2`, …) that are never reused. Each
  rule MUST give its statement (which blocks may or may not depend on which), its reason (a quality goal, an ADR or a
  constraint), and its check: an automatic check, or "manual until" a date.
- **R7.** At the standard tier and above, a dependency rule that a pull request can break MUST have an automatic check, or
  a dated plan to have one. A rule written in the Blueprint and enforced by nothing SHOULD be treated as a wish.
- **R8.** Dependencies SHOULD point from the blocks that change often to the blocks that change rarely. The part that
  holds the business's own rules SHOULD NOT depend on delivery details such as the web framework, the database driver or a
  vendor's library.
- **R9.** A block that uses an external system or a framework whose model differs from the project's SHOULD reach it
  through one adapter block, so that the foreign model does not spread. Each external library, framework or service
  MUST be named in the block that uses it, with its version policy.

### Blocks that other teams own

- **R10.** A relationship to a block that another team or project owns MUST be named with one of the patterns of the
  Guidance (partnership, shared kernel, customer and supplier, conformist, anticorruption layer, open-host service with a
  published language, or separate ways) and MUST be recorded in the row of the interface inventory that it concerns.

### Change and tiers

- **R11.** A change to a boundary or to a dependency rule MUST be recorded as an ADR when it is hard to reverse
  (`arch.adr`) and MUST change section 5 in the same pull request. A rule and its check MUST change together.
- **R12.** At the lightweight tier, the blocks MAY be a short table and at least one dependency rule MUST be stated, with
  its reason, and checked by hand if no tool is available. At the standard tier, all the rules apply. At the
  high-assurance tier, every dependency rule MUST have an automatic check that proves itself, as the
  fitness-functions item describes, and the check for cycles MUST run on every change.

## Guidance

### What a block is

A block is the unit of section 5. In C4 terms it is a container, or a component inside a container that is too complex to
read as one unit. The word "block" is used so that the rules read the same at both levels. Draw it as C4 asks
(`arch.c4-model`) and list it as R1 asks: the diagram shows the blocks and their lines, and the table says why.

### Finding the boundaries

Start from three questions and write the answers down. Where they agree, the boundary is easy; where they disagree, the
disagreement is the thing to decide, and an ADR records it.

1. **What will change?** Make a list of the design decisions that are hard or likely to change: the payment provider, the
   storage, the format of a file, the look of the pages. Give each its own block, so that the decision is hidden in one
   place and a change touches one block. This is the information-hiding criterion of Parnas (1972), who showed that cutting
   a system by the steps of its processing is almost always the wrong cut.
2. **What do the words mean?** A word such as "order" or "customer" can mean different things in the shop, in
   fulfilment and in accounting. Where a word changes meaning, a boundary runs. In Evans's words, a bounded context is
   the boundary within which a particular model is defined and applicable.
3. **Who owns it?** A block that one owner can hold in mind and change alone is easier to keep honest. If a split of the
   blocks cuts across the split of the owners, expect friction and say so.

### The block table

The table in section 5 is the one source for R1. A row looks like this:

| Id | Block | Responsibility | Hides | Offers | Depends on | Owner | Technology |
|---|---|---|---|---|---|---|---|
| B-3 | Payment adapter | Starts a payment and reports its result | the payment provider's model and version | `start(order)`, `result(order)`; row I-1 and I-2 | B-2 | lead | PHP 8.2 |

### Dependency rules

A dependency means that a block breaks when the other changes. The rules say which dependencies are allowed. The usual
kinds:

| Kind | Example of a rule |
|---|---|
| Direction | The pages (B-1) may use the catalogue (B-2); the catalogue never uses the pages |
| Isolation | Only the payment adapter (B-3) may call the provider; no other block names the provider |
| Public only | Blocks use the order module through its interface; none reads its tables |
| No cycles | No block is reachable from itself through dependencies |
| Read only | The export (B-4) reads orders and never writes them |
| Placement | Code that touches the database lives only in the modules that own the data |

Write a rule so that a person or a tool can tell whether a given line of code breaks it: name the blocks, or a pattern of
file paths, and the direction. State its reason, because a rule without a reason is the first to be broken, and its
check, because a rule without a check is not a rule (the next item, on fitness functions, says how to write one that
proves itself).

### Relationships to blocks that others own

Evans's strategic design gives names to the ways two teams' models meet. The Hub uses these seven rows for the
relationship between a block and another team's block; the sixth joins two of Evans's patterns, the open-host service
and the published language.

| Pattern | What it means in a sentence |
|---|---|
| Partnership | the two teams succeed or fail together and plan their changes together |
| Shared kernel | a small part of the model and code that both teams share and change only by agreement |
| Customer and supplier | the downstream team's needs are planned into the upstream team's work |
| Conformist | the downstream team accepts the upstream model as it is, with no say |
| Anticorruption layer | the downstream team translates the upstream model into its own, in one place |
| Open-host service with a published language | the upstream team offers a stable, documented interface and a shared format to everyone |
| Separate ways | the two teams agree to have nothing to do with each other |

Choose the cheapest one that fits, and record it. A conformist relationship with a provider that you cannot influence is
honest; an anticorruption layer there costs a block and buys independence.

### Tailoring by tier

| Tier | Blocks | Dependency rules |
|---|---|---|
| Lightweight | a table of the blocks | at least one rule, with its reason; a manual check is enough |
| Standard | the full table; patterns for the other owners' blocks | each rule has an automatic check or a dated plan |
| High-assurance | as standard | each check proves itself; the cycle check runs on every change |

## Explanation

**Why boundaries around decisions.** The usual way to cut a system is by the steps of what it does: read, process,
write. Parnas compared that cut with one made by the decisions that each part hides, and showed that the second survives
change far better, because a change to one decision touches one module. The same view makes the owner column meaningful:
the owner of a block is the owner of its hidden decision.

**Why meanings, too.** A model is true inside a boundary. The same word in two places holds two models, and forcing one on
both makes each worse. Domain-driven design names the boundary and the ways the two models meet, so that the meeting can
be designed and not left to chance.

**Why rules and not diagrams.** A diagram can say "the pages use the catalogue", but it cannot fail when someone makes the
catalogue call the pages. A rule with a check can. The Blueprint states the rule; the check keeps it true; the ADR keeps the
reason. R11 makes them move together.

**Why no cycles.** Two blocks that depend on each other cannot be changed, tested or understood apart. A cycle is also how
a boundary dies: each shortcut seems small. The check for cycles is cheap and catches the whole class.

**Why arc42 by reference.** The Blueprint's section 5, the building block view, follows arc42's order. The Hub cites the
structure by reference (`arch.architecture-description#R13`) and writes its own text.

## Examples

**Good.** A synthetic example: the blocks of a small UK web shop that sells refurbished bicycles, at the standard tier. B-1
to B-5 are the components of the Storefront container of the container diagram in `arch.c4-model`; the database is its
other container.

| Id | Block | Responsibility | Hides | Offers | Depends on | Owner | Technology |
|---|---|---|---|---|---|---|---|
| B-1 | Storefront pages | Show products, basket and checkout | the look of the pages | the shop's pages; rows I-6 | B-2, B-3 | lead | PHP 8.2, theme |
| B-2 | Catalogue and orders | Hold products, stock and orders | the shop's data model | its public functions | none | lead | PHP 8.2, OpenCart core |
| B-3 | Payment adapter | Start a payment, report its result | the provider's model and version | `start(order)`, `result(order)`; rows I-1, I-2 | B-2 | lead | PHP 8.2 |
| B-4 | Order export | Write the nightly file for the accountant | the accountant's file format | the nightly file; row I-3 | B-2 | owner | PHP 8.2, cron |
| B-5 | Admin | Let staff edit products and see orders | the staff's screens | the admin pages | B-2 | owner | PHP 8.2, OpenCart admin |

Dependency rules:

| Rule | Statement | Reason | Check |
|---|---|---|---|
| DR-1 | B-1, B-3, B-4 and B-5 use B-2 only through its public functions; none reads its tables | goal 4, maintainability (B-2 may change its tables) | a script lists direct table names outside B-2 and fails on any |
| DR-2 | Only B-3 calls the payment provider | ADR 0004, the hosted payment page | a script searches for the provider's address outside B-3 |
| DR-3 | B-4 reads orders and never writes them | the accountant's file must not change an order | the export runs under a database account with read rights only |
| DR-4 | No cycles between blocks | R5 | a script builds the graph of the blocks and fails on a cycle |

The relationships: the shop has no say in the payment provider's model, so B-3 is an **anticorruption layer** that keeps
that model out of B-2; the accountant's file is a **customer and supplier** relationship, with the accountant as the
customer, recorded in row I-3 of the interface inventory.

**Bad.** "Blocks: frontend, backend, database." The three boxes have no reasons, no owners and no public interface, so every
part uses every other. The rule "never call the database from the pages" is written in the README and checked by nobody, and a
shortcut in the third release breaks it. R1, R2, R4 and R6 are missed.

## Sources

- [D. L. Parnas, "On the Criteria to Be Used in Decomposing Systems into Modules"](https://dl.acm.org/doi/10.1145/361598.361623)
  — Communications of the ACM, December 1972; copyright ACM, so cited and paraphrased, not copied; information hiding as
  the criterion for a boundary. Accessed 2026-11-21 (the text was read on a university-hosted copy, because dl.acm.org
  refuses automated requests).
- [Eric Evans, "Domain-Driven Design Reference"](https://www.domainlanguage.com/ddd/reference/) — CC BY 4.0; the bounded
  context and the patterns of context mapping, in the Hub's own words. Accessed 2026-11-21.
- [C4 model — Container diagram](https://c4model.com/diagrams/container) and [Component diagram](https://c4model.com/diagrams/component) — Simon Brown,
  CC BY 4.0; the levels at which blocks are drawn. Accessed 2026-11-21.
- ISO/IEC/IEEE 42010:2022 — referenced by name and edition only.
- [arc42 template, edition 9.1 (October 2026)](https://docs.arc42.org/home/) — CC BY-SA 4.0; referenced for the order of
  the Blueprint's sections only; no text is adapted (`arch.architecture-description#R13`).
