Documenting the Software Architecture

By: Juan Carlos (John Charles) Olamendy Turruellas

In this article, I’m going to talk about specifying the architecture of software intensive systems based on multiple views in order to address different concerns of various stakeholders: end-user, developers, systems engineers, project manager, etc.

Software architecture deals with high-level structure of the software system, it means the key components, its relationship and how they expose their properties and behavior to the world. The structure is established in order to satisfy the major functionality, the non-functional requirements (reliability, scalability, portability, availability, etc) as well as business and project constraints.

In order to specify the software architecture, we need a document in the application lifecycle to capture the required architectural information using multiple and concurrent views of the system. This document, according to Rational Unified Process (RUP),is called the Software Architecture Document (SAD), and it’s the mean for the communication between the architecture team and project team. The SAD provides a comprehensive high-level view of the system using a number of different architectural views to depict different aspects of the system.

According to RUP, the SAD must be defined in the Inception phase before the first development iteration and maintained throughout the project. The goal is to establish a sound and stable architectural foundation. The software architect is responsible for producing this document in order to maintain the architectural integrity of the system throughout the development process as well as approving all changes to architecturally significant elements.

The most used architectural view model for SAD is 4+1. This view model was developed by Phillippe Krutchen and defines the following views:

• Use case/ Scenario View. The system architecture is defined and validated by the main business scenarios. This is the first view to specify. You should take the most significant business use cases representing the interaction between objects and processes. You can use the Use Case diagram.
• Logical View. Defines the design model of the system (object-oriented designed is mostly used). You can use different UML diagrams such as Layer, Class, Sequence and Activity diagrams.
• Development View. Defines the system from the developer point of view. It focuses on the software module organization such as subsystems, libraries, frameworks, etc. You can use different UML diagrams such as Component diagram to describe system components and Package diagram to represent the development view.
• Process View. Captures the concurrency and synchronization aspects of the design by describing the business processes and the components supporting these processes. It addresses concurrency, distribution and integrators. You can use the Activity diagram.
• Deployment View. Describes the topology of the software components onto the physical infrastructure and the connectors between these components. You can use the Deployment diagram.
• Data View (optional depending whether the system is data intensive or not)

The representation of the views and their relationship can be shown in the following figure:

Figure 1

In order to create the SAD, architects must follow these steps:

1. Identify and prioritize significant business use cases, and understand the non-functional requirements, constraints and business drivers
2. Define the candidate architecture. High-level architecture
3. Review the architecture
4. Specify the system architecture on the SAD

The following table summarizes for each view, its audience, its area and RUP model.

View	Audience	Area	RUP Model
Use Case	Everyone	Functional Requirements	Use Case model
Logical	Designers	Use Case realization	Analysis Model Design Model
Development	Programmers	Software Components	Implementation Model
Process	Integrators	Performance Scalability Concurrency	Deployment Model Design Model
Deployment	Deployment Managers	Physical Nodes	Deployment Model
Data	Data Specialists Data Administrators	Data Persistence	Data Model

Table 1

Now, let´s talk about the outline of SAD document as shown in the Listing 1.

SAD Software Architecture Document for {system_name} Prepared by {company_software_architecture_team} Prepared for {client_company_name} Approved by {stakeholder} Version: xx.xx Date: xxxxx   Page1 ———————————————————————————————————————–   Document Information Document: Software Architecture Document Prepared by:   Responsible:   Creation Date:   Approved by:   Approved Date:     Revision History Date Version Description Author Page2 ———————————————————————————————————————– Table of Contents 1.       Introduction 1.1    Purpose 1.2    Scope 1.3    Definitions, Acronyms and Abbreviations 1.4    References 2.       Architectural Representation 3.       Architectural Goals and Constraints 3.1    Implementation strategy 3.2    Architectural and design patterns 3.3    Usability 3.4    Transaction 3.5    Security 3.6    Integration 3.7    Data Migration 3.8    Availability 3.9    Reliability 3.10Performance 3.11Scalability 3.12Internationalization (I18N) 3.13Modificability 3.14Audit trailing and technical logging 4.       Use Case View 4.1    Use Case Realization 5.       Logical View 5.1    Overview 5.2    Architecturally significant design packages 6.       Process View 6.1    Overview 6.2    Process1 6.3    Process2 7.       Deployment View 7.1    Overview 7.2    Topology (single computer/client-server/distributed N-tier) 7.3    Hardware requirements 7.4    Platform requirements 8.       Implementation View 8.1    Overview 8.2    Layers 9.       Data View (optional) 10.   Size and Performance 11.   Quality Page3 ———————————————————————————————————————–

Listing 1

Now, let’s see how we can specify the SAD in a real world solution. Let’s supposed that our customer is Contoso Corp and he wants to increase its sales by developing an online store (named ContosOnline) in order to sell his products with a global presence. Our architecture team has to provide the vision of the software architecture and the implementation strategy for this online store system.

The first task is to identify the business scenarios, the non-functional requirements, the constraints and business drivers that are significant for the architecture. The prerequisite (input) for this task is the Vision, High-level Use Case, Supplementary Specification documents produced by a system analyst during the Inception phase. They define the scope of the project and allow the software architect to identify the elements that influence in the architecture.

The key business scenarios for ContosOnline system are:

1. Managing information of the products in the online store (add, update and delete products in the catalog)
2. Displaying the product information
3. Buying process for a product
4. Reporting the sales revenue in order to support the decisions

This business scenario can be specified using business use case diagrams as shown in the following figure (see Figure 2):

Figure 2

The list of the key non-functional requirement for the ContosOnline system is:

• Performance
• Security
• Reliability
• Availability
• Scalability
• Usability

The list of key constraints for the ContosOnline system is:

• The application must be deployed in a Web environment
• The application must be developed using Microsoft.NET platform and related technology
• We need to develop a prototype for the solution
• We need to migrate existing data into new data repository
• The system must use the existing Oracle 10g database licenses
• The development of the application must follow the defined standards of the customer
• The functionality exposed by the application must be on WS-* stack of protocols and the programming model must be Windows Communication Foundation
• The application must be integrated with the SCM system

The list of business drivers for the ContosOnline system is:

• The customer has modified some business processes in order to achieve his goals
• Changes in the profiles of the average user
• The customer needs to adapt to the business environment

The second task is to define the candidate architecture. The input for this task is the business scenarios, the non-functional requirements, the constraints and business drivers which were analyzed in the previous activity. Most of the time, the architecture selection is based on architectural and design patterns as well as past experiences with similar systems. You may use proof of concepts or architectural spikes to explore areas of design, validate new approach and choose potential architectures and implementation strategies as well as to create a foundation prototype for the application development. The output of this task is the specification of candidate architecture (the application type, the deployment environment, architectural style, technology choices, quality attributes and crosscutting concerns). You may modify the candidate architecture many times, through iterations and several architectural spikes.

We have chosen an N-tier architecture where the application is web-based and Microsoft.NET related technologies as the development environment (see Figure 3). We’re also going to do an architectural spike to map each layer of the N-tier architecture with Microsoft.NET technologies and to set the foundations for the future development.

Figure 3

The third task is to review the architecture. The purpose of this task is to determine the feasibility of the candidate architecture and verify that it links to functional and non-functional requirements, the constraints and business drivers. This is critical in order to reduce the cost of mistakes as well as to find and fix architectural problems as early as possible. The input is the candidate architecture and the output is the validated candidate architecture.

There are several techniques to evaluate the software architecture such as questioning, checklists, scenario evaluation, simulation and experimenting.

The most used methods for reviewing the system architecture are based on scenario. The focus is on the scenarios that are most important from the business perspective and which have the greatest impact on the architecture. The most common methodologies are:

• Quality Attributes Workshop method (QAW). This is an approach for discovering quality attributes before the software architecture is created. Achieving these quality attributes is highly dependent on well-design software architecture. The QAW elicitation activities are executed in a workshop composed of the architecture team and stakeholders. The output is a list of architectural drivers, quality elements, prioritized and refined scenario before the architecture was laid out. This output can be used to refine requirements, develop prototypes, influence on decisions, etc. QAW is executed in eight steps:
  • QAW presentation and introductions. QAW facilitators describe rationale for the workshop, steps involved with QWE, and expectations from the effort.
  • Business and mission presentation. A stakeholder presents business and mission drivers for the system. Architecture team captures relevant information.
  • Architectural plan presentation. At this point in the SLC of the solution, there might not be a detailed system architecture. Might have high-level descriptions, diagrams, or other elements with technical details. The architecture team presents them to stakeholder. The architecture team continues to capture important aspects for later analysis.
  • Identification of architectural drivers. The architecture team takes a break from the main group and consolidates the notes. The documented important architectural drivers are presented back to stakeholders for consensus.
  • Scenario brainstorming. Once the architectural drivers are agreed upon, architecture team serves as catalyst for scenario generation activities. Each stakeholder defines scenarios that satisfy their concerns. Do at least two round-robin passes. The architecture team ensures there is at least one scenario per architectural driver.
  • Scenario consolidation. The architecture team queries stakeholders for possible scenario consolidations, allowing a better focus on more robust scenarios.
  • Scenario prioritization. Driven by stakeholders, desired outcome is a set of goals prioritized by what is more important to the project at hand.
  • Scenario refinement. Refine the top scenarios (depending on time), clarifying their stimulus, response, source of stimulus, environment, artifact stimulated and response measure.
  • Software Architecture Analysis Method (SAAM). SAAM was originally designed for assessing modifiability, but later was extended for reviewing architecture with respect to quality attributes such as modifiability, portability, extensibility, integratability, and functional coverage.
  •  Architecture Tradeoff Analysis Method (ATAM). ATAM is a refined and improved version of SAAM that helps you review architectural decisions with respect to the quality attributes requirements, and how well they satisfy particular quality goals. The key approach is to understand the architecture used to achieve a particular quality goal and the underlying implications. ATAM assumes that the architecture has already been delivered. The method uses stakeholder perspectives to derive a collection of scenario to analyze the usage, performance, types of failure, possible threads and a set of likely modifications. The architect must understand the architecture risks and evaluate the tradeoffs among quality attributes. The main steps in ATAM are:
    • Present the ATAM. Similar to QAW Step 1.
    • Present the business drivers. Similar to QAW Step 2.
    • Present the architecture. The architect team presents the architecture, focusing on how it meets the business drivers.
    • Identify the architectural approaches. Focusing on the drivers to be addressed, the architecture team identifies the approaches taken during construction of the architecture design.
    • Generate the quality attribute utility tree. Allows for better visualization and organization of the quality attributes related to the project. QAW steps can be very useful here. Attributes are decomposed all the way to their supportive scenarios.
    • Analyze the architectural approaches. Architectural approaches found in Step 4 are compared against scenarios at the leaves of the quality attribute utility tree to better understand if the approaches taken match with stakeholders driven scenarios. Trade-off points and risks are identified.
    • Brainstorm and prioritize scenarios. To make sure that no important details are ignored, another round of scenario finding activities is executed with stakeholders. Findings are prioritized (a vote is taken) and documented.
    • Analyze architectural approaches. New scenarios might exist so Step 6 activities are executed, focusing on the highly prioritized scenarios.
    • Present the results. Information — approaches, scenarios, tradeoffs, risks — is presented to stakeholders. Can make a suitability decision regarding the architecture and needs of the stakeholders.
    •  Active Design Review (ADR). ADR is best suited for incomplete or in-progress architectures. The main difference is that the review is more focused on a set of issues or individual sections of the architecture at a time, rather than performing a general review. It’s well suited for evaluating components or group of components before the entire architecture is established. The approach is that stakeholders are engaged to review the documentation that describes the interfaces provided by a component and ask them to use this documentation to write code of pseudocode in order to perform some useful task. ADRs are contrasted with unstructured reviews in which people are asked to read a document, attend a long meeting, and comment on whatever they wish. In an ADR, there is no meeting; reviewers are debriefed (or walked through their assignments) individually or in small informal groups.
    • Active Reviews of Intermediate Designs (ARID). ARID combines the ADR aspect of reviewing in-progress architecture with a focus on a set of issues, and the ATAM and SAAM approach of scenario-based review focused on quality attributes. ARID was created to evaluate partial designs (for example, subsystems) in the conceptual phase before they are fully documented, so ATAM and SAAM focus on complete architecture while ARID focus on incomplete architectures. The approach is to assemble the stakeholders for the design, having adopt them a set of scenarios that express a set of meaningful ways in which they would like to use the design, and having them write code or pseudocode that uses the design to carry out the scenario. The main steps in ATAM are:
      • Identify the reviewers. Reviewers in ARID are the architecture team — parties that have an investment in the crafting of a robust design
      • Prepare the seed scenarios. Executed by the stakeholders and the designer
      • Prepare the material
      • Present ARID. Similar to Step 1 in QAW and ATAM.
      • Present the design
      • Brainstorm and prioritize scenarios. Just as in ATAM, scenarios are used for proper requirement coverage
      • Apply the scenarios. Beginning with scenarios at the top of the prioritization list, pseudo code is used by reviewer to verify applicability of the scenarios.
      • Summarize. Outcomes of assessment effort are documented and delivered to appropriate stakeholders.
      • Cost Benefit Analysis Method (CBAM). This CBAM focuses on analyzing the costs, benefits, and schedule implications of architectural decisions.
      • Architecture Level Modifiability Analysis (ALMA). ALMA evaluates the modifiability of architecture for business information systems (BIS).
      • Family Architecture Assessment Method (FAAM). FAAM evaluates information system family architectures for interoperability and extensibility.

There are two main groups involved in the architecture evaluation:

• Architecture team. The people who will conduct the evaluation and perform the analysis.
• Stakeholders. People who have interest in the architecture and the system to be built.

QAW fits best within RUP’s Inception phase, as it is then that the ideas shaping the to-be architecture are shaped. QAW can also be used in later phases to refine initial findings. The Requirements discipline would benefit from the extra focus on quality attribute analysis that QAW brings to RUP.

ARID should be executed in RUP’s Elaboration phase as it is at this phase that the software architecture is solidified. ARID would help in various review efforts executed as part of the RUP’s Analysis and Design discipline.

ATAM/SAAM effort can occur anywhere where in the life cycle where an architectural review is needed. A good fit would be within RUP’s Construction phase, as it is at this phase that resources will begin executing on architecture plans.

The bottom line of the architecture review methods is that QAW is executed before the architecture has been defined, ARID during design efforts, while ATAM and SAAM are executed after the architecture has been completed.

In order to evaluate the candidate architecture for ContosOnline system, we’re going to use the ARID and ATAM methods along with the scenarios defined in the Figure 2.

And the fourth and last task is to specify the software architecture to ensure that it will be implemented correctly. You must communicate the architecture to all stakeholders including the development team, system administrators, operators, product owners, and other parties. The input for this task is the evaluated software architecture along with the key business scenarios, non-functional requirements, constraints and business drivers. The output for this task is the Software Architecture Document (SAD).

In order to document the architecture of ContosOnline system, we’re going to use the following SAD (see Listing 2).

SAD Software Architecture Document for ContosOnline Prepared by MyArchitectureTeam Prepared for Contoso Approved by Mr. John Doe Version: 1.0 Date: 05-23-2011   Page1 ———————————————————————————————————————–   Document Information Document: Software Architecture Document Prepared by: Juan Carlos Olamendy Turruellas Responsible: Juan Carlos Olamendy Turruellas Creation Date: 05-23-2011 Approved by:   Approved Date:     Revision History Date Version Description Author 05-23-2011 1.0 Creation of the SAD JCO Page2 ———————————————————————————————————————– Software Architecture Document 1.       Introduction 1.1    Purpose This document provides a comprehensive architectural overview of the ContosOnline system, using a number of different architectural views to depict different aspects of the system.  It is intended to capture and convey the significant architectural decisions which have been made on the system. In order to depict the software as accurately as possible, the structure of this document is based on the “4+1” model view of architecture [KRU41]. 1.2    Scope The scope of this SAD is to depict the software architecture of the Online Store system (ContosOnline) created for the company Contoso. Throughout the document, the software architecture is depicted using different views (following the “4+1” approach) as well as the key business scenario, non-functional requirements, constraints and the implementation strategies. 1.3    Definitions, Acronyms and Abbreviations Term Description SAD Software Architecture Document RUP Rational Unified Process UML Unified Modeling Language 1.4    References [KRU41]: The “4+1” view model of software architecture, Philippe Kruchten, November 1995, http://www3.software.ibm.com/ibmdl/pub/software/rational/web/whitepapers/2003/Pbk4p1.pdf [RSA]:  IBM Rational Software Architect, http://www-306.ibm.com/software/awdtools/architect/swarchitect/index.html [RUP]:The IBM Rational Unified Process, http://www-306.ibm.com/software/awdtools/rup/index.html 2.       Architectural Representation This document details the software architecture using different views defined in the “4+1” model [KRU41]. The views used to document the ContosOnline system are: Use Case view Audience: All the stakeholders of the system, including the end-users Related Artifacts : Use Case diagram Logical view Audience: Architects and designers Related Artifacts: Layer, Class, Sequence and Activity diagrams Process view Audience: Architects and Integrators Related Artifacts: Activity diagram Implementation view Audience: Architects and Programmers Related Artifacts: Component diagram to describe system components and Package diagram to represent the development view Deployment view Audience: Architects and Deployment managers Related Artifacts: Deployment diagram Data view (optional) Audience: Architects, Data specialists and Database administrators Related Artifacts: Entity-Relationship diagram 3.       Architectural Goals and Constraints This section describes the software requirements and objectives that have some significant impact on the architecture. 3.1    Implementation strategy The ContosOnline system will be developed following the N-tier architectural style where the application is web-based; and Microsoft.NET related technologies are used as the development and deployment environment (as shown in the following figure). Figure 4 You must use the development standards and policies defined by the Architecture Team and Contoso such as referential architecture, coding naming, best practices, auditing policies, etc. The ContosOnline system will be deployed onto a developed and deployed using Microsoft.NET platform and related technology: IIS 7.0 Microsoft.NET 4.0 Visual Studio.NET 2010 WCF 4.0 AS.NET MVC 2.0 LINQ to SQL as the ORM Oracle 10g database jQuery ExtJS   [We can also include the rationale for the decisions] 3.2    Architectural and design patterns In order to develop the ContosOnline system, the main architectural pattern is based on multiple layers and service-oriented architecture. You can also use other styles such as component-based and aspect-oriented architecture. 3.3    Usability The solution must follow the latest user experience standards and supporting technologies, in order for the human actors to use easily the system and reduce the learning curve. You can use mockups for the screen analysis and design as well as RIA technologies such as Ajax, jQuery, ExtJS, etc. 3.4    Transaction The ContosOnline system is transactional, leveraging the technical platform capabilities. Transaction management model of the Microsoft.NET platform will be reused intensively. 3.5    Security The ContosOnline system must be secured, so that a customer can make online payments. It must support the following security services: •         Authentication: Login using at least a user name and a password •         Authorization: According to their profile, online customer must be granted or not to perform some specific actions (gold customer, business partners, etc.) For internet access, the following requirements are mandatory •         Confidentiality: Sensitive data (credit card payments) must be encrypted using secure channels such as SSL and HTTPS. •         Data integrity: Data sent across the network cannot be modified by a tier •         Auditing: Every sensitive action can be logged •         Non-repudiation: Gives evidence a specific action occurred Security model for Microsoft.NET and Windows infrastructure will be reused. 3.6    Integration Integration is the system capacity to exchange messages with external systems. The architectural pattern for the message exchange between systems must follow the service-orientation schema. The implementation strategy is based on Web services and its realization using Windows Communication Foundation (WCF). For a correct integration between systems, you need to specify the following items: Interfaces and the underlying operations Message schemas Communication protocol and policies. 3.7    Data Migration When an existing application is replaced, there will be a critical need to migrate data (master and transactional) to the new application. We should identify data migration requirements and also provide indicators as to the level of transformation, weeding, and cleansing that will be required to present data in a format that meets the requirements and constraints of the ContosOnline system. The objective being that the ContosOnline system has quality data when it is populated. Another key consideration is to ensure that an enterprise-wide common data definition is established to support the transformation. In this case, there is no strategy for data migration for the ContosOnline system. 3.8    Availability The ContosOnline system must ensure high availability architecture with failover capabilities. High availability is usually expressed as the percentage of uptime in a given year. This is very important for operational continuity of the customer business and it requires having the system operationally for 24×7. The common availability architecture is through redundant elements in the whole system such as redundant power suppliers, cluster of servers, RAID configuration for disks, multiple network interfaces and redundant routers. There are many techniques such as replication, fault tolerance, application clustering, workload balancing and disaster recovery plans. In order to provide high availability for ContosOnline system, we need to use RAID for data storage and an Active-Active schema with a workload balancer and two application server nodes and a Real Application Clusters (RAC) solution (provided by Oracle database) for the database (see the figure below). Figure 5 3.9    Reliability The ContosOnline system must be robust and work according to the functional specification. The system cannot fail when executing the functionalities: Display Information for Product and Buy a Product. The remainder functionalities can have a low fail rate. You should realize the following rules: Show friendly messages and log the technical exceptions Define messages according to the exception event All the exceptions must be caught The system must be capable to detect external source of exceptions in order to mitigate the risks 3.10Performance Performance is characterized by the amount of useful work accomplished by a computer system compared to the time and resources used. This quality requirement is much related to reliability and high availability. The ContosOnline system has a strong performance constraint when executing the functionalities: Display Information for Product and Buy a Product. In the case of the functionality Display Information for Product, the response time must be under 5 seconds. In the case of the functionality Buy a Product, the response time must be under 60 seconds in the whole process. The ContosOnline system must support the following metrics: Short response time for a given piece of work. Under 10 seconds High throughput (rate of processing work). Capable for processing 100 transactions per second Low utilization of computing resource(s). Under 1 Gb of RAM In order to achieve the performance requirements for the ContosOnline system, we´re going to follow the architecture defined in the Availability section. 3.11Scalability Scalability is the ability of the system to handle growing amounts of work in a graceful manner or its ability to be enlarged with more resource to accommodate that growth. There are two methods to add more resources to the system: scale out and scale up. To scale horizontally (or scale out) means to add more nodes to a system, such as adding a new computer to a distributed software application. An example might be scaling out from one Web server system to three. To scale vertically (or scale up) means to add resources to a single node in a system, typically involving the addition of CPUs or memory to a single computer. Such vertical scaling of existing systems also enables them to use virtualization technology more effectively, as it provides more resources for the hosted set of operating system and application modules to share. In order to achieve the scalability requirements for the ContosOnline system, we´re going to follow the scale out method through the architecture defined in the Availability section. 3.12Internationalization (I18N) The ContosOnline system must be able to deal with several languages (at least English and Spanish) So the presentation layer must be able to support i18n. 3.13Modificability The ContosOnline system must follow an architectural style which supports modificability. The N-tier architectural style enables the modificability of the system natively.   3.14Audit trailing and technical logging The ContosOnline system must log any technical exception using Log4Net logging framework and the business audit must be through an Audit table recording information about the important entities. You should register the errors in order to find the causes when the system is on production environment. Errors must be logged following the statements log.error() and log.fatal() depending the severity of the error. 4.       Use Case View The Use Case view presents the perception of the system functionality from the user point of view. The most important business process and its context are described as well as the most critical use cases derived. It lists use cases or scenarios from the use-case model if they represent some significant, central functionality of the final system. They are the base for specifying the system architecture. 4.1    Use Case Realization The only use-case with a significant impact on the ContosOnline system architecture is the one related to online buying process (UC03 – Buy a Product). The traceability matrix for the use cases is shown below. Legend: 1)        Presentation Layer 2)        Service Layer 3)        Business Logic Layer 4)        Data Access Layer 5)        Usability 6)        Transaction 7)        Security 8)        Integration 9)        Availability 10)     Reliability 11)     Performance 12)     Scalability 13)     Internationalization 14)     Audit trailing and technical logging Use Case   Traceability of Use Case through the Application Layers Traceability of Use Case through Quality Requirements 1 2 3 4 5 6 7 8 9 10 11 12 13 14 UC03 – Buy a Product Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes The use cases are detailed in the following sub-sections. 4.1.1  UC03- Buy a Product Use Case: UC03 – Buy a Product UseCase_ID UC03 – Buy a Product Complexity Medium Principal Actors Online Customer Secondary Actors Pre-conditions The online customer is logged into the ContosOnline system The ContosOnline  system displays a list of products Main Flow Steps Actor System 1 The online customer selects a product from the list 2 The system displays the detail information for the product, the underlying payment method and a button to begin the order process 3 The online customer submit the information (product, payment and shipping information) in order to start the order process 4 The system connects to an external Web service (provided by an online banking system) and validate the payment information 5 The system validates that there is stock in the warehouse for the product 6 The system connects to an external Web service in order to start the shipping process and gets a tracking number 7 The system notifies to the online system that order is done correctly and display a tracking number 8 The online user can see the order verification and tracking number in a message Post-Conditions The shipping process has started (using an external Web service) The online customer can track the product shipping Alternative Flow Steps Actor System 4.1 The system cannot connect to the banking Web service and displays a message error window 5.1 The system validates that there is no stock for the product and displays a message 6.1 The system cannot connect to the shipping Web service and displays a message error window [Note: You can also include a high-level screen prototype.] 5.       Logical View 5.1    Overview This section of the document describes the structural hierarchy of the system in layers, subsystems and packages, and then goes to describe how these artifacts collaborate to provide the most architecturally functionality. For each significant package, decompose them in significant static and dynamic views, if necessary. 5.2    Architecturally significant design packages This sub-section describes the overall decomposition of the design model. The ContosOnline system comprises of the following modules to support the business process: Product Management, Online Selling and Reporting modules. In order to implement this module, we need to follow the N-tier architectural style (as shown in the following figure). Figure 6 5.2.1 Product Management Module Name:   Product Management Module Description: This module enables adding new products, updating the underlying information and deleting a product Most Significant Diagrams Figure 7 5.2.2 Online Selling Module Name:   Online Selling Module Description: This module enables displaying a list of products. You can select a particular product and the underlying information is shown. After, the online customer a product to buy, the selling process starts. A tracking number is sent in order to check the selling status. Most Significant Diagrams   5.2.3 Reporting Module Name:   Reporting Module Description: This module enables showing a lot of consolidated information about the products, its stock and the revenues for the sales. Most Significant Diagrams   6.       Process View 6.1    Overview This sub-section depicts the system´s decomposition into light weight processes (single threads of control) and heavy weight processes (group of light weight processes). Describe the main modes of communication between processes. The ContosOnline system has no process to describe in this view. 7.       Deployment View 7.1    Overview In this section, the deployment is described by identifying the infrastructure in which the ContosOnline system is deployed and run. It is specified any deployment constraints and how the ContosOnline system components are distributed over computing nodes. 7.2    Topology (single computer/client-server/distributed N-tier) The deployment topology for the ContosOnline system is as shown in the following figure. Figure 8 7.3    Hardware requirements According to the high availability, reliability and performance requirements. 7.4    Platform requirements According to the platform requirements in the sub-section Implementation Strategy. 8.       Implementation View 8.1    Overview The implementation view depicts the physical composition of the implementation in terms of implementation artifacts such as source code, data, development frameworks, distributable files and executable files. The implementation layer must be aligned and fit the layers defined in the architecture vision and the best practices to support this architecture. The ContosOnline system will be developed using the technologies described in the sub-section 3.1 Implementation Strategy. The implementation strategy is to implement each logical layer inside an independent .NET assembly. Inside each assembly, you can find the modules logically separated by namespaces (For further details, see the following table). Namespaces/Packages Description Assembly ContosOnline.Presentation It´s a Web application developed using ASP.NET MVC technology and contains the artifacts for the correct presentation. It also uses the following JavaScript libraries: jQuery and ExtJS to support the Rich Internet Application approach. ContosOnline.Presentation.dll ContosOnline.Presentation. ProductManagement It´s a package (a folder) inside the ContosOnline.Presentation to hold the artifacts for the module ProductManagement ContosOnline.Presentation.dll ContosOnline.Service It´s a Microsoft.NET library developed using C# language and contains the service artifacts. ContosOnline.Service.dll ContosOnline.Service. Contracts It´s a package (a folder) inside the ContosOnline.Service to hold the contracts of the service. Inside this package, you should group the contracts by module (similar to the presentation structure). ContosOnline.Service.dll ContosOnline.Service.DTO It´s a package (a folder) inside the ContosOnline.Service to hold the messages of the service. Inside this package, you should group the messages by module (similar to the presentation structure). ContosOnline.Service.dll ContosOnline.BLL It´s a Microsoft.NET library developed using C# language and contains the business logic artifacts. ContosOnline.BLL.dll ContosOnline.BLL. ServiceImplementations It´s a package (a folder) inside the ContosOnline.BLL to hold the service implementations. Inside this package, you should group the service implementations by module (similar to the presentation structure). ContosOnline.BLL.dll ContosOnline.BLL. BusinessObjects It´s a package (a folder) inside the ContosOnline.BLL to hold the business objects. Inside this package, you should group the business objects by module (similar to the presentation structure). ContosOnline.BLL.dll ContosOnline.BLL. Mappers It´s a package (a folder) inside the ContosOnline.BLL to hold the mappers (transformations from the entities to DTO). Inside this package, you should group the mappers by module (similar to the presentation structure). ContosOnline.BLL.dll ContosOnline.BLL.Workflow It´s a package (a folder) inside the ContosOnline.BLL to hold the workflows. Inside this package, you should group the workflows by module (similar to the presentation structure). ContosOnline.BLL.dll ContosOnline.BLL. BusinessRules It´s a package (a folder) inside the ContosOnline.BLL to hold the business rules. Inside this package, you should group the business rules by module (similar to the presentation structure). ContosOnline.BLL.dll ContosOnline.DAL It´s a Microsoft.NET library developed using C# language and contains the data access artifacts. ContosOnline.DAL.dll ContosOnline.DAL. Entities It´s a package (a folder) inside the ContosOnline.DAL to hold the business entities. Inside this package, you should group the business entities by module (similar to the presentation structure). ContosOnline.DAL.dll ContosOnline.DAL. DAO It´s a package (a folder) inside the ContosOnline.DAL to hold the data access objects. Inside this package, you should group the data access objects by module (similar to the presentation structure). ContosOnline.DAL.dll ContosOnline.DAL. ServiceAgents It´s a package (a folder) inside the ContosOnline.DAL to hold the service agents. Inside this package, you should group the service agents by module (similar to the presentation structure). ContosOnline.DAL.dll 8.2    Layers 8.2.1 Presentation Layer The Presentation layer contains all the components needed to allow interactions with an end-user. It encompasses the user interface and how to handle the user requests and responses. The Presentation layer will be developed using the MVC architectural style and the technology ASP.NET MVC. In order to enrich the user interface, we´re going to use JavaScript libraries such as jQuery and ExtJS (a pack of controls) and latest trends in HTML and CSS for the content presentation. The iconography and graphical styles must be consistent with the corporate colors of Contoso. In order to present a common layout in all the pages of the application, we´re going to use the approach Master Page of ASP.NET. 8.2.2 Service Layer The Service layer contain all the definitions of the services that are exposed to external systems such as service contracts (operations, message format, message exchange pattern), the communication patterns (REST vs SOAP), url and the behavior of the service. The Service layer will be developed using Windows Communication Foundation (WCF) and the underlying programming model. 8.2.3 Business Logic layer The Business Logic layer contains all the components that represent the concepts to support the business process. It contains business objects, entities, rules workflows, and so on. The Business Logic layer will be developed using C# and the underlying technologies provided by Microsoft.NET. 8.2.4 Data Access layer The Data Access layer contains all the components that represent the entities mapped to the relational schema and the communication mechanisms with the database engine. It also contains the logic to access other data source as well as the definitions of Web services’ clients (service agents). The Data Access layer will be developed using C# and LINQ as the ORM technology. 9.       Data View (optional) This view represents the data model and the underlying distribution as well as the persistence and transactional services to access the data. The data model for ContosOnline system is shown below: Figure 9   For ContosOnline system, there is no distribution at the data level. All the database artifacts reside in the same data base. The persistence service used for ContosOnline system is based on LINQ technology (Microsoft proposal for ORM). All the execution of use cases in ContosOnline system must be under a transactional context. When starting to execute a use case, you should start a transaction. When finishing the use case, in case of success you should execute a commit transaction command, otherwise you should execute a rollback transaction command.   10.   Size and Performance Volumes: Estimated online orders : 100 a day, with peaks in the evening ContosOnline system registered individual customer : about 150 ContosOnline system corporate online operators : about 100 Performance: Time to process and online selling (credit card validation + confirmation) : less that 10 seconds required 11.   Quality The ContosOnline system is being developed by an internal team. We need a quality control team externally. Page3 ———————————————————————————————————————–

Listing 2

Conclusion

In this article, I’ve talked about specifying the architecture of software intensive systems. Now you can use the techniques, document templates and examples to apply in your own scenario.