Purpose and Scope
The Software Architecture Document specifies the software architecture for the current release of the CONNECT product. This document is meant to be all-inclusive. That is, all information regarding the software architecture may be found in this document with only minimal information being incorporated by reference to other documents. This organization is meant to simplify the reader's access to the necessary information as well as the writer's task in maintaining this information without having to reference a large number of separate documents.
At the same time, this document is meant to be minimalistic. It is not exhaustive in presenting all of the Unified Modeling Language (UML) diagrams that might be included in software architecture documentation or associated software design documentation. Instead, it includes only the most important views and diagrams that will enable a developer to sufficiently understand the software architecture in order to work with it.
This document is also a living document. As CONNECT evolves through future releases and makes its way into the open source community, it will undergo changes that may include changes to its architecture. This document will evolve with CONNECT to reflect those changes. The move to include CONNECT documentation, including this document, as wiki pages on the open source community portal reflects this approach.
Finally, this document is targeted toward CONNECT stakeholders, managers, architects, and developers to aid in developing a high-level familiarity with the CONNECT architecture as well as a more detailed understanding to support implementation and development of the appropriate adapter to existing health systems. To this end, it references some additional materials that make up the software development kit.
Software architecture. The software architecture for a system is its structure, comprising software elements, the externally visible properties of those elements, and the relationship among them [Bass 2003; see Referenced Materials section]. The concept of "externally visible" is meant to identify the assumptions developers, and the software elements they create, can make of an element that is part of the architecture. Those assumptions might include the services the element provides, performance characteristics, fault handling, shared resource usage, etc.
This definition provides the basic litmus test for what information is included in this document and what information is relegated to downstream documentation. While this document is intended to incorporate only architectural information, in its capacity as a complete view of CONNECT it will also incorporate high-level software design information.
Elements and relationships. The software architecture first and foremost embodies information about how software elements relate to each other. This means that this document specifically omits details about elements that do not pertain to their interaction. Elements interact with each other by means of interfaces that are partitioned into public and private parts. Software architecture is concerned with the public side of this division, and the public interfaces will be documented accordingly. On the other hand, private details of elements (details having to do solely with internal implementation) are not architectural and will not be documented here.
Within the later sections of this document, these elements and relationships are presented primarily using component diagrams and sequence diagrams. In addition, the Web Services Description Language (WSDL) descriptions and XML schemas referenced in this document make up the full description of the interfaces among elements.
Multiple views. Systems can, and often do, comprise a complex structure best illuminated by considering differing perspectives that illustrate different properties. All perspectives are inherently related and, taken together, describe the architecture as a whole. This document follows the principle that documenting software architecture is a matter of documenting the relevant views and then documenting information that applies to more than one view.
Behavior. Although software architecture tends to focus on structural information, behavior of each element is part of the software architecture insofar as that behavior can be observed or discerned from the point of view of another element. This behavior is what allows elements to interact with each other, which is clearly part of the software architecture and will be documented here as such. Behavior is documented through sequence diagrams and in the element catalog of the documented views.
How this Document Is Organized
This section provides a narrative description of the major sections of this document and the overall contents of each. Readers seeking specific information can use this section to help them locate it more quickly.
The organization of the Software Architecture Documentation is modeled after that described by the Software Engineering Institute (SEI) in Documenting Software Architectures: Views and Beyond [Clements 2003; see Referenced Materials section]. The so-called V&B approach comprises descriptions of a set of relevant views of architecture along with information that applies to more than one view or to the set of views as a whole. It is consistent with the IEEE Recommended Practice for Architectural Description of Software-Intensive Systems [IEEE 2000; Referenced Materials], keeping in mind the desire to be all-inclusive as well as minimalistic.
This document is organized into the following sections:
- Executive Summary: Contains a high-level overview of the system and its architecture designed primarily for the executive or less technical reader, providing a high-level understanding of the goals of the project and the most important architectural features
- Document Roadmap (this section): Provides a roadmap and overview for this document. Every reader who wishes to find information relevant to the software architecture should begin by reading the Roadmap, which describes how the document is organized, how stakeholders are expected to use it, and where information may be found. The Roadmap also provides information about the views that are used by this document to communicate the software architecture
- Architecture Background: Explains why the architecture is what it is. It provides a system overview, establishing the context and goals for the architecture development. It describes the background and rationale for the software architecture, explains the constraints and influences that led to the current architecture, and describes the major architectural approaches that have been utilized in the architecture. It also includes information about evaluation or validation performed on the architecture to provide assurance it meets its goals.
- Architecture Views: Specifies the software architecture. Views specific elements of software and the relationships between them. A view is a representation of one or more structures present in the software. This document comprises a multi-view approach of the architecture. However, unlike the prescribed set of views advocated by models such as the "4+1 View Model" [Kruchten 1995; see Referenced Materials section], it follows a more modern trend of selecting the most useful views to describe the system at hand. As with much of the architectural documentation of successful open source projects, these views concentrate on components-and-connectors diagrams and sequence diagrams.
Relationship to Other Documents
This section describes the relationship between this document and other architecture documents, both system and software. It also describes the relationship to other documents that can be found on the CONNECT website.
There are no other architecture documents that describe the CONNECT architecture. However, there are other documents that one would generally classify as part of software design documentation that should be considered together with the architecture in order to gain a full understanding of how to implement CONNECT for an organization. As of this release of this document, these documents include:
- The Enterprise Architect UML Model for CONNECT that functions as the ultimate software design document and captures the full architecture of CONNECT [FHA 2013-1, FHA 2012-1; Referenced Materials]
- Referenced Materials and Acronyms and Terms: Provides reference information for the reader. Referenced Materials provides look-up information for documents that are cited elsewhere in this document. Acronyms and Terms includes a glossary of terms and a list of acronyms used in this document.
There may be additional documents that describe the architecture for or otherwise document the open-source reference implementations of the enterprise service components that have been contributed and integrated with CONNECT. They are not included or referenced in this document. Many of these can be found in the CONNECT Wiki under design documents.