Revision History

Table of Contents

1. 1.                  Introduction
   1. 1.1               Purpose
   2. 1.2               Scope
   3. 1.3               Definitions, Acronyms, and Abbreviations
   4. 1.4               References
   5. 1.5               Overview
2. 2.                  Architectural Representation
3. 3.                  Architectural Goals and Constraints
4. 4.                  Use-Case View
   1. 4.1               Use-Case Realizations
5. 5.                  Logical View
   1. 5.1               Overview
   2. 5.2               Architecturally Significant Design Packages
6. 6.                  Process View
7. 7.                  Deployment View
8. 8.                  Implementation View
   1. 8.1               Overview
   2. 8.2               Layers
9. 9.                  Data View (optional)
10. 10.             Size and Performance
11. 11.             Quality

Software Architecture Document

1.                  Introduction

This document covers the basics needed to understand how the Et1 Component Architecture works.  The Et1 Component Architecture serves as a complement to the Et1 Controller, by allowing fine-grained separation of Controller-type logic.  By that virtue and supporting features such as lazy-loading/instantiation of Components and automatic memory management, the Et1 Component Architecture supports essentially unlimited code size and complexity on a single page, to enablethe ultimate in desktop-app-like functionality while not compromising on the transparency of the code.  The Et1 Component Architecture allows for maximum maintainability and debuggability even when the system consists of a large amount of complex JavaScript code with inter-Component dependencies. 

[The introduction of the Software Architecture Document provides an overview of the entire Software Architecture Document. It includes the purpose, scope, definitions, acronyms, abbreviations, references, and overview of the Software Architecture Document.]

1.1               Purpose

This document provides a comprehensive architectural overview of the 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.

[This section defines the role or purpose of the Software Architecture Document, in the overall project documentation, and briefly describes the structure of the document. The specific audiences for the document is identified, with an indication of how they are expected to use the document.]

1.2               Scope

The Et1 Controller architecture is out of scope.

[A brief description of what the Software Architecture Document applies to; what is affected or influenced by this document.]

1.3               Definitions, Acronyms, and Abbreviations

(These items are listed in the order required for comprehension).

Css: Cascading Style Sheet

Component: In Et1, an instance of a Component class.  Defines a logic container for a complete, lazy-loadable application or JavaScript-applet that lives on an html Web page.  May or may not be associated with a canvas (dom container, or section of some other paintable or listenable region of the screen).

[This subsection provides the definitions of all terms, acronyms, and abbreviations required to properly interpret the Software Architecture Document.  This information may be provided by reference to the project’s Glossary.]

1.4               References

Et1 Component Architecture Test Harness

Js-doc of 'et1/src/lib/controller/component'

[This subsection provides a complete list of all documents referenced elsewhere in the Software Architecture Document. Identify each document by title, report number (if applicable), date, and publishing organization. Specify the sources from which the references can be obtained. This information may be provided by reference to an appendix or to another document.]

1.5               Overview

This document exposes the Et1 Component Architecture from a variety of architectural views.

[This subsection describes what the rest of the Software Architecture Document contains and explains how the Software Architecture Document is organized.]

2.                  Architectural Representation

We must examine the system from all views.  All views entail the use of the whole Et1 Component system.

[This section describes what software architecture is for the current system, and how it is represented. Of the Use-Case, Logical, Process, Deployment, and Implementation Views, it enumerates the views that are necessary, and for each view, explains what types of model elements it contains.]

Use-Case 

End-user is a customer of E*Trade Financial, and the system uses the Et1 Component system to better serve them (more detail below).

Logical

3.                  Architectural Goals and Constraints

Two primary concerns dominate this architecture: 

• The need to support a complex set of dependencies in the asynchronous-loading environment of the Web
• The need to manage memory properly to prevent memory leaks as Components are loaded and unloaded.

[This section describes the software requirements and objectives that have some significant impact on the architecture; for example, safety, security, privacy, use of an off-the-shelf product, portability, distribution, and reuse. It also captures the special constraints that may apply: design and implementation strategy, development tools, team structure, schedule, legacy code, and so on.]

4.                  Use-Case View

[This section lists use cases or scenarios from the use-case model if they represent some significant, central functionality of the final system, or if they have a large architectural coverage—they exercise many architectural elements or if they stress or illustrate a specific, delicate point of the architecture.]

4.1               Use-Case Realizations

End-user logs-in to etrade.com and the system responds with the user's home page.  The user is invested in a variety of accounts and investment vehicles.  Details of each, with specific application functionality, load in various portions of the screen.  

One Component holds a special view of one type of the customer's investment accounts.  However, it depends on another Component that loads all the customer's investmetn accounts of that type.  Therefore, the system ensures that the Components are loaded in the proper order.

A parent Componnent contains an investment account with the option to buy and sell shares in that investment account.  The buying and selling must proceed according to unique logic.  That logic is contained in two sub-Components of the parent Component.

The system is overloaded at the time, and cannot deliver the data for the Component that shows the customer's investment account 'A'.  The logic inside that Component handles the situation (e.g., waiting and retrying its call for the data, displaying a notification to the user, etc).  

The end-user would like to go from the special view of one type of his or her investment accounts to another.  The user makes that selection in the Component that supports the special view.  The Component then emits an event that alerts the Controller logic.  The Controller logic then destroys the Component (along with its Component tree), freeing its memory for garbage collection.  It then loads the Component that will offer the special vew and features that the end-user desires.

[This section illustrates how the software actually works by giving a few selected use-case (or scenario) realizations, and explains how the various design model elements contribute to their functionality.]

5.                  Logical View

[This section describes the architecturally significant parts of the design model, such as its decomposition into subsystems and packages. And for each significant package, its decomposition into classes and class utilities. You should introduce architecturally significant classes and describe their responsibilities, as well as a few very important relationships, operations, and attributes.]

5.1               Overview

This section will touch on 'Et1.oController.Controller', but specifics about that class are out of scope.

[This subsection describes the overall decomposition of the design model in terms of its package hierarchy and layers.]

5.2               Architecturally Significant Design Packages

Et1.oController

    Et1.oController.Controller 

                A singleton that is the master of the html Web page.  If there are Components on the page, this class will have an instance 

                of  Et1.oController.oComponent.ComponentManager.  

[For each significant package, include a subsection with its name, its brief description, and a diagram with all significant classes and packages contained within the package.

For each significant class in the package, include its name, brief description, and, optionally, a description of some of its major responsibilities, operations, and attributes.]

6.                  Process View

1. Controller loads on the page.
2. Controller finds Component configuration objects, if any, in the page config ('Et1.oModel.oPage.oConfig').  
3. Controller instantiates Component Manager.
4. Component Manager synchronously instantiates a ComponentBuilder for each Component, following the Component order in the config.
5. ComponentBuilder asychronously loads the css (Cascading Style Sheet) files, if any.  
6. ComponentBuilder asychronously loads the batch of JavaScript files. 
7. ScriptIncludeListLoader synchronously loads the individual JavaScript files in the batch, in order.  It uses the Messenger to do this, which is out of scope.  See the js-doc linked above for more details.
8. ComponentBuilder instantiates the Component.
9. If the Component finds any Component configuration objects, this process sequence is repeated from Step #2, with 'Component' being substituted for 'Controller'.

[This section describes the system's decomposition into lightweight processes (single threads of control) and heavyweight processes (groupings of lightweight processes). Organize the section by groups of processes that communicate or interact. Describe the main modes of communication between processes, such as message passing, interrupts, and rendezvous.]

7.                  Deployment View

Normal Web deployment.  This system consists solely of JavaScript, Html, and optional Css.

[This section describes one or more physical network (hardware) configurations on which the software is deployed and run. It is a view of the Deployment Model. At a minimum for each configuration it should indicate the physical nodes (computers, CPUs) that execute the software and their interconnections (bus, LAN, point-to-point, and so on.) Also include a mapping of the processes of the Process View onto the physical nodes.]

8.                  Implementation View

General Info

Refer to the Et1 Architecture Document.

[This section describes the overall structure of the implementation model, the decomposition of the software into layers and subsystems in the implementation model, and any architecturally significant components.]

8.1               Overview

The architecture is a layered one, with a Mediator layer managing a forest of Component trees for its client object, and each Component optionally having its own forest of Component trees, recursively with no limit.  

[This subsection names and defines the various layers and their contents, the rules that govern the inclusion to a given layer, and the boundaries between layers. Include a component diagram that shows the relations between layers. ]

8.2               Layers

Mediator Layer: Managed by an instance of 'Et1.oController.oComponent.Component'.  The top-level class used to aid management of the Components is 'Et1.oController.oComponent..ComponentBuilder'.

Component Layer: A tree of Components.  A Component is or inherits from 'Et1.oController.oComponent..Component'.

[For each layer, include a subsection with its name, an enumeration of the subsystems located in the layer, and a component diagram.]

9.                  Data View (optional)

Event listeners are held in RAM so that the event listeners can be removed on 'destroy' (memory management).  The method 'storeListener' is provided on Component for that purpose.

[A description of the persistent data storage perspective of the system. This section is optional if there is little or no persistent data, or the translation between the Design Model and the Data Model is trivial.]

10.             Size and Performance

A basic forest of Component trees leaks no memory on 'destroy' on platforms such as Safari 3.x and Firefox 3.x.  The 'destroy' operation acts recursively to ensure that all the memory held by a given Component forest is freed for garbage collection.  

The recursive pattern followed by the Component tree gives unlimited capability to handle complexity.  The 'destroy' facility enables any number of Components to be successively created and destroyed, offering unlimited single-web-page functionality.

[A description of the major dimensioning characteristics of the software that impact the architecture, as well as the target performance constraints.]

11.             Quality

'ComponentManager' encapsulates all the details of managing a Component or set of Components, on behalf of the Component-owning object.  This simplifies and circumscribes the interface of Component creation and destruction.   

The system is kept simple by the one-to-one correspondance between a 'ComponentBuilder' object and a 'Component'.  It is further simplified by the separation of the ordered loading of lists of JavaScript includes from the actual JavaScript includes itself.  'Component' may be subclassed to any degree, providing complete flexibility in terms of what a Component can do.

[A description of how the software architecture contributes to all capabilities (other than functionality) of the system: extensibility, reliability, portability, and so on. If these characteristics have special significance, such as safety, security or privacy implications, they must be clearly delineated.]