Project Process and Documentation

In my previous post, I described a default architecture for a UI application. In this post, I will introduce the concept for a system that requires a UI application (as well as other software packages) and briefly describe a process for discovering system requirements (user stories, scenarios, and feature specifications). Once the system requirements are defined, and using system architecture guidelines like the one in the previous post, product requirements can be defined.

The first step in a project’s life-cycle is the establishment of a project charter. Given that this is a fictitious project, there isn’t a real project charter. However, I did create a wiki (warning: be sure to have an ad blocker running) to keep track of some overly simplistic artifacts to use as a place to keep my ideas straight as I walk through the process of developing this conceptual project. Included in that wiki, is the Circulade Project Charter.

The overview of the Circulade system is to create a platform for enabling people trying to ship cargo to connect with carriers trying to fill their cargo containers for a route. This connection will allow shippers to find better shipping rates by finding containers with available space that can be purchased at a discounted price compared to standard shipping rates. Carriers will be able to make more money by selling space that would otherwise be left empty on an already planned shipment.

Once a project charter has been approved by the stakeholders, the project initiation process begins. However, since I want to keep focused on the deliverables of a project, I won’t be describing that process. For more details on project management, see the following:

To use terms from the PRINCE2 methodology, this post will be focused on the procedures in the Managing Product Delivery process. The “work package” to be delivered is the System Requirements for the project. This is accomplished by applying the business analysis process. The initial delivery of the System Requirements will consist of the most prominent User Stories and their most prominent Scenarios along with a list of Features the project will be expected to deliver and the Quality of Service requirements that will constrain the delivery of those features.

Business Analysis Process

System requirements specify the features a system must have in order to assist users with completing processes. These processes are described as Scenarios which detail a specific set of steps that are used to accomplish a User Story’s goal. Scenarios and User Stories are referred to as Business Requirements.

Business Requirements

User Stories

It is beyond the scope of this post to list all of these requirements, especially since this is a fictional system. However, the wiki contains some examples of the user stories used to produce this project.

If this were a real business, a Business Analyst would work with subject matter experts to elicit and document User Stories. More in-depth descriptions of user stories can be found at the following links:

For each user story, the analyst further examines the processes and procedures required to accomplish the goal of the story. This examination results in Scenario descriptions.

Scenarios

A scenario describes the process an actor must step through in order to achieve a goal . It specifies what information is needed, what decisions must be made based on that information and what to do with the result of those decisions. Another way of thinking about scenarios is to consider them “user flows” or “use cases”.

For existing organizations with detailed business process and procedure documentation, this activity is much easier, as the scenarios are essentially the process descriptions or are slightly modified versions of them as projects are usually intended to provide a new or improved process for the organization.

Again, some simplistic examples can be found on the Circulade wiki.

For more detailed examinations of the scenario writing process, read the following articles:

System Requirements

Features

Based on the Project Charter, User Stories, and Scenarios, a business analyst can specify the features a system must provide in order to enable the users to more efficiently accomplish their goals. For each Feature, a set of Feature Requirements will be defined.

This post provides a good example of the difference between a Feature and a Feature Requirement.

Quality of Service

QoS requirements are non-functional requirements such as availability, maintainability, extensibility, etc. These are important to capture in order to meet the expectations of the users and the stakeholders. The FURPS+ system is a useful way of thinking about these types of requirements in order to elicit these needs from the stakeholders and subject matter experts.

For the Circulade project, the system requirements examples are on the wiki.


Solutions Architecture Process

With the first batch of system requirements defined, a solutions architect, along with a user experience architect, should analyze the business requirements in order to identify any subsystems, or natural boundaries, within the organization and use these bounded contexts to define deployable packages of software/hardware necessary to fulfill the business requirements of the subsystems. This analysis is best handled by using the principles described by Domain-Driven Design. For a deep dive into these principles, see the following resources:

Once a bounded context has been identified and the software/hardware requirements are being determined, if the context requires a user facing application (and almost all of them do), the architects design the wireframes of the UI screens and detail the information needed for display and manipulation.

The solutions architect uses the system requirements analysis along with the wireframes and information details to specify the product requirements as a set of interface definitions.

The next post will explore the product requirements for the Circulade system’s public context.

Default Architecture for a UI Application

In this post I’m going to cover the default/general architectural structure that I use when building a UI application.

Application Architecture Composition

When designing the architecture of an application I like to break the package down into components. Each component is responsible for providing an interface to a set of cohesive features that can be loosely coupled with other components to provide the full set of features required by the application.

As a general rule and default starting place for a GUI application, the primary components will be an implementation of the MVC architectural pattern. This decision encourages the notion that there should be at least three components in our application: Model, View and Controller. In order for these components to be loosely coupled, the application will likely need a few services such as a message broker and a dependency injection service. So I’ll add another component called Service. All applications need to have an entry point into the package, so I’ll add one more component to the solution that will be called UI as this is the component that is responsible for providing users access to the application.

Within the Model component, there are two subcomponents: Command and Event. The Model.Command component isolates data structures used to represent user commands sent from objects in the View to objects in the Controller. The Model.Event component isolates data structures used to represent events raised by objects in the Model changing state.

Below is a UML component diagram that shows the dependency chain of these components. I used UMLetino to create the diagram.

component-dependency-diagram

 

The Model and the Service components are the most important since all of the other components depend on them. Also notice that neither the Model nor the Service components depend on any thing.

Model Component

The Model component is responsible for providing the state of the application and encapsulating the logic the application is providing the user the ability to work with. It is also responsible for declaring Command and Event objects that are used to model the behavior the application is modeling. For example, if the application was supporting an Accounts Receivable Clerk’s ability to create invoices, then there would likely be an Account object in the Model component, a GenerateInvoice object in the Command component and an InvoiceGenerated object in the Event component.

Most applications will require some sort of user security where a user must authenticate their credentials to prove their identity to the system and once their identity is recognized, the system will grant them authorization to access and potentially manipulate resources controlled by the system.

If the application requires tracking the state of a user, they could be modeled in a Session object. An active Session would have properties such as an Identity representing the user’s information such as name, title, contact information, etc.; and a set of authorization Claims representing the authorizations granted the user. It would also provide a method to end the Session. The commands and events corresponding to the Session would include objects such as AuthenticateCredentials, AuthenticationFailed, SessionInitialized, SessionStarted, and SessionEnded.

View Component

The View component is responsible for providing a visual representation of the state of theĀ  objects in the Model component. Objects in the View component will use a message broker to subscribe to one or more Model.Event(s) in order to be notified when a Model object has changed its state.

Objects defined in the View component are responsible for translating user interactions into the appropriate Model.Command objects and publishing those commands via a message broker. Typically, applications display a nameplate/masthead that display the organization’s logo, controls for accessing the user’s profile, as well as the ability to logout, and a menu of links to resources/features of the application. These nameplates come in many styles and each system will require the application’s display stylistically match the organization’s branding. To design an application with this minimal feature, we would need to include Masthead, Logo, Profile, and IdentityChallenge objects in the View component.

The Masthead would subscribe to the SessionInitialized event and would handle receiving notification of that event by checking if the Session that was initialized is currently active and if it is, render the Logo, Profile and itself. If the Session isn’t active, then the Masthead would remove the Profile from view and potentially even change the style of the Logo to be larger and/or in a different position.

Similarly, the IdentityChallenge would be subscribed to the SessionInitialized event and would check if the initialized Session was active. If it is active, the IdentityChallenge would remove itself from the UI as it is not required. If it isn’t active, it would append itself to the UI in order to allow the user to authenticate/start a new Session.

Controller Component

The Controller component is responsible for controlling the state of objects in the Model. Objects in the Controller component will use a message broker to subscribe to one or more Model.Command(s) in order to be notified when a View object has been interacted with by a user. Objects defined in the Controller component are responsible for calling the appropriate methods on a Model object based on the received Command and publishing the results as a Model.Event object. In some cases, the Model object’s method that corresponds with the received Command will require data that is external to the application. In those cases, the Controller object will use a service to make a call to the external data source and use the results of that request to fulfill theĀ  Command.

As an example, if the Profile object in the View component contains a button for logging out, when the user clicks that button the Profile will publish a new EndSession command. The SessionController object will be subscribed to that event and be notified. It will then send an HTTP request to the identity and access management API (examples are Auth0 or Google’s Firebase Auth) to end the user’s session. When it receives a success response it will call the End() method on the Session object.

Service Component

The Service component is responsible for providing application services to the other components. These services include a dependency injection container and a pub/sub message broker.

Objects defined in the Service component are responsible for handling the infrastructure duties required by any application to function in its host environment.

UI Component

The UI component is responsible for providing the entry point of the application. In the case of a browser-based application, the host environment is a browser DOM’s window object. When the window loads, it will fire a load event. The UI component makes use of the EventTarget interface and adds an EventListener which will use the Service‘s dependency injection Container to initialize the application based on configuration settings. Once the application is initialized, it will publish a SessionInitialized event via the MessageBroker. View objects subscribed to the SessionInitialized event will render the appropriate user interface and enable the application to respond to the user’s interactions as described in the View Component section above.

Next Steps

With the basic architectural guidelines defined, when a project needs a user interface application, this architecture can be used to provide a launching pad for defining the product requirements that a developer will need to implement. The next post in this series will be about defining these requirements for a fictional system.