4. Architecture Documentation Structure Overview
This chapter shall give an overview and explanation of the arc42 template.
1 Introduction and Goals
This section shall describe the fundamental requirements that software architecture must fulfil. It summarizes functional and non-functional (quality) requirements.
1.1 Business Requirements Overview
Overview of business requirements. References to details requirements documentation, only minimal redundancy.
1.2 Stakeholder
A list of persons or organizations or organizational units influenced by or influencing the architecture.
1.3 Architecture Goals
The most important goals for the architecture. Please note these goals will most likely differ from the project goals of any implementation or release project. Quality requirements, like maintainability, flexibility, understandability belong to this category.
2 Architecture Constraints
Describes all factors limiting design decisions.
2.1 Technical Constraints
Hardware-, software and operational constraints (like operating systems, application servers, middleware etc.), development constraints (like version management systems, development process constraints etc.)
2.2 Organzational Constraints
Organizational standards and conventions, legal constraints.
2.3 Conventions constraining Architecture and Development
Programming and documentation guidelines, coding- or naming conventions, guidelines for version-, configuration- or test-management.
3 Context View
As mentioned in the previous chapter, different architectural views support understanding of the system as a whole. Chapter 3 to 6 of the architecture documentation are dedicated to these views, beginning with the top-level perspective, the context view. The context view secion describes the whole system as a blackbox with all its external interfaces. All relevant aspects of those interfaces shall be briefly described here:
- Kind of transmitted data
- Format of transmitted data
- Transmission media
- Transmission metadata (frequency of transmission, security, compression, transformation, synchron- or asynchronicity, monitoring, verification, handshake)
Alternatively, the details can be described in the corresponding building block sections.
The context view is refined in the building-block view in chapter 4 of the documentation template by revealing the inner structure of the system, hierarchically refinded.
## 3.1 Business (logical) Context Describes the function and context of the system from a business point of view, e.g. references to the major use-cases. Context can be documented using static UML diagrams, business processes or functions by sequence or activity diagrams.
Figure 1: Sample of Context View
3.2 Physical Context
Describe channels and media between system, its neighbours and its environment. Use UML deployment diagram plus textual description of elements.
4 Building Block View
The static architectural structure, describing the building blocks (subsystems, modules, components etc.) of the system. A building block is a structural unit, which has a representation in source code artifacts. This is the most important view, usually documented by a combination from static UML diagrams plus textual descriptions.
This structure is the result of architectural creativity, of the software-/system architect deciding upon how to break down the system into building blocks.
The building block description is organized by architectural levels, with the context view from the preceding chapter being level 0. Blackbox and whitebox descriptions are used alternately, as depicted in Figure 2.
Figure 2: Black- and Whitebox-Descriptions in Building
Block Hierarchy
In Figure 2 “level 1” is the whitebox of “level 0”. On level 2 the two different blackboxes from level 1 (named A and B) are refined in two distinct whitebox views. This kind of refinement is used throughout the building block view: Every blackbox can be refined by a whitebox at the next level of detail. This concept yields a tree structure of building blocks.
Within the documentation, this tree is mapped to the linear section structure:
- Level 1 of this view is documented in section 4.1, where every building block gets its own subsection 4.1.1 to 4.1.n.
- Level 2 is documented in section 4.2 and so forth.
The further one reads within this part of the architecture documentation, the more details are revealed about the system.
4.1 Building Block View Detail Level 1
The first part of any refinement shall always be a whitebox description, detailing the corresponding black-box of the previous level. Here, in level 1, this is the refinement of the whole system, its decomposition in layers, subsystems or similar building blocks.
Every whitebox description consists of the following elements:
-
Overview diagram: A diagram (UML packet, class or component diagram) depicting the struc-tural elements and their relationships and dependencies. Take this exam-ple (excerpt from Figure 2):
Figure 3: Whitebox of System-under-Design -
Local building blocks: Table or list with names brief descriptions of local building blocks. These local building blocks are all blackboxes! Their inner structure is revealed in the next level of detail. In the example above this would be two blackboxes A and B.
- Local relationships and dependencies: Table or list with brief descriptions of the dependencies. In the example, this would be the relationship between A and B.
- Design Decisions: Reasons or design decisions leading to this structure.
- (optional) Discarded design alternatives
- (optional) References and further information This section is a placeholder for other kinds of information one needs to understand this particular whitebox.
- (optional) Open issues
Now that one knows the structure of this part of the system its necessary to describe all the blackboxes in more detail, especially their purpose and their interfaces. That shall be done in the following subsections of the documentation conforming to the following scheme:
- Local building block A is detailed as blackbox in section 4.1.1 (and, with more detail, as a white-box in section 4.2.1)
- Local building block B is detailed as blackbox in section 4.1.2 (and, with more detail, as a white-box in section 4.2.2)
4.1.1 Building Block 1 (Blackbox Description)
Every blackbox shall be described according to the following scheme:
- Purpose & Responsibility: Describe the purpose or responsibility of this building block from the per-spective of its users. Keep this description brief, one to three sentences.
- Interface(s): Describe the inbound and outbound interfaces: what the building block delivers to others (outbound, provided interfaces) and what it expects from others (inbound, required interfaces)
- Fulfilled requirements: References or links to requirements that this building block either fulfills or supports.
- Variability: What may change about this building block or what is configurable.
- Location/File: A mapping of this building block to source artifacts (packages, classes, stylesheets or any other artifact). In case the building block is “large” or abstract, concentrate on the “important” artifacts: It is often superflous to enumerate all associated classes or files here, just mention the important ones. Every developer shall be able to identify all other associated artifacts with minimal effort.
- Further info: Author, Change history, version information and other things not found elsewhere.
- Open issues: Open questions, issues or risks associated with this building block.
On detailed levels of building-block descriptions, the major artifacts needed to implement the building block shall be referenced in section location/important files. The latter section should contain the main entry point (e.g. main class or classes, sitemap etc.) plus brief info on depencend artifacts (like buildfiles). Additional information is optional.
Please note: Refrain from giving too many details here. Usually developers
use their development environment to determine the current and complete
set of required artifacts, they do not consult written documentation for that
purpose. Furthermore there are substantial maintenance costs associated
with completeness, especially when in keeping a complete list of code artifacts.
4.1.2 Building Block 2 (Blackbox Description)
This shall be the blackbox description of the next building block from section 4.1. In the small example this would be building block “B”. The structure is exactly the same as shown in the table above, describing purpose&responsibilit, inter-faces, requirements, variability, location&files etc.
4.2 Building Block View Detail Level 2
In the preceeding section the level 1 building blocks have been documented as blackboxes. This current section (4.2) shows the next level of detail. In our example we need two subsections:
- Blackbox “A” from level 1 is detailed as whitebox in section 4.2.1
- Blackbox “B” from level 1 is detailed as whitebox in section 4.2.2
4.2.1 Whitebox view of Building Block 1, Level 2
In our example this is “A” from level 1. At first we describe this building block as whitebox, revealing its inner structure, togegher with the description elements already shown under section 4.1 above.
Figure 4 Sample Whitebox Overview of Building-Block „A“
(Level 2)
4.2.1.1 Building Block A1, Level 2, (Blackbox Description)
Blackbox description of building block A1, again conforming to the structure already mentioned above, describing purpose&responsibilit, interfaces, requirements, variability, location&files etc.
This documentation pattern (alternating white- and blackboxes) continues up to the granularity appropri-ate for the target audience of the documentation:
- Development stakeholders need more details, to enable efficient mapping of building blocks to code artifacts.
- Management, operations and testing/QA stakeholders need less detail.
4.4 Generic Dependencies & Patterns
Note: The number of this section depends on the depth of the building-block tree
(see Figure 2). With 3 levels of details number of this section is 4.4, but could
also be 4.5 or 4.6.
Sometimes the pure hierarchical decomposition in the different architectural levels does not suffice to describe all necessary dependencies between architecture building blocks. In that case you might docu-ment either generic or specific dependencies or patterns here:
- Generic dependencies or patterns occur in multiple places within the architecture.
- Specific dependencies occur only once and combine building blocks from different levels or pla-ces into one view.
Any number of such dependencies can be documented here, each one in its own subsection.
5 Runtime View
This view describes how the systems’ building blocks interact at runtime in different scenarios: * How are the most important use-cases handled? * How to (instances of) building blocks interact with their environment * How ist the system bootstrapped and/or started? * How are exceptions, system failures and error conditions handled? * How are external interfaces with their protocols (import/export to external systems) handled?
Use any dynamic UML diagram (e.g. activity-, sequence-, object-diagramm).
5.1 Runtime Scenario 1
Every scenario is documented with a diagram plus (optional) additional text within its own subsection.
6 Deployment View
Describes the various execution environments for the system, especially processors (nodes, where soft-ware building blocks are executed) and channels (over which data is transmitted). We distinguish between production, test and development environment, which can be described in their own subsections.
The respective stakeholders shall use this part of the documentation to properly install (and configure) the system in their environment.
Use UML deployment diagrams to depict nodes and channels. Note: Nodes can be nested. Every de-ployment-artifact shall be described here (e.g. every file
The structure of this view can vary: * Every environment in a subsection * Every node or type-of-node in a subsection
7 Design Decisions
Document major design decisions, at least those with either:
- long-lasting impact
- chances of surprising future developers or architects
- high risk
- high impact on any quality attribute
These decisions are documented in plain text without formal constraints.
8 Architecture Aspects
Architecture aspects are all crosscutting concerns which are not handled by a single building block within the application architecture or which are common to a number of building blocks.
9 Project Aspects
Issues indirectly concerning software or system architecture, but with strong relationsship to project management. Examples include identified risks, development team or location issues and similar stuff.
By the time you read this paragraph, you will be ready for prime time - just click over to the real arc42 template and dive into the details!