Building Block View

Content

The building block view shows the static decomposition of the system into building blocks (modules, components, subsystems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers, functions, macros, operations, datas structures, …) as well as their dependencies (relationships, associations, …)

This view is mandatory for every architecture documentation. In analogy to a house this is the floor plan.

Motivation

Maintain an overview of your source code by making its structure understandable through abstraction.

This allows you to communicate with your stakeholder on an abstract level without disclosing implementation details.

Form

The building block view is a hierarchical collection of black boxes and white boxes (see figure below) and their descriptions.

Hierarchy of building blocks

Level 1 is the white box description of the overall system together with black box descriptions of all contained building blocks.

Level 2 zooms into some building blocks of level 1. Thus it contains the white box description of selected building blocks of level 1, together with black box descriptions of their internal building blocks.

Level 3 zooms into selected building blocks of level 2, and so on.

Whitebox Overall System

Here you describe the decomposition of the overall system using the following white box template. It contains

an overview diagram
a motivation for the decomposition
black box descriptions of the contained building blocks. For these we offer you alternatives:
- use one table for a short and pragmatic overview of all contained building blocks and their interfaces
- use a list of black box descriptions of the building blocks according to the black box template (see below). Depending on your choice of tool this list could be sub-chapters (in text files), sub-pages (in a Wiki) or nested elements (in a modeling tool).
(optional:) important interfaces, that are not explained in the black box templates of a building block, but are very important for understanding the white box. Since there are so many ways to specify interfaces why do not provide a specific template for them. In the worst case you have to specify and describe syntax, semantics, protocols, error handling, restrictions, versions, qualities, necessary compatibilities and many things more. In the best case you will get away with examples or simple signatures.

<Overview Diagram>

Motivation: The system is split up based on its physical domain and interfaces on the first level.
Contained Building Blocks

Block	Description
Media Manager *	Manage active media content by taking commands via WAN or the remote control
LCD	Display video signal
Speaker	Play audio signal
AV component	Convert a raw media stream to separate audio and video signals

Block

Description

Media Manager *

Manage active media content by taking commands via WAN or the remote control

LCD

Display video signal

Speaker

Play audio signal

AV component

Convert a raw media stream to separate audio and video signals

* Due to a central role in the system the media manager is detailed in a separate sub chapter.

Insert your explanations of black boxes from level 1:

If you use tabular form you will only describe your black boxes with name and responsibility according to the following schema:

Name	Responsibility
<black box 1>	<Text>
<black box 2>	<Text>

Name

Responsibility

<black box 1>

<Text>

<black box 2>

<Text>

If you use a list of black box descriptions then you fill in a separate black box template for every important building block . Its headline is the name of the black box.

Media Manager

Here you describe <black box 1> according the the following black box template:

Purpose/Responsibility
Interface(s), when they are not extracted as separate paragraphs. This interfaces may include qualities and performance characteristics.
(Optional) Quality-/Performance characteristics of the black box, e.g.availability, run time behavior, ….
(Optional) directory/file location
(Optional) Fulfilled requirements (if you need traceability to requirements).
(Optional) Open issues/problems/risks

<Purpose/Responsibility>

The task of the media manager is to play the content that the user is requesting. It needs to interpret input requests and transfer the appropriate media stream to the AV component.

<Interface(s)>

Table 1. Media Manager technical interfaces
Interface	Description	I/O
LAN	Online streaming content is controlled via LAN	in:media control
WAN	An internet connection is used by the system to update its firmware via the Manufacturer or to fetch online content	out:HTTPS
Remote Control	A remote control is used by the Owner to modify the system state	in:physical interaction
Satellite	Using the `DVB-S` standard television program is received by the system	in:DVB-S
Media Stream	A raw media stream is sent to the AV component for further processing	out:raw stream

<Quality/Performance Characteristics>

Level 2

Here you can specify the inner structure of (some) building blocks from level 1 as white boxes.

You have to decide which building blocks of your system are important enough to justify such a detailed description. Please prefer relevance over completeness. Specify important, surprising, risky, complex or volatile building blocks. Leave out normal, simple, boring or standardized parts of your system

Media Manager

…describes the internal structure of building block 1.

This is an explanation of the media manager subsystem written in another repository.

Level 3

Here you can specify the inner structure of (some) building blocks from level 2 as white boxes.

When you need more detailed levels of your architecture please copy this part of arc42 for additional levels.

White Box <_building block x.1_>

Specifies the internal structure of building block x.1.

<white box template>