#1: Finished top-level building block breakdown.

Task-Url: http://github.com/itsallcode/openfasttrace-architecture-template/issues/1

Author: sebastian

doc

@@ -43,7 +43,7 @@
           <dependency>
             <groupId>net.sourceforge.plantuml</groupId>
             <artifactId>plantuml</artifactId>
-            <version>8059</version>
+            <version>	1.2018.8</version>
           </dependency>
         </dependencies>
       </plugin>

pom.xml

@@ -0,0 +1,85 @@
+# Building Block View
+
+> OFT: This chapter is usually every readers favorite. First because it usually contains a lot of pictures, second because it advances the understanding of the system most.
+
+This chapter contains the building block breakdown of the system.
+
+## Building Blocks, Components, Compositions and Software Units
+
+The diagram below shows the relation of components, compositions and software units.
+
+![Components vs. compositions vs. software units](uml/component/comp_units_components_and_compositions.svg "Components vs. compositions vs. software units")
+
+Building blocks are system components and we will use the two terms synonymously throughout this document.
+
+Components come in two flavors: Software Components and Hardware Components.
+
+Compositions are constructed from sets of components. From an outside-perspective they are components to.
+
+Defining Software Units is trickier than it looks at first glance because it is much easier to find criteria to define what isn't a Software Unit than to find hard criteria that defines what is one.
+
+> OFT: Many projects try to avoid that problem by defining that a Software Unit is a single class, but that contradicts the idea that software units should be reusable without modification in another project. Copying single classes between projects is not a promising practice.
+
+We define a Software Unit as a Software Component that cannot be split further without sacrificing reusability.
+
+> OFT: there is heated discussion between software developers whether or not you are allowed to test below the level you defined for your software units.
+
+> OFT: The contra-faction usually states that you do not have written requirements below unit level and therefore no definition for what to test.
+
+> OFT: The pro-faction dismisses this argument saying that the developer knows what algorithms need to do even below unit level, otherwise they would not be able to implement them. From our experience this approach is more practical in real-world projects. It also helps you locating error more precisely.
+
+## How Building Block Relations are Depicted in this chapter
+
+The associations between the components represent "A-knows-B" relationships. This helps determining dependencies between the components. They are directed associations. The aim is to avoid circular dependencies between the components. Bidirectional associations must also be avoided since they are only a special form of a circular dependency.
+
+![Circular dependencies](uml/component/comp_circular_dependencies.svg "Circular dependencies")
+
+Circular dependencies would create unacceptable constraints on the development life cycle and deployment of the components.
+
+Since the circle has no start, there is no component that you could deploy first without creating a broken dependency for at least a short time. This means that you have to release and deploy all components at the same time which is bound to fail.   
+
+## Building Block Overview
+
+This section contains the building block breakdown on the highest level.
+
+![Building block overview](uml/component/comp_overview.svg "Building block overview")
+
+## Top-Level Building Blocks
+
+> OFT: In this section you give a short description of the building blocks at the highest level of abstraction. It is a good idea to roughly define what they are responsible for.
+
+> OFT: If you want to make sure the components you define in this architecture appear in the actual detailed designs (and in the implementations) we recommend that you create one specification item for each internal component and require coverage on detailed design level (here `dsn`). Of course you should talk the component breakdown through with the implementing teams in order to get their agreement. Otherwise you will end up with a nice architecture document that nobody cares about.
+
+### AutoYummyBox
+`arch~ayb.autoyummybox~1`
+
+This hardware component is a vending machine with a built-in 3D food printer. It is responsible for printing and cooking the dishes.
+
+Needs: dsn
+
+> OFT: Note that we did not cover a SRS requirement with this component decision. The reason is simple: you would have to link each SRS requirement that is implemented in this component with the component in addition to the runtime requirements. This is way to error-prone to be practical and also not very helpful.
+
+### MachineApplication
+`arch~ayb.machine-application~1`
+
+The MachineApplication is an embedded software that controls the operation of the [AutoYummyBox](#autoyummybox) hardware and communicates with the [MachineManager](#machinemanager) backend.
+
+Needs: arch
+
+### MachineManager
+`arch~ayb.machinemanager~1`
+
+The MachineManager is a backend component that serves as a single entry point for all communication with the [MachineApplication](#machineapplication).
+
+Needs: arch
+
+> OFT: ...
+
+> OFT: We stop the enumeration of top-level components at this point of the example because adding more would not contribute to a better understanding
+
+> OFT: Next comes a breakdown of the internal component structure of the previously defined top-level components. We recommend to keep each in a separate file since it is likely that different authors will have to work on the details in parallel in projects of a certain complexity.
+
+## Sub-Level 1 Building Blocks
+
+* [MachineApplication Building Blocks](building_blocks/MachineApplication.md)
+* ...

src/main/resources/markdown/building_blocks.md

@@ -0,0 +1 @@
+# MachineApplication

src/main/resources/markdown/building_blocks/MachineApplication.md

@@ -8,13 +8,27 @@ OFTAutoYummi uses a backend connection via the Internet to report fill level of
 
 Check [System Scope and Context](context.md) for an overview of the systems connections to external actors and neighboring systems.
 
+## About This Document
+
+### Target Audience
+
+The target audience are persons involved with the construction of the system, technical decisions and quality assurance. See section ["Stakeholders"](#stakeholders) for more details. 
+
+### Notational Conventions
+
+Requirements in this document are written in "Requirment enhanced Markdown format" which is the native specification format of [OpenFastTrace (OFT)](https://github.com/itsallcode/openfasttrace). If you want to learn more about this format please check the [OpenFastTrace User Guide](https://github.com/itsallcode/openfasttrace/blob/master/doc/user_guide.md).
+
+Using this format allows you to scan the requirement chain using OFT to see if all requirements from the user-level [System Requirement Specification (SRS)](bibliography.md#srs) are covered.
+
+The name part of the requirement IDs contains the prefix `ayb.` (for "AutoYummyBox") in order to avoid ID collisions when the specification is used in a wider scope cross-project. 
+
 ## Requirement Overview
 
 > OFT: We recommend that you reference the system requirements specification (SRS) of your project here. Repeating the user-level requirements would break the single-source principle — aka. "don't repeat yourself (DRY)".
 
 > OFT: Generally speaking though the arc42 template contains this section, we do recommend to keep these requirements in a separate document since the life cycle and responsible persons are different for system requirements and system architecture.
 
-See [OFTAutoYummy System Requirement Specification](../bibliography.md#SRS)
+See [OFTAutoYummy System Requirement Specification](../bibliography.md#srs)
 
 ## Quality Goals
 
@@ -39,7 +53,7 @@ This section list the target audience of the system architecture and their inter
 
 > OFT: Hint: always use plural when referring to roles. This keeps your specifications gender-neutral especially when using pronouns. 
 
-For a list of OFTAutoYummi's stakeholder contacts and their responsibilities please refer to the [OAY-ORGA](../bibilography.md#OAY-ORGA).
+For a list of OFTAutoYummi's stakeholder contacts and their responsibilities please refer to the [OAY-ORGA](../bibilography.md#oay-orga).
 
 > OFT: Usually only certain chapters are interesting for an individual project role. You can help your readers finding the relevant information more quickly by listing the chapters they should read.
 

src/main/resources/markdown/introduction.md

@@ -0,0 +1,13 @@
+# Solution Strategy
+
+> OFT: This chapter is a tricky one. The original arc42 template states that you should outline your main architectural decisions here, for example how you plan to reach your quality goals.
+
+> OFT: While we can understand the benefits of drawing lines on a grand scale, this approach has multiple problems.
+
+> OFT: First understanding those decisions usually requires knowledge of details that will appear in later chapters. Decisions that are not justified by facts that you presented before are hard to accept for your readers.
+
+> OFT: Second this chapter is bound to create duplicated information especially when compared to the [Design Decisions](design_decisions.md) chapter and duplications are a major source of error.
+
+> OFT: Third the job of a system or software architecture is to keep as many decision options open for as long as possible. If you draw the lines to early and to strictly you are removing freedom from the designers that could have given you a better overall solution. 
+
+> OFT: Our recommendation is to remove this chapter unless you have uncountermandable decisions that everyone needs to get over before starting to work on a solution. A prime example would be if your company enforces a strict book of standards for technical systems that does not allow for solutions outside of that box. In this case you can either deal with it and find the best remaining solution within the confines of these regulations, spend your time trying to get the book of standards adapted to your needs or leave for a company that understands the necessity of picking the right tool for the job.

src/main/resources/markdown/solution_strategy.md

@@ -0,0 +1,3 @@
+@startuml
+component AuthenticationAndAuthorizationProvidern as AAProvider
+@enduml

src/main/resources/uml/components/AAProvider.plantuml

@@ -0,0 +1,3 @@
+@startuml
+component AutoYummyBox <<hardware>>
+@enduml

src/main/resources/uml/components/AutoYummyBox.plantuml

@@ -0,0 +1,3 @@
+@startuml
+component MachineApplication [[../../building_blocks/MachineApplication.html]]
+@enduml

src/main/resources/uml/components/MachineApplication.plantuml

@@ -0,0 +1,3 @@
+@startuml
+component MachineManager
+@enduml