Building blocks, boundaries and dependency rules
- Status
- Review
- Version
- 0.1.1
- Authority
- UASK standard
- Applies to
- Core
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.
- 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.
- 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.
- 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” — 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” — 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 and Component diagram — 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) — CC BY-SA 4.0; referenced for the order of
the Blueprint’s sections only; no text is adapted (
arch.architecture-description#R13).