This page specifies the content of the architectural design document, which presents details of the overall architecture of the software system. The goal of this is to specify the system components and their interrelationships. The design is done using both text and graphics to provide a system block diagram. It is, nevertheless, only a preliminary-level design. The document should provide enough detail so that a new programming team that did not participate in this preliminary design could begin detailed design and coding. However, the Architectural Design should not include any details of implementation, such as variable names. For this reason, even though the diagrams will be executed in UML, the class diagrams will not need class fields or method names; only the class names need to be shown in the block diagrams.
If desired, some of the operations and processes may be shown, using UML sequence or activity diagrams. In these, it isn't necessary to show message names or data structure details.
The document should be structured as follows (sections are explained below):
6.0 Architectural Design Document
6.1. Introduction
6.1.1 System Objectives
6.1.2 Hardware, Software, and Human Interfaces
6.2. CSCI Descriptions
6.2.1 Concept of Execution
6.2.2 Interface Design
6.2.2.1 Interface Identification and Diagrams
6.2.2.2 Project Interactions
6.3. Preliminary User Manual
The introduction is intended to introduce the reader to the product that is being designed. Since this is a repeat of information in previous sections, only a high-level description of the project is needed here. Keep in mind that for your project, this is another section in the project notebook, so a full introduction would be redundant. However, since this section is a representation of a full-up architectural design, the introduction must be there. In the industry version it would be a full introduction that would specify the system (again!) and would provide a scope and focus for the document. For you, all you need is the document focus part, something like "This document presents the architecture for the software for the GompusWompus project. The project performs <blah blah>."
Briefly recap the goals and scope of this project. Another semi-redundant section which is there to mimic the industry standard. Try to focus on the architecture in the text of this section, rather than just making it a copy and paste from another section.
Identify all hardware, software and human interfaces. These interfaces should have been identified in the requirements document as external interfaces. This section should also provide some details about how they interrelate to the base system. For example, you will list the keyboard and the mouse under human interfaces. You will list specifics of the networking under hardware, including such things as whether hard-wired or wireless networking will be the primary connections. Software items would include whether the server is threaded or not, or if a socket interface is used as opposed to an ONC-RPC interface.
This section is intended to start focusing on the CSCI components, from an architectural view of the system. You should put in details for each component of the CSCI, including what CSCs there are, and the roles and responsibilities of each in the overall system. This is where you actually start designing the system, so it is OK to put in implementation ideas. You're still at a high level of abstraction, but you are past the "description-only" phase, so you can put in some of the "how" that was only hinted at in the SRS. Don't try to design the final details of the system (like the fields and methods for every Java class, for example), but do try to identify the classes, and what the responsibilities of each of them are. This section is a good place to make use of CRC cards to figure out what the CSUs are and what they will do.
The architectural design of a software system is one of the most critical aspects of a
successful system. A good design generally takes considerable foresight and a lot of trial
and error.
The architectural design is the first step towards an implementation. The requirements specification has previously identified the functions that the customer requires. The architectural design suggests an implementation of those functions. This does not mean that the architectural design will simply be a module for each of the functions described in the requirements specification.
One of the most important characteristics of a good designer is that she be able to spot awkwardness in a design, meaning you must look at the design and attempt to figure out if it works from the perspective of, "Now if I had to implement this module, could I do it reasonably?" In general, as you refine the system architecture, you are looking for problems in the design such as, "I need to compute the sine of X, but I haven't been told X and I can't find it out at this point in the processing flow of the program." Another common problem in design is a lack of independence between the modules (known as "coupling"). Strongly coupled entities can cause a great deal of confusion on a group project.
This major subsystems section should present the overall design of the system. Partition the system into logical sets of class definitions by CSU. These classes should based on their overall functionality within the entire system. For example, for a game program, you might want to decompose the system into a State Control subsystem, a User Interface Control system, and Computer Player.
The goal here is to give some conceptual organization to the set of class descriptions that are to follow in the next segment, i.e., the detailed design contained in the Software Design Description (SDD) document.
In the business, the Architecture Design Description (yes, I know that's "ADD") and the Detailed Design Description are often combined into one document, known as the Software Design Description. However, even though there is only one document, it frequently contains much more detail than the two smaller versions you will produce for this project. So, even though it seems like there is more work in writing two documents, you're actually getting off easy. . . (smiley face!)
This section is the place to document the way you forsee the system will work. It is where to put USE CASES, both the diagrammatic representation, and the text versions. Your work in this section is to document all the things the system will do. There are at least a bejillion different references on the UML diagrams for this, as well as the textual versions; the first place to look, of course, is in the textbooks for this class. This is another time when your CRC cards will come in handy. Have a meeting (actually a bunch of meetings) and walk all the way through an operational scenario. For an example, consider an ATM transaction. There are definite steps to that process, which are discrete and (because everyone is familiar with them) are well-known. You could even "role-play" a scenario, having different members of the team play different actors in the process. Whatever your choice, the idea is to determine what the use cases are and how they work. The "nitty-gritty" details of these (e.g., the full class diagrams, state diagrams, activity diagrams, and so on) will go into the detailed design, but the use case information will go here. An additional UML diagram for this section is a Component diagram, or even a Deployment diagram — these will show how the different CSCs relate and the environments that each requires. The section is not entirely UML, though; you'll still need to write some text to explain things fully. Make sure you reference the diagrams by Figure number, as you've seen in textbooks and other material you've read.
Remember: The diagrams in this document will not necessarily reflect the level of detail that is talked about in the text!!
This is an introduction to the section, and simply states what it is for as a lead-in to the sections which follow.
Section 6.2.2.1 is a short section which identifies all interfaces used in the project. This does not mean interfaces in the Java sense; rather, it is interfaces between parts or segments of the project, as well as interfaces between actors in the use cases. It can be fairly short and simple, even just a table showing the name of each and its description.
Similarly, the interactions section is intended to describe all the interactions between the project segments. This is the section in which more details of interactions between the parts described in the previous section of the document will be spelled out. For example, how does the graphics engine get data from the physics engine when there is a calculation update? How does the game state get notified that a player has won? When does the buffered object for the display get updated and shown to the user? How is the user checked against the database to be sure only valid users have access, from the standpoint of the database store and the database server? These are the types of items on which to focus for interactions.
In this section you will write the preliminary user's manual for the project. It will become the complete user's manual by the end of the project, but at this point, you will use what has been decided upon in discussing and defined in the previous sections to detail how the user will work the system. This should be written from the user's point of view. Picture what you remember from the last software you bought that came with a manual (if you actually read it!) and you'll get the idea. The user's manual covers all facets of program operation, all menu items and their sub-menus, all buttons and their functions, starting and stopping the program, installation, de-installation, help topics, possible error messages, and so on. Ask someone for a copy of a typical manual from some commercial application and look through it to get an idea of what is expected.
An initial draft of the user manual will be part of your Architectural Design deliverable. The user manual will be a living document, and you will continue to revise and enhance it during the term. At the end of the term it should be able to exist as a standalone document in electronic form, to be stored in the directory containing the executable of your system. (See the following description of the Final submission for further details.)
The final version of this section should aim to be a professional-quality document, which will be very much like reading any documentation you get with professionally produced software. For example, when you buy Quicken, you get a manual that tells you in great detail (and in language that non-computer people can understand) the following items:
These are the kinds of things that a good user's manual will contain. The intent is to provide the user with something on the order of a "software semi-expert" looking over the user's shoulder during the learning period. The more you put in (in an intelligent and intuitive manner, of course) the better the user experience will be.
Entries in the project SDF table of contents should be generated for the Architectural Design document. These entries should match the section titles listed above and in the table of contents at the bottom of the Course Overview page.
An example of the level of detail for this document can be found on this page, which is something I have culled from past experience.