Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Building blocks, boundaries and dependency rules

Status
Review
Version
0.1.1
Authority
UASK standard
Applies to
Core
Markdown source

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