.. # ******************************************************************************* # Copyright (c) 2025 Contributors to the Eclipse Foundation # # See the NOTICE file(s) distributed with this work for additional # information regarding copyright ownership. # # This program and the accompanying materials are made available under the # terms of the Apache License Version 2.0 which is available at # https://www.apache.org/licenses/LICENSE-2.0 # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* .. _arch_design_guideline: Architecture Guideline ###################### .. gd_guidl:: Architectural Design :id: gd_guidl__arch_design :status: valid :complies: std_req__isopas8926__44411, std_req__isopas8926__44412, std_req__iso26262__software_745 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 :need:`[[title]] `. General Hints ============= Attributes ---------- For all architectural need elements following mandatory attributes are defined: .. needtable:: Overview of mandatory attributes :filter: "mandatory" in tags and "attribute" in tags and "architecture_design" in tags and type == "gd_req" and is_external == False :style: table :columns: title; id :colwidths: 30,70 Checks ------ For architectural elements following checks are defined: .. needtable:: Overview of checks on architectural elements :filter: "check" in tags and "attribute" in tags and "architecture_design" in tags and type == "gd_req" and is_external == False :style: table :columns: title; id :colwidths: 30,70 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 :ref:`architecture_workflow_fig` Those steps are: .. list-table:: Definition of the static architectural elements :header-rows: 1 :widths: 10,60,30 * - Step - Description - Responsible * - 1. - :ref:`Create feature architecture (Concept) ` - :need:`[[title]] ` * - 2. - :ref:`Model feature architecture ` - :need:`[[title]] ` * - 3. - :ref:`Allocate feature requirements to architectural elements ` - :need:`[[title]] ` * - 4. - :ref:`Review architectural design ` - :need:`[[title]] ` * - 5. - Merge architectural design into score repository - :need:`[[title]] ` * - 6. - | :ref:`Create component architecture (Concept) ` | :ref:`Allocate component requirements to architectural elements ` - :need:`[[title]] ` * - 7. - :ref:`Model component architecture ` - :need:`[[title]] ` * - 8. - :ref:`Review component architecture ` - :need:`[[title]] ` * - 9. - Merge component architectural design into module - :need:`[[title]] ` .. _create_feature_architecture: 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: :need:`Feature Architecture Template `. 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 :need:`Project SW development Plan `. .. _model_feature_architecture: Model feature architecture -------------------------- Based on the concept description a model of the feature architecture should be designed. It shall consist of the logical interfaces which the user of the feature can access including also the modules which provide the interfaces. Therefore following elements shall be used: .. list-table:: Architectural Elements of the Feature Architecture :header-rows: 1 :widths: 10,30,30 * - Element - Sphinx directive - VS Code Template * - Feature Architecture - feat_arc_sta, feat_arc_dyn - feat_arc_sta_t, feat_arc_dyn_t * - Logical Interface - logic_arc_int - logic_arc_int_t * - Logical Interface Operation - logic_arc_int_op - logic_arc_int_op_t The relations of the static elements are described in :ref:`metamodel_architectural_design`. .. note:: For the modeling of the architecture a sphinx extension is available: :ref:`arch_gen_sphinx` An example for modeling the architecture can be found :ref:`here `. .. _allocate_feature_requirements: 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 Requirement may either be allocated to static or dynamic architecture. Interface requirements shall only be allocated to the interface architecture. If needed also additional feature requirements, which may arise due to architectural decisions, should be created and allocated to the feature architecture itself. Those links shall be established from architectural elements to feature requirements via the attribute *fulfils*. .. _review_architectural_design: Review architectural design --------------------------- As soon as the design is in a mature state it can be reviewed according to :need:`doc_concept__wp_inspections` and merged into the main branch of the score repository. For the review process a checklist template is available: :need:`[[title]] ` Following roles should be included in the review: * :need:`[[title]] ` * :need:`[[title]] ` * :need:`[[title]] ` * :need:`[[title]] ` .. _create_component_architecture: 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 :need:`template ` is provided. For this step the following guidance is available: :need:`Feature Architecture Template `. 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 :need:`Project SW development Plan `. .. _allocate_component_requirements: Allocate component requirements to architectural elements --------------------------------------------------------- In this step the component requirements shall be derived (see :need:`[[title]] `) and allocated to the architectural elements via the attribute *fulfils*. .. _model_component_architecture: 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. .. list-table:: Architectural Elements of the Component Architecture :header-rows: 1 :widths: 10,30,30 * - Element - Sphinx directive - VS Code Template * - Component Architecture - comp_arc_sta, comp_arc_dyn - comp_arc_sta_t, comp_arc_dyn_t * - (Real) Interface - real_arc_int - real_arc_int_t * - (Real) Interface Operation - real_arc_int_op - real_arc_int_op_t The relations of the static elements are described in :ref:`metamodel_architectural_design`. .. _review_component_architecture: Review component architecture ----------------------------- As soon as the design is in a mature state it can be :ref:`reviewed ` and merged into the main branch of the module repository. Following roles should be included in the review: * :need:`[[title]] ` * :need:`[[title]] ` * :need:`[[title]] ` For the review process a checklist template is available: :need:`[[title]] ` .. _uml_diagram_selection: UML diagram selection ===================== Static architecture ------------------- As can be seen from the examples presented in :need:`feat_arc_sta__example_feature__feature_1` and :need:`comp_arc_sta__example_feature__archdes_component_2` for the static architecture a UML component diagram is expected (and supported by the tooling). Dynamic architecture -------------------- The :need:`doc_concept__arch_process` shows the usage of UML sequence diagrams to describe dynamic behaviour. This is also the expected default diagram. Alternatively also 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). - It should be more than two components involved. - In case of safety related calls/communication also the error cases shall be displayed (see the "alt" boxes in the examples). - If there would be only small difference between the feature and the component view, one can be omitted, preferrably the feature view. - If the described feature or components support multiple use cases (e.g. in different life cycle phases). These should be described also in multiple dynamic views.