Architecture Guideline#
Architectural Design Guideline
|
status: valid
|
||||
The guideline focuses on the steps which need to be performed in order to create the architectural design. The concept behind those steps is described in the Architecture Process.
General Hints#
Attributes#
For all architectural elements, the following mandatory attributes are defined:
Title |
ID |
|---|---|
Architecture attribute: fulfils |
|
Architecture attribute: safety |
|
Architecture attribute: security |
|
Architecture attribute: status |
|
Architecture attribute: UID |
Checks#
For architectural elements, the following checks are defined:
Title |
ID |
|---|---|
Check of Architecture mandatory attributes |
|
Check of Architecture linkage requirement |
|
Check of Architecture linkage requirement type |
|
Check of Architecture linkage metamodel |
|
Check of Architecture linkage safety |
|
Check of Architecture linkage security |
Workflow for creating an architectural design#
This chapter describes the general guideline for architectural design within the project. In general, the workflow for creating an architectural design is shown in Architecture Design Workflow.
Those steps are:
Step |
Description |
Responsible |
|---|---|---|
Merge architectural design into score repository |
||
Merge component architectural design into module |
Create feature architecture (Concept)#
The feature architecture (= high-level architecture) shall be created in the feature tree of the platform repository.
For this step, the following guidance is available: Feature Architecture Template (gd_temp__arch_feature). Based on this template, the feature architecture shall describe the concept of the feature, including supporting figures and drawings. Additionally, you should consult your project’s specific guidelines, e.g., for using the version management tooling or architecture element naming conventions, which should be defined (or linked) in the Project SW development Plan (wp__sw_development_plan).
Model feature architecture#
Based on the concept description, a model of the feature architecture shall be designed. It shall consist of the logical interfaces which the user of the feature can access, including the modules which provide the interfaces. Therefore, the following elements shall be used:
Element |
Sphinx directive |
|---|---|
Feature Architecture |
feat, feat_arc_sta, feat_arc_dyn |
Logical Interface |
logic_arc_int |
Logical Interface Operation |
logic_arc_int_op |
The relations of the static elements are described in Definition of the Metamodel for Architectural Design.
Note
For the modelling of the architecture a sphinx extension is available: Architecture Generation for Sphinx-Needs
An example of modelling the architecture can be found here.
Allocate feature requirements to architectural elements#
In the next step, the already derived feature requirements shall be allocated to the architectural elements depending on the content of the requirement. Functional requirements may either be allocated to static or dynamic architecture. Interface requirements shall only be allocated to the interface architecture.
If needed, additional feature requirements, which may arise due to architectural decisions, should be created and allocated to the feature architecture itself.
These links shall be established from architectural elements to feature requirements via the attribute fulfils.
Review architectural design#
As soon as the design is in a mature state, it can be reviewed according to Work product Inspections Co... (doc_concept__wp_inspections) and merged into the main branch of the score repository. See also the document life-cycle guideline Documentation (gd_guidl__documentation) for more information about the documentation for the feature architecture Feature Architecture (wp__feature_arch).
For the review process, a checklist template is available: Architecture Inspection Checklist Template (gd_chklst__arch_inspection_checklist).
The following roles should be included in the review:
Create component architecture (Concept)#
Based on the feature architecture, the concept for the component architecture shall be created in the SW module. It shall describe which components need to be created and how they correlate with each other in order to provide the required functionality. As a starting point, a template (gd_temp__arch_comp) is provided.
For this step, the following guidance is available: Feature Architecture Template (gd_temp__arch_feature). Additionally, you should consult your project’s specific guidelines, e.g., for using the version management tooling or architecture element naming conventions, which should be defined (or linked) in the Project SW development Plan (wp__sw_development_plan).
Allocate component requirements to architectural elements#
In this step, the component requirements shall be derived (see Requirements Guideline) and allocated to the architectural elements via the attribute fulfils.
Model component architecture#
According to the architecture design description, the model for the component architecture shall be created. It shall consist of components, real interfaces and real interface operations. Depending on the size of the component, it can also be split into multiple (lower-level) components.
Element |
Sphinx directive |
|---|---|
Component Architecture |
comp, comp_arc_sta, comp_arc_dyn |
(Real) Interface |
real_arc_int |
(Real) Interface Operation |
real_arc_int_op |
The relations of the static elements are described in Definition of the Metamodel for Architectural Design.
Review component architecture#
As soon as the design is in a mature state, it can be reviewed and merged into the main branch of the module repository. See also the document life-cycle guideline Documentation (gd_guidl__documentation) for more information about the documentation for the component architecture Component Architecture (wp__component_arch).
Following roles should be included in the review:
For the review process, a checklist template is available: Architecture Inspection Checklist Template (gd_chklst__arch_inspection_checklist).
UML diagram selection#
Static architecture#
As can be seen from the examples presented in Feature 1 Architecture (feat_arc_sta__example_feature__feature_1) and Component 1 Static View (comp_arc_sta__example_feature__archdes_component_concept_1) for the static architecture a UML component diagram is expected (and supported by the tooling).
Dynamic architecture#
The Architecture Process (doc_concept__arch_process) shows the usage of UML sequence diagrams to describe dynamic behaviour. This is also the expected default diagram. Alternatively, state machine diagrams can be used to describe stateful behaviour. Other types like the activity diagram are not encouraged to use, if an activity diagram is used instead of a sequence diagram, this has to be argued as part of the architecture description.
Generally dynamic views are expected in the feature view and the component view based on the following considerations:
Do not use dynamic views, if the fulfillment of the requirements by the architecture is already understandable with the static view.
Simple caller/callee relation is not expected to be modelled (this would mean that the examples would be too simple for modelling).
There should be more than two components involved.
In case of safety-related calls/communication, the error cases shall also be displayed (see the “alt” boxes in the examples).
If there is only a small difference between the feature and the component view, one can be omitted, preferably the feature view.
If the described feature or components support multiple use cases (e.g., in different life-cycle phases), these should also be described in multiple dynamic views.