Mano 禅マノ

Describing System Architecture In the previous chapter we started discus how we wanna solve our problem. How we intend to structure our system. Now is the moment to drill down into the building blocks. The Building block view is a multilevel Black box - White box view showing how the component are structured with modules, interfaces and classes. You can go down to package structure, framework and libraries. The level of detail depends by the level of information you have at the moment of writing and it can always be enriched during the project/product lifetime. From the arc42 documentation: - 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 (not shown in the diagram above) zooms into details of selected building blocks of level 2, and so on. Each black box in a layer becomes the white box of the next one. Ensure clarity in your source code structure by employing abstraction, facilitating an understandable hierarchy. This approach enables abstract-level communication with stakeholders while keeping implementation details undisclosed. Utilize the building block view, consisting of a hierarchical arrangement of black boxes and white boxes (refer to the figure below), accompanied by their respective descriptions. A possible structure form an Overall system to a level 3 decomposition. Level 1: Whitebox Overall System 1. Overview Diagram: Present a visual representation for a comprehensive view. 2. Motivation for Decomposition: Clearly articulate the reasons behind the chosen decomposition. 3. Black Box Descriptions: Describe the building blocks contained within. Consider the following alternatives: - Utilize a single table for a succinct overview of all building blocks and their interfaces. - Opt for a list of black box descriptions using the provided template (see below). Depending on the tool, this list can be organized as sub-chapters (in text files), sub-pages (in a Wiki), or nested elements (in a modeling tool). 4. Optional: Important Interfaces: If pertinent interfaces are not covered in the black box templates but are crucial for understanding the white box, include them optionally. Level 2 In this section, outline the internal structure of selected building blocks starting from level 1, representing them as white boxes. Decide judiciously which building blocks merit a detailed description, prioritizing significance over comprehensiveness. Focus on specifying details for crucial, unexpected, risky, complex, or dynamic building blocks. Exclude details for ordinary, straightforward, unremarkable, or standardized components of your system. 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 and create the needed additional layers. For each of the layer you can compile a table or a list for each component explaining the White Box view. You can mention the internals structure of your component with package structure, libraries and framework involved. This is one of the most important and possibly complex parts of the documentation. For some practical example you can find this list mentioned in the arc42 documentation: - Example Building Block View: HTML Sanity Checker(docs.arc42.org/examples/buil…) - Example Building Block View Level-1: Traffic Pursuit Unit(docs.arc42.org/examples/buil…) - Example Building Block View Level-2: Traffic Pursuit Unit(docs.arc42.org/examples/buil…) Bookmark and like this post if you found it useful. Follow me, If you are interested in more Software system architecture topic.