Software Architecture Document Template
Software Architecture Document Template
Software Architecture Document Template
Version 1.7
04/11/2013
Revision History
Approval Block
Version Comments Responsible Party Date
1. Introduction ...................................................................................................................... 1
1.1. Purpose ..................................................................................................................................... 1
1.2. Scope ........................................................................................................................................ 1
1.3. Definitions, Acronyms, and Abbreviations ................................................................................ 2
1.4. References ................................................................................................................................ 2
1.5. Overview ................................................................................................................................... 2
2. Architectural Representation .......................................................................................... 3
3. Architectural Goals and Constraints .............................................................................. 4
4. Use-Case View ................................................................................................................. 4
4.1. Actors ........................................................................................................................................ 4
4.2. Use-Case Realizations.............................................................................................................. 5
4.2.1. Login ................................................................................................................................... 5
4.2.2. Request Analysis (Get Report) ........................................................................................... 6
4.2.3. Retrieve Last Report ........................................................................................................... 9
4.2.4. Print Report....................................................................................................................... 10
4.2.5. Email Report ..................................................................................................................... 11
5. Logical View ................................................................................................................... 12
5.1. Overview ................................................................................................................................. 12
5.2. Interface Definitions ................................................................................................................ 14
6. Data View ........................................................................................................................ 22
7. Deployment View ........................................................................................................... 25
Software Architecture Document (SAD) iii Distributed Development Monitoring and Mining
Software Architecture Document
1. Introduction
This document provides a high level overview and explains the architecture of the Distributed
Development Monitoring and Mining system.
The document defines goals of the architecture, the use cases supported by the system, architectural
styles and components that have been selected. The document provides a rationale for the
architecture and design decisions made from the conceptual idea to its implementation.
1.1. Purpose
In order to depict the software as accurately as possible, the structure of this document is based
on Philippe Kruchten’s “4+1” model view of architecture [Kruchten].
The “4+1” View Model allows various stakeholders to find what they need in the software
architecture.
1.2. Scope
The scope of this SAD is to explain the architecture of the Distributed Development Monitoring
and Mining system.
This document describes the various aspects of the DMM system design that are considered to
be architecturally significant. These elements and behaviors are fundamental for guiding the
construction of the DMM system and for understanding this project as a whole. Stakeholders who
require a technical understanding of the DMM system are encouraged to start by reading the
Project Proposal, Concept of Operations and Software Requirements Specification documents
developed for this system [PP, ConOps, SRS].
1.4. References
[Kruchten]: 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
1.5. Overview
In order to fully document all the aspects of the architecture, the Software Architecture
Document contains the following subsections.
Section 2: describes the use of each view
Section 3: describes the architectural goals and constraints of the system
Section 4: describes the most important use-case realizations
Section 5: describes logical view of the system including interface and operation definitions.
Section 6: describes significant persistence elements.
Section 7: describes how the system will be deployed.
This document details the architecture using the views defined in the “4+1” model [Kruchten]. The
views used to document the DMM system are:
Logical view
Audience: Designers.
Area: Functional Requirements: describes the design's object model. Also describes the
most important use-case realizations and business requirements of the system.
Related Artifacts: Design model
Data view
Audience: Data specialists, Database administrators
Area: Persistence: describes the architecturally significant persistent elements in the data
model as well as how data flows through the system.
Related Artifacts: Data model.
Deployment view
Audience: Deployment managers.
Area: Topology: describes the mapping of the software onto the hardware and shows the
system's distributed aspects. Describes potential deployment structures, by including known
and anticipated deployment scenarios in the architecture we allow the implementers to
make certain assumptions on network performance, system interaction and so forth.
Related Artifacts: Deployment model.
1. The system is meant as a proof of concept for a more complete project prediction system to
be built in the future. Therefore one of the primary stakeholders in this document and the
system as a whole are future architects and designers, not necessarily users as is normally
the case. As a result, one goal of this document is to be useful to future architects and
designers.
2. The system will be written using Microsoft .NET technologies but will use an open source
RDBMS system (MySQL) for data persistence and will be deployed to a Linux webserver
running Mono. These special deployment requirements require additional consideration in
the development of the architecture.
3. The system must communicate with multiple third-party APIs, Assembla and Google
Predictive. Defining how the system interfaces with these third-party systems is a primary
concern of the architecture.
4. Use-Case View
The purpose of the use-case view is to give additional context surrounding the usage of the
system and the interactions between its components. For the purposes of this document, each
component is considered a use-case actor. Section 4.1 lists the current actors and gives a brief
description of each in the overall use context of the system. In section 4.2, the most common
use-cases are outlined and illustrated using UML use-case diagrams and sequence diagrams to
clarify the interactions between components.
4.1. Actors
User
The user will drive all operation of the software. No distinction is made in regards to type
of user. The user interacts with all available interfaces to initiate and monitor all
application operations.
Assembla Client
The Assembla client serves to aid in user authentication and general assembla
accessibility.
Web Portal
The web portal is the main user interface for the system.
Prediction Service
The Prediction Service is the link between our application and the Google Predictive API.
4.2.1. Login
User credentials are authenticated and user is redirected to application home page.
The main goal of the logical view is to define the components that will make up the system and
to define the interfaces through which they will communicate and interact with one another. The
primary decision-making factor behind defining the system components is the need to isolate
the components that are likely to change from the rest of the system. By clearly defining the
interfaces of these components and hiding their internal implementations from the rest of the
system, the impact of expected changes can be minimized. Section 3.3 of the Software
Requirements Specification outlines the changes that are likely to be made to the system. A
summary of these changes and how the logical decomposition of the architecture addresses
them is as follows:
4. Changes to the content of the prediction report generated for the user
a. This report is generated in the Web Portal module (see figure 5.1). As such
changes to its content need only be made in this module.
Assembla_Client::Assembla_Client_Interface
Interface Signature
public interface IAssemblaClient
{
HttpWebResponse Milestones(string spaceId);
HttpWebResponse PublicSpaceNamesForPage(int pageNumber);
HttpWebResponse PublicSpaces();
HttpWebResponse SpaceTools(string spaceId);
HttpWebResponse TicketsByMilestone(string spaceId, string milestoneId);
HttpWebResponse UserSpaces(string accessToken);
HttpWebResponse Space(string accessToken, string spaceId);
HttpWebResponse AuthorizeUser();
HttpWebResponse GetAccessToken(string authorizationCode);
}
Operation Definitions
Milestones(string spaceId)
Description: This operation connects to the Assembla API and downloads all Milestones
associated with a particular Space as identified by the spaceId parameter.
Precondition: A valid Assembla application ID and application secret must be sent in the
request headers in order to authenticate with the Assembla API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the Milestone data. The caller is responsible for
deserializing the response.
PublicSpaceNamesForPage(int pageNumber)
Description: This operation connects to the Assembla website and downloads a specific HTML
page containing publicly available space IDs. The page to download is specified by the
pageNumber parameter.
Precondition: None
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
HTML content of the page requested.
Description: This operation connects to the Assembla website and downloads the HTML page
that lists all publicly available space IDs.
Precondition: None
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
HTML content of the page requested.
SpaceTools(string spaceId)
Description: This operation connects to the Assembla API and downloads all Tools associated
with a particular Space as identified by the spaceId parameter.
Precondition: A valid Assembla application ID and application secret must be sent in the
request headers in order to authenticate with the Assembla API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the Tool data. The caller is responsible for deserializing
the response.
Description: This operation connects to the Assembla API and downloads all Tickets associated
with a particular Space and Milestone as identified by the spaceId and milestoneId parameters.
Precondition: A valid Assembla application ID and application secret must be sent in the
request headers in order to authenticate with the Assembla API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the Ticket data. The caller is responsible for deserializing
the response.
UserSpaces(string accessToken)
Description: Returns a list of spaces that the currently logged on user has access to.
Precondition: User has successfully logged on through Assembla and a valid access token has
been obtained.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the Spaces data. The caller is responsible for deserializing
the response.
Description: This operation connects to the Assembla API and downloads all data associated
with a particular Space and user as identified by the spaceId and accessToken parameters.
Precondition: User has successfully logged on through Assembla and a valid access token has
been obtained. The user must also have access to at least one Assembla space.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the Space data. The caller is responsible for deserializing
the response.
AuthorizeUser()
Precondition: A valid Assembla client ID must be sent in the request query string in a
parameter named “client_id”.
GetAccessToken(string authorizationCode)
Description: Calls the Assembla API method to generate an access token for an authorized
user.
Precondition: User has been authorized and an authorization code obtained through the
AuthorizeUser() method. A valid authorization code must be passed in to the
authorizationCode parameter.
Assembla_Data_Retrieval_Service::Assembla_Data_Retrieval_Service_Interface
Operation Definitions
GetAllPublicSpaces()
Description: This operation gets all public space IDs from Assembla and saves them to the
database.
Precondition: None
Postcondition: All publicly accessible space IDs are saved to the database.
GetMilestones ()
Description: This operation gets milestone data for each of the space IDs saved in the database
and saves the milestone data to the database.
Postcondition: Milestone data for each space ID present in the database is saved to the database
and associated with the appropriate space ID.
Description: This operation gets a list of all spaces that a user has access to.
Precondition: The user has successfully logged on to Assembla and a valid access token has
been obtained to pass to this method.
Description: This operation gets data for a specific Space that a user has access to.
Precondition: The user has successfully logged on to Assembla and a valid access token has
been obtained to pass to this method. The user also has access to at least one Space.
GetTicketsForMilestones ()
Precondition: A list of milestones and associated space IDs is available in the database.
Postcondition: Ticket data for each milestone present in the database is saved to the database
and associated with the appropriate milestone ID and space ID.
Application_Data_Service::Application_Data_Service_Interface
Operation Definitions
Description: This operation saves a prediction report to the application data store.
Description: This operation gets the last saved prediction report for a particular space.
Precondition: At least one prediction report has been previously saved to the application data
store.
Prediction_Client::Prediction_Client_Interface
Interface Signature
public interface IPredictionClient
Operation Definitions
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the analysis data. The caller is responsible for
deserializing the response.
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the delete operation status. The caller is responsible for
deserializing the response.
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the status of the trained model if it is done or still in
progress. The caller is responsible for deserializing the response.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the model data. The caller is responsible for deserializing
the response.
HttpWebResponse List ()
Description: This operation connects to the Google Predictive API and list available models.
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the list of models. The caller is responsible for deserializing
the response.
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the prediction. The caller is responsible for deserializing the
response.
Precondition: A valid model ID and application secret must be sent in the request headers in
order to authenticate with the Google Predictive API.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the model update data. The caller is responsible for
deserializing the response.
HttpWebResponse AuthorizeUser()
Description: This operation connects to the Google Predictive API using the secrets for the
user.
Postcondition: An HttpWebResponse object is returned to the caller. This object contains the
JSON formatted response containing the authnitcation ID. The caller is responsible for
deserializing the response.
Prediction_Client_Service::Prediction_Client_Service_Interface
Interface Signature
Operation Definitions
PredictionFeedback Predict()
Description: This operation is doing the actual prediction by sending the data to Google
Predictive Client and retrieving the results
Precondition: All parameters are set such as action, model name and prediction data
Postcondition: The model has been updated from the data gathered from the collaboration
database and it will return status of failure or success
Web_Portal::Web_Portal_Interface
Interface Signature
public interface IWebPortal
{
HttpWebResponse AuthorizeUser(string url)
HttpWebResponse GetSpacesForUser(string accessToken)
HttpWebResponse RunPrediction(string spaceId)
HttpWebResponse GetLastUserReport(string userId)
}
Operation Definitions
AuthorizeUser(string url)
Precondition: Assembla authentication API requires client Id. The Client Id will be stored into
application’s configuration file.
Postcondition: Once user enters User Id and Password; Assembla API authenticates the user and
redirects the user to DMM’s home page.
GetSpacesForUser(string accessToken)
Description: This operation gets the project space Ids associated with the user.
Precondition: User needs to be authenticated. User Id is passed for getting the spaces.
Postcondition: User associated spaces are returned back to the user interface and those get
populated into the drop-down box. The return object is HttpWebResponse. The JSON formatted
response will be parsed at client.
RunPrediction(string spaceId)
Description: Once the user selects the project space to be analyzed and clicks the button
‘Analyze’, this operation is triggered.
Precondition: The Space Id that needs to be analyzed should be selected in the drop-down box.
Postcondition: Google Predictor API does the analysis depending upon the past training data
supplied and returns back with the analysis report that gets displayed on the user report interface.
GetLastUserReport(string userId)
Description: User is able to see the last analysis report that s/he has run previously. Clicking the
menu item, calls this operation.
Precondition: User Id needs to be passed. The model logic will look for the last report for the
specific user Id into the database.
6. Data View
This diagram illustrates the static data structure and relationships of the main entities that will be stored
by the application in its database. Each element nominally represents a database table. Relationship
cardinality is denoted with UML multiplicity notation.
<<database system>>
MySql Server
Web Portal
<<cloud>>
Google
Predictive API
Prediction Service