Part I: Documentation Roadmap

This document contains architectural drivers and the software architecture specification (packaged as Views) of the DiMeo Waste Management System platform. It is written and maintained by the DiMeo Waste Management System Software Architecture Team. The following sections of this chapter describe how this document is organized, maintained, its purpose, scope and elements.

Purpose and Scope of this document

This document specifies the software architecture of the DiMeo Waste Management System platform. All information regarding the software architecture may be found in this document.

Elements and relationships

The contents of this document aims to embody information about how the DiMeo Waste Management System platform elements relate to each other. This means that information about elements that does not pertain to their interaction will be omitted. Thus, this software architecture document suppresses details of elements that do not affect how they use, are used by, relate to, or interact with other elements.

Multiple structures

The DiMeo Waste Management System platform comprise a set of structures. Although these structures are pictured differently and have considerably different properties, all are inherently related; together they describe the architecture of the entire system:

• Module structures

The DiMeo Waste Management System platform as a software system can be partitioned into units of implementation (Modules); Module structures represent a code-based way of considering the system. They are assigned areas of functional responsibility. There is less emphasis on how DiMeo Waste Management System manifests itself at runtime. For example, the DiMeo Waste Management System high-level modules are its Administrative Backoffice portal, Client mobile application, the API, and so on. However, a module structure does not describe how and when DiMeo Waste Management System interact at runtime.

• Component-and-connector structures

C&C are the runtime structures of the DiMeo Waste Management System platform. They represent the interaction between elements of the system as it executes. For example, an DiMeo Waste Management System platform’s component-and-connector structure is the communication flow between microservices and the pub/sub, databases and other runtime components, how it is achieved, with the help of what other software it works, and how it answers to architecturally significant requirements. All component-and-connectors structures are orthogonal to the module structures, as in they deal with the dynamic aspects of the running DiMeo Waste Management System system.

• Allocation structures

Allocation structures embody how the system relates to its environment. That includes the deployment of the DiMeo Waste Management System platform elements, the distribution of work among external developers and their management.

The architecture of DiMeo Waste Management System consists of these structures. These structures will be described further in this document as Views.

Note

None of these structures alone is the entire architecture, although they all convey architectural information. The architecture consists of these structures as well as many others. This example shows that since architecture can comprise more than one kind of structure, there is more than one kind of element (e.g., implementation unit and processes), more than one kind of interaction among elements (e.g., subdivision and synchronization), and even more than one context (e.g., development time versus runtime). [3]

How this documentation is organized

This documentation is organized into the following sections:

• Part I: Documentation Roadmap provides information about this document and its intended audience. It provides the roadmap and document overview. Every reader who wishes to find information relevant to the software architecture described in this document should begin by reading Part I: Documentation Roadmap, which describes how the document is organized, which stakeholder viewpoints are represented, how stakeholders are expected to use it, and where information may be found. Part I: Documentation Roadmap also provides information about the views that are used by this documentation to communicate the software architecture.

• Part II: Architecture Background explains why the architecture is what it is. It provides a system overview, establishing the context and goals of the implementation. It describes the background and rationale for the software architecture. It explains the constraints and influences that led to the current architecture, and it describes the major architectural approaches that have been utilized in the architecture.

• Part III: Views and Part IV: Relations Among Views specify the software architecture. Views specify elements of software and the relationships between them. A view corresponds to a viewpoint (see Viewpoint Definitions), and is a representation of one or more structures present in the software (see Multiple structures).

• Part V: References and Part VI: Directory provide reference information for the reader. Part V: References provides look-up information for documents that are cited elsewhere in this documentation. Part VI: Directory is a directory, which is an index of architectural elements and relations telling where each one is defined and used in this documentation. The section also includes a glossary and acronym list.

Stakeholder Representation

This section provides a list of the stakeholder roles considered in the design of the architecture described by this documentation. For each, the section lists the concerns that the stakeholder has that can be addressed by the information in this documentation.

Each stakeholder of a software system is concerned with different characteristics of the system that are affected by its software architecture. For example, the Customer and Internal Operational User are concerned that the system is reliable and available when needed; the Strategic Leadership is concerned about development timelines and budget; The Development Team is interested in in strategies to achieve all of those goals, and so on.

Stakeholder matrix

Stakeholder	Description	Concerns
Strategic Leadership	CEO & Founder
Commercial Growth	Head of sales, Head of marketing
Security & Operations	Head of Security & Operations
Customers	Company business customers
Internal Operational Users	Drivers

Viewpoint Definitions

This document employs a stakeholder-focused, multiple view approach to architecture documentation, as required by ISO/IEC/IEEE 42010:2011, the recommended best practice for documenting the architecture of software-intensive systems [1].

As described in Purpose and Scope of this document, a software architecture comprises more than one software structure, each of which provides an engineering handle on different system qualities. A view is the specification of one or more of these structures, and documenting a software architecture, then, is a matter of documenting the relevant views and then documenting information that applies to more than one view [3].

Note

ISO/IEC/IEEE 42010:2011 provides guidance for choosing the best set of views to document, by bringing stakeholder interests to bear. It prescribes defining a set of viewpoints to satisfy the stakeholder community. A viewpoint identifies the set of concerns to be addressed, and identifies the modeling techniques, evaluation techniques, consistency checking techniques, etc., used by any conforming view. A view, then, is a viewpoint applied to a system. It is a representation of a set of software elements, their properties, and the relationships among them that conform to a defining viewpoint. Together, the chosen set of views show the entire architecture and all of its relevant properties. A Software Architecture Document contains the viewpoints, relevant views, and information that applies to more than one view to give a holistic description of the system.

The remainder of Viewpoint Definitions defines the viewpoints used in this document. The following table summarizes the stakeholders in this project and the viewpoints that have been included to address their concerns.

Stakeholders and Relevant Viewpoints

Stakeholder	Relevant Viewpoints	Why Relevant
Strategic Leadership
Commercial Growth
Security & Operations
Customers
Internal Operational Users

Module Decomposition Viewpoint Definition

Abstract

Views conforming to the module decomposition viewpoint partition the system into a unique non-overlapping set of hierarchically decomposable implementation units (modules).

Stakeholders and Their Concerns Addressed

Elements, Relations, Properties, and Constraints

Elements of the module decomposition viewpoint are modules, which are units of implementation that provide defined functionality. Modules are hierarchically decomposable; hence, the relation is “is-part-of.” Properties of elements include their names, the functionality assigned to them (including a statement of the quality attributes associated with that functionality), and their software-to-software interfaces. The module properties may include requirements allocation, supporting requirements traceability.

Language(s) to Model/Represent Conforming Views

Views conforming to the module decomposition viewpoint may be represented by UML, using subsystems or classes to represent elements and “is part of” or nesting to represent the decomposition relation.

Applicable Evaluation/Analysis Techniques and Consistency/Completeness Criteria

Completeness/consistency criteria include:

1. no element has more than one parent;

2. major functionality is provided for by exactly one element;

3. the union of all elements’ functionality covers the requirements for the system;

4. every piece of source code can be mapped to an element in the module decomposition view (if not, the view is not complete);

5. the selection of module aligns with current and proposed procurement decisions.

Additional consistency/completeness criteria apply to the specifications of the elements’ interfaces. Applicable evaluation/analysis techniques include:

1. scenario-based evaluation techniques such as ATAM [2] to assure that projected changes are supported economically by the decomposition;

2. disciplined and detailed mapping to requirements to assure coverage and non-overlapping functionality;

3. cost-based techniques that determine the number and composition of modules for efficient procurement.

Viewpoint Source

Chapter 2, Section 2.1 of [3] describes the module decomposition style, which corresponds to this viewpoint.

Component-and-Connector (C&C) Viewpoint Definition

Abstract

Views conforming to the component-and-connector viewpoint represent the system as a set of interacting components and connectors. Components are the elements that perform computation, store data, and interface with the system’s environment. Connectors are the elements that enable communication, coordination, or cooperation among components.

Stakeholders and Their Concerns Addressed

Elements, Relations, Properties, and Constraints

Elements of the component-and-connector viewpoint are components and connectors. Components are the elements that perform computation, store data, and interface with the system’s environment. Connectors are the elements that enable communication, coordination, or cooperation among components. The relations among components and connectors are interactions, which are the ways in which components and connectors collaborate to perform the system’s functions. Properties of elements include their names, the functionality assigned to them (including a statement of the quality attributes associated with that functionality), and their interfaces. The component-and-connector properties may include requirements allocation, supporting requirements traceability.

Language(s) to Model/Represent Conforming Views

Views conforming to the component-and-connector viewpoint may be represented by UML, using components and connectors to represent elements and interactions to represent the relations among them. The UML component diagram is a common representation of this viewpoint. However, custom languages or notations may be used to represent the viewpoint.

Applicable Evaluation/Analysis Techniques and Consistency/Completeness Criteria

Completeness/consistency criteria include:

1. All components required to fulfill system functionality are represented and appropriately connected.

2. Each connector specifies the required interaction properties (e.g., protocol and latency).

3. All specified interactions are traceable to system requirements and quality attributes.

4. The runtime view is consistent with the static structural view (e.g., module decomposition).

Viewpoint Source

Chapter 4 of [3] describes a set of component-and-connector styles, which correspond to this viewpoint.

Allocation Viewpoint Definition

Abstract

Views conforming to the allocation viewpoint map the software system to elements of its development, execution, or physical environments. These views highlight how software artifacts relate to their environment and address concerns about resource usage, deployment, and organizational alignment.

Stakeholders and Their Concerns Addressed

Elements, Relations, Properties, and Constraints

Elements of the allocation viewpoint vary depending on the type of allocation and include:

• Software artifacts, such as components, modules, or data stores.

• Environment elements, such as (hardware or virtualized) nodes, networks, development teams, or geographic locations.

The primary relations are allocated-to or hosted-on, representing the mapping between software and environment elements.

Properties of elements include:

• Software artifacts: name, resource requirements (e.g., memory, CPU, bandwidth), and runtime behavior characteristics.

• Environment elements: capacity (e.g., CPU credits, storage), availability, and constraints (e.g., physical location or redundancy requirements).

Constraints may include:

• Resource constraints (e.g., no single node can exceed 80% CPU usage).

• Security requirements (e.g., personal identifiable information cannot remain stored in a specific runtime component).

• Redundancy and failover requirements (e.g., critical components must have backup strategies).

Language(s) to Model/Represent Conforming Views

Views conforming to the allocation viewpoint can be represented using:

• UML deployment diagrams, showing the mapping of software artifacts to hardware elements.

• Text-based tables or spreadsheets, listing software elements and their allocations.

• Custom architecture modeling notations, such as AWS Reference Architecture Diagrams [4].

Applicable Evaluation/Analysis Techniques and Consistency/Completeness Criteria

Completeness/consistency criteria include:

• All software artifacts are mapped to an environment element.

• No environment element is over-allocated based on its resource capacity.

• Deployment maps are consistent with system constraints, such as latency or geographic regulations.

• Allocation satisfies failover and redundancy requirements.

Applicable evaluation/analysis techniques include:

• Resource analysis: to verify adequate allocation of processing, memory, and storage resources.

• Performance testing: to confirm that deployment meets required performance thresholds.

• Fault-tolerance testing: to evaluate resilience under node or resource failure scenarios.

• Scalability analysis: to ensure the deployment supports expected growth in resource demands.

Viewpoint Source

Chapter 5 of [3] describes some allocation styles, which corresponds to this viewpoint.

How a View is Documented

Each view is documented as follows, where the letter i stands for the number of the view: 1, 2, etc.:

1. Name of the View

2. View Description - This section describes the purpose and contents of the view. It should refer to (and match) the viewpoint description in Viewpoint Definitions to which this view conforms.

3. View packet overview - This section shows the set of view packets in this view, and provides rationale that explains why the chosen set is complete and non-duplicative. The set of view packets may be listed textually, or shown graphically in terms of how they partition the entire architecture being shown in the view.

4. Architecture background - Whereas the architecture background of Part II: Architecture Background pertains to those constraints and decisions whose scope is the entire architecture, this section provides any architecture background (including significant driving requirements, design approaches, patterns, analysis results, and requirements coverage) that applies to this view.

5. Variability mechanisms - This section describes any architectural variability mechanisms (e.g., adaptation data, compile-time parameters, variable replication, and so forth) described by this view, including a description of how and when those mechanisms may be exercised and any constraints on their use.

6. View packets - This section presents all of the view packets given for this view. Each view packet is described using the following outline, where the letter i stands for the number of the view packet being described: 1, 2, etc.

   • Name of view packet #i

   • i.1: Primary presentation - This section presents the elements and the relations among them that populate this view packet, using an appropriate language, languages, notation, or tool-based representation.

   • i.2: Element catalog - Whereas the primary presentation shows the important elements and relations of the view packet, this section provides additional information needed to complete the architectural picture. It consists of the following subsections:

     • i.2.1: Elements - This section describes each element shown in the primary presentation, details its responsibilities of each element, and specifies values of the elements’ relevant properties, which are defined in the viewpoint to which this view conforms.

     • i.2.2: Relations - This section describes any additional relations among elements shown in the primary presentation, or specializations or restrictions on the relations shown in the primary presentation.

     • i.2.3: Interfaces - This section specifies the software interfaces to any elements shown in the primary presentation that must be visible to other elements.

     • i.2.4: Behavior - This section specifies any significant behavior of elements or groups of interacting elements shown in the primary presentation.

     • i.2.5: Constraints - This section lists any constraints on elements or relations not otherwise described.

   • i.3: Context diagram - This section provides a context diagram showing the context of the part of the system represented by this view packet. It also designates the view packet’s scope with a distinguished symbol, and shows interactions with external entities in the vocabulary of the view.

   • i.4: Variability mechanisms - This section describes any variabilities that are available in the portion of the system shown in the view packet, along with how and when those mechanisms may be exercised.

   • i.5: Architecture background - This section provides rationale for any significant design decisions whose scope is limited to this view packet.

   • i.6: Relation to other view packets - This section provides references for related view packets, including the parent, children, and siblings of this view packet. Related view packets may be in the same view or in different views.

Process for Updating this Document

Updating this document should happen to reflect the state of the software architecture. The structural integrity of the document must remain intact. This means that the document should be updated in a way that the structure of the document is maintained. This includes the following steps:

Stakeholder changes

Upon changes in stakeholders, the sections Stakeholder Representation and Viewpoint Definitions need to be updated. The stakeholders and their concerns should be reviewed and updated accordingly. The viewpoints should be reviewed and updated to reflect the concerns of the stakeholders.

Important

It is rare, but not unheard of, for stakeholders and/or their definitions to change. Make sure to review if requested changes are necessary.

Architectural drivers changes

Upon changes in architectural drivers, the section Part II: Architecture Background needs to be updated. The architectural drivers should be reviewed and updated accordingly.

View changes

As the DiMeo Waste Management System products evolve, the software architecture will evolve as well. This means that the views of the software architecture will change. The views should be reviewed and updated to reflect the current state of the software architecture. Use Pull Requests to suggest software architecture changes, both for suggested, planned and current states.