ECS Architecture Documentation Roadmap

1.1 Description of the ECS Software Architecture Documentation Package

This section describes the structure and contents of the entire ECS software architecture documentation package. The ECS architecture documentation package is arranged in two volumes. Volume I contains the information that applies to more than one view, including this roadmap of the entire package. The architectural views are collected in Volume II.

Volume I, ECS Software Architecture Documentation Beyond Views, contains the following chapters:

• Chapter 1, ECS Architecture Documentation Roadmap, lists and outlines the contents of the overall documentation package and explains how stakeholder concerns can be addressed by the individual parts. This is the first document that a new stakeholder should read.
• Chapter 2, ECS System Overview, gives a broad overview of the purpose and functionality of ECS. Architectural detail is purposely omitted from this overview; instead, the emphasis is on the system's background, its external interfaces, major constraints, and what functions the system performs. The purpose is to help someone new to the project understand what the architecture is trying to achieve.
• Chapter 3, View Template, explains the standard organization for the views given in Volume II. The purpose is to help a reader understand the information given in the views of Volume II.
• Chapter 4, Mapping Between Views, draws comparisons between separate views of the ECS architecture that are given in Volume II. The mapping points out places where the views overlap or have elements in common and resolves areas of apparent conflict between the views.
• Chapter 5, Directory, is a look-up index of all the elements, relations, and properties in the ECS architecture, listing where these items are defined and where they are used. The purpose of the directory is to help a stakeholder quickly locate the definition of an architectural entity.
• Chapter 6, Architecture Glossary and Acronym List, defines special terms and acronyms used elsewhere in the architecture documentation package. This list is intended to supplement the overall project glossary and acronym list.
• Chapter 7, Rationale, Background, and Design Constraints, explains the design rationale behind the ECS architecture, including the most relevant background information and imposed design constraints. Maintainers seeking to make changes, future architects, and lead designers can learn the motivation behind the major design decisions of ECS.

Volume II, ECS Software Architecture Views, contains the following chapters:[1]

[1] Each entry tells what the element and relation types are that are found in the view and then what the view can be used for. Both kinds of information can be extracted from the corresponding style catalog for the view, whether that catalog is in this book or another source. For instance, the style descriptions in this book include What It's For and What It's Not For sections.

• Chapter 1, Module Decomposition View: The module decomposition view shows how the system is decomposed into implementation units and, simultaneously, how the functionality of the system is allocated to those units. The elements of this view are modules. The relation is is-part-of.

  The decomposition view presents the functionality of a system in intellectually manageable pieces that are recursively refined to convey more and more details. Therefore, this style supports the learning process about a system. This view is a learning and navigation tool for newcomers in the project or other people who do not necessarily have the whole functional structure of the system memorized. The grouping of functionality shown in this view also builds a useful basis for defining configuration items within a configuration management framework.

  The decomposition view is the basis for creating work assignments, mapping parts of a software system onto the organizational unitsteamsthat will be given the responsibility for implementing and testing them. The module decomposition view also provides some support for analyzing effects of changes at the software implementation level. But because this view does not show all the dependencies among modules, you should not expect to do a complete impact analysis. Here, views that elaborate the dependency relationships more thoroughly, such as the module uses style described later, are required.

• Chapter 2, Module Uses View: The uses view shows how modules are related to one another by the uses relation, a kind of depends-on relation. A module uses another module if the correctness of the first depends on the correctness of the second. The view is used to help integraters and testers field incrementally larger subsets of the system.
• Chapter 3, Module Generalization View: The generalization view shows how classes, a kind of module, are related to one another by inheritance, a kind of generalization/specialization relation.

  This view is used to show extension and evolution of architectures and individual elements. This view is the predominant means for expressing the inheritance-based object-oriented design of ECS. It shows where component and design reuse, or reuse with variation, occurs in the system. Like the decomposition view, the generalization view is also useful for analyzing the scope of a change.

• Chapter 4, Module Layered View: The layered view shows how the ECS software is structured as a set of seven abstract virtual machines. Lower layers provide abstract hardware, network, and data transport facilities. Intermediate layers provide common facilities and object services. The highest layers encapsulate the application-dependent aspects of the system. Elements of this view are layers, a kind of module. Layers are related by the allowed-to-use relation, where use has the meaning given in the uses view.

  Layers are used to provide portability and modifiability. Specifically, the implementation of any layer can be replaced without affecting other layers.

• Chapter 5, Component-and-Connector Pipe-and-Filter View: The pipe-and-filter view shows how data entering ECS flows through a series of order-preserving transformations before being assigned to the appropriate data warehousing facilities. The pipe-and-filter view of ECS is a conceptual view, meaning that in truth, the system is not structured as a series of pipes and filters in the formal sense. In fact, the shared-data view is a higher-fidelity picture of the sysem as it is built. However, the pipe-and-filter view conveys a valuable conceptual picture to project newcomers and users because it shows the transformations applied to the ingested data.

  Elements are pipes and filters, both a kind of component. The relations shown in this view are the attachments between pipes and filters.

• Chapter 6, Component-and-Connector Shared-Data View: The shared-data view shows how the system is structured as a number of data accessors that, at runtime, read and write data in the various ECS shared repositories. Elements are repositories, accessors, and the connectors between the two.

  The shared-data view is used to help tune the system for performance to make sure that it can handle the volume of ingested data, as well as service data processing and production requests in a timely fashion.

• Chapter 7, Component-and-Connector Communicating-Processes View: The communicating-processes view represents the system as a set of concurrently executing units together with their interactions. A concurrent unit is an abstraction of more concrete software platform elements, such as tasks, processes, and threads. Any pair of concurrent units depicted in a process style has the potential to execute concurrently, either logically on a single processor or physically on multiple processors or distributed processors. Connectors enable data exchange between concurrent units and control of concurrent units, such as start, stop, synchronization, and so on.

  The communicating-processes view is used to perform concurrency-related analyses, including performance analysis and deadlock detection and prevention. It is also used as the basis for allocation of the software to hardware processors in the deployment view.

• Chapter 8, Allocation Deployment View: In the deployment view, processes and other software elements are allocated to execution platforms, physical units that store, transmit, or compute data. Physical units include processing nodes (CPUs), communication channels, and data stores.

  The relation depicted in the deployment view is a special form of allocated to that shows on which physical units the software elements reside. The allocation relation in ECS is static; that is, it does not change at runtime.

  The view is used as the basis for performance analysis by, among other things, analyzing the volume and frequency of communication among software units on different processing elements along the communication channels among those elements. The view is also used to support memory capacity analysis; reliability analysis, by examining the effects of a failed processor or communication channel; and security analysis, by examining the way each platform is connected and potentially vulnerable to external threats.

• Chapter 9, Allocation Implementation View: The implementation view shows how code units, or modules, are mapped, or allocated, to the ECS development and implementation environment. It is used to help plan the development environment and to manage the day-to-day artifact production and storage process, including configuration management.
• Chapter 10, Allocation Work Assignment View: The work assignment view shows how code units, or modules, are allocated to organizational work unitsin this case, either internal government development teams or external contractors. It is used to help manage the teams and provides a basis for planning and measuring progress.

1.2 How Stakeholders Can Use the Documentation

This section lists the stakeholder roles of primary importance to ECS and how they might use the documentation package to address their concerns.

• Someone new to the project: Read the documentation roadmap for an understanding of the documentation package and the view template to understand how views are documented. Read the system overview and system-level design rationale. Examine the top-level view packets of the module decomposition view, the pipe-and-filter view, the deployment view, and the work assignment view.
• Project manager: To help with project planning, concentrate on the module decomposition view, which will help define work assignments and identify COTS products that will have to be qualified, procured, and integrated. Read the deployment view to understand the hardware environment that will have to be acquired and that will help identify testing environments that need to be set up. Read the work assignment view to begin to manage and coordinate the teams.
• Performance engineer: Read the communicating-processes view to understand the units of potential concurrency. Read the deployment view to understand how the software is to be allocated to hardware. Read the shared-data view to build performance models for ingesting data and producing data products on demand. Read the behavioral specifications in all the C&C views.
• Security analyst: Read the deployment view to understand the physical environment in which the system operates.
• Maintainer: Read the system-level rationale in Volume I. Read the decomposition view to understand the units of implementation that exist and the area of responsibility of each. Read the generalization view to see how the units relate to one another in terms of generalization and specialization. Especially read the rationale in each view and in each interface specification. Read the top-level view packet of the deployment view to understand where each software unit is allocated. Read the implementation view to understand how the code units are allocated to the development environment.
• Customer/Acquirer: Read the system overview. Read the top-level view packets of the decomposition, deployment, and pipe-and-filter views to gain a broad understanding of how the system is structured to carry out its mission and to gain an appreciation for the work that must be done to build it.
• Users: Users will not generally be voracious consumers of architecture documentation, but they can read the behavioral specifications in the C&C views to gain an understanding of how various parts of the system behave. Reading the pipe-and-filter view will give users an intuition about how the system functions.
• Developer: Read the decomposition view to understand the basic units of software in the system, the uses view to see how the current subset being developed is structured, the implementation view to see where the software resides in the development environment, the layered view to see which software developers are allowed to use, and the work assignment view to understand the other organizational units with which developers must coordinate. Read the interface specifications of other units to find out how to use them. Then, using the mapping between views, read the relevant parts of the other views that reveal how their units are deployed onto hardware or manifested as runtime components.