Prof Ric Holt, Department of Computer Science,
CONSTRAINTS
For this version of the course, the following constraints are imposed by the management:
GOAL
You are to produce a (web-readable) report that documents the architecture of the software that you propose to develop for your proposed system. Your target audience for reports and documents is a manager or developer who is somewhat but not intimately familiar with your project.
REPORT
You report should include the following:
Title: About 3 to 6 words making clear what your report is about.
Authors: List of authors, their addresses, date, etc.
Abstract: About 2/3 of a page overviewing the key points in your report, targeted to a manager or developer.
Introduction and Overview: About 1 to 3 pages summarizing the purpose of report, its organization, and its salient conclusions. A person should be able to read just the abstract or just the introduction and have a good idea what is in the rest of your report.
Architecture: Give the overall structure of the system that you are proposing to implement, with descriptions of each major component and of the interactions among them. These components are to be primarily packages, subsystems or modules, but also include threads or processes (as in Unix processes), files, and data bases. In your descriptions, concentrate on goals, requirements, evolvability, testability, etc., rather than on lower level concepts such as classes, variables and control flow. However, you should clarify global control flow, such as units of concurrency and method of passing control from one component to another.
Your system's architecture should be easy to understand, with simple interfaces, and modest interactions among packages, subsystems and modules.
Architectural style. Clarify what style of architecture (in the sense of Garlan and Shaw) that you are proposing.
Level of detail. You are not to concentrate on minor components, such as classes and procedures, which are smaller than packages or modules. However, you may wish to discuss important abstractions, patterns, classes, data structures or algorithms that are critical to the successful implementation of your architecture.
Diagrams. You should use diagrams that clearly illustrate the structure of your system. You may choose to use various kinds of UML diagrams. Do not give diagrams that are too low level, eg, do not give diagrams of details within objects, nor within modules. You can use tools such to help you draw diagrams, but this is not required. Do not include diagrams that are difficult to read.
External Interfaces: List information transmitted to/from the system, such as by Graphical User Interfaces, files, data bases, messages or networks. Do not give details such as menus, but rather concentrate on information content. Although the information to be stored in a database should be specified, the form of this data need not be given.
Use Cases: Give a small number of essential Use Cases that illustrate the use of the your system. Show or explain how each Use Case activates or uses the various major parts of your proposed architecture.
Data Dictionary: Include a glossary that briefly defines the key terms used in your architecture, giving when appropriate, the "type" (such as a class, module, algorithm, subsystem, etc.) of the item being explained.
Naming Conventions: List any naming conventions used in your architecture. Explain any abbreviations that you use.
Test Plan: Briefly describe how you plan on testing your system. (Perhaps a page.)
Methodology and Cost: Give a plan for how the system is to be implemented, (what modules and subsystems in what order, by whom and how to do unit testing), with estimates of number of lines in each module and number of person hours to both implement and unit test each module. (You are to record this same information during your development, to compare with these estimates.) (Roughly a page or two.)
Performance: Discuss any parts of the system that are likely to be performance critical, i.e., which might not run fast enough. (Perhaps a quarter page.)
Evolvability: Discuss how your architecture is designed to support future changes in the your system. (Perhaps a page.)
Feasibility Studies: Investigate and report on the feasibility of key or risky parts of your system. You may wish to do small prototypes investigating the use of these. (Perhaps one or two pages.)
References: List any documents that your reader may wish to or need to read in conjunction with your report. Since the report is to be web readable, include links to references when appropriate.
DOCUMENT STYLE AND LENGTH
Do not make your report longer than necessary. In general, shorter reports that contain appropriate information are preferred. Your report must not be longer than 20 pages (in the hard copy version), including all diagrams and appendices.
Write clearly. Organize your report so it is easy to find things in it.
FUTURE ASSIGNMENTS
Future reports are to be interlinked with an updated version of this software architecture report.
Revised 30 June 2009 RCH