Skip to content
Software Architecture Guide

Data architecture documentation in arc42

Explanation

Section titled “Explanation”

arc42 has no single “data chapter”. Data-related material is spread across the template, and each place answers a different question.

Data flows in the context (Section 3). The business context shows the system as a black box. It names the communication partners and the domain interfaces between them. arc42 says all stakeholders should understand which data the system exchanges with its environment. It also advises showing data flows rather than plain dependencies. A line that says “uses” tells a reader little. A line that says what data moves tells much more.

The technical context is a separate view. It covers the channels and transmission media that link the system to its environment. It is typically drawn as a UML deployment diagram. See Business and Technical Context and arc42 Context and Scope.

Data structures in the building block view (Section 5). This view is a static decomposition of the system into building blocks. Building block types can include data structures. The view is mandatory in every arc42 documentation, so data structures have a place in a view that is always present. For the differences between conceptual, logical and physical models, see Conceptual, Logical and Physical Data Model.

Terms in the glossary (Section 12). The glossary lists the domain and technical terms stakeholders use. Its goal is one shared understanding, without synonyms (different words for one thing) and homonyms (one word for different things). arc42 tips suggest amending the glossary with a graphical model. See arc42 Glossary and Ubiquitous Language.

Domain data model in crosscutting concepts (Section 8). One arc42 tip says to document at least the business or domain data model there. Another tip says to combine domain models with the glossary. That link helps keep the model and the glossary consistent.

Example

Section titled “Example”

A web shop’s business context diagram shows the shop as one box. Arrows point to a payment provider and a delivery company. Each arrow is labeled with the data it carries, such as “payment request” or “parcel details”. The building block view lists an “Order” data structure as one block. The glossary defines “Order” in one sentence and shows a small diagram of how Order relates to Customer and Product. Everyone then uses the word “Order” the same way.

Trade-offs

Section titled “Trade-offs”

Spreading data material over several sections means readers must look in more than one place. The facts here do not say how to split detail between sections. Keeping a domain model and a glossary aligned also takes ongoing effort.

A business context sketch: the system is a black box and arrows are labeled with the data that flows.

Diagram source 
flowchart LR
  P[Partner] -->|order data| S[System as black box]
  S -->|confirmation data| P

Checks

Section titled “Checks”
  • The business context shows data flows between the system and its partners, not only dependencies.
  • The business context shows the system as a black box with domain interfaces to communication partners.
  • The building block view is present and any data structures appear as building blocks.
  • The glossary defines the domain terms stakeholders use and avoids synonyms and homonyms.
  • The domain data model is documented and combined with the glossary.
Section titled “Related”

Sources

Section titled “Sources”