Informatics 117: Project in Software System Design

Spring Quarter 2010

Architecture and Module Specifications

Due Date

May 11, 2010.

Overview

Develop a design that fully satisfies the requirements for your application. This deliverable consists of two elements: a design specification (consisting of an architecture and module specifications) and an integration test plan. NOTE: contents of this deliverable may vary from the description below, depending on the project. View the description below as normative, but if it does not "fit" your project, talk to me about how you believe the deliverable should be changed.

Your document must specify the correspondence between the requirements elements and your design. You may show this correspondence any way you feel is appropriate (e.g., make notations throughout your document or using a table that cross-references paragraph numbers).

Developing the software design will undoubtedly reveal inadequacies in previous documents. Please note these problems and what was done to resolve them.

Don't forget to include your meeting minutes and performance appraisals with your document; refer to the syllabus for the complete check-list of what has to be turned in. As before, make sure that you post your design documents and your meeting minutes to your team web page.

Deliverable Objectives/Quality

Keep in mind that key objectives of a design document may include:

Develop a coherent representation of software that will satisfy the requirements
Identify inadequacies in requirements
Decompose the system into sub-systems that provide related sets of services
Establish a framework for sub-system control and communication
Specify modules that can be assigned as coding responsibilities
Document design decisions and rationale
Provide a reference tool readable by developers, testers, and maintainers
Provide a basis for integration and testing

In addition, keep in mind that a design document should exhibit the following qualities:

Complete: everything that is essential is described
Unambiguous: expressed in a well-defined notation
Consistent: no mismatched interfaces
Modifiable: this document will change just like all the others
Confirmable/testable: you can tell when you've met the design

Document Contents

Introduction

Expand your previous introduction to discuss your specific approaches to the design of the system and the organization of this document. This description is essentially just an updated version of the introduction you included in your previous deliverable.

Understanding

Expand the understanding section of your previous document. Include brief descriptions of actions you took to understand each technology studied during this phase. If you make changes to this section, add text describing why the change was necessary, and why it more accurately reflects your new understanding. This section need not be different if your understanding hasn't changed.

Project Plan

This will be an iterative expansion of your previous submission. Update your project plan to show what you have accomplished so far. Reassess the project risks as necessary. Expand your task network or work breakdown structure to include the effort expended to complete this task, as necessary. Based on the work you have done, revise your estimates on how much your team can accomplish and deliver.

If you make changes, add text describing why the change was necessary or why it will improve the ability of your team to accomplish the work you have proposed.

Design Specification

Architecture Overview

Architectural Style
What style of architecture did you adopt? Provide a reference to a defining document.
System Architecture Overview
This is the place for your "one great diagram" that shows how your system is built. You might want to use more than one diagram, to show, e.g., some different abstractions of the design (such as a data flow view, a layers of abstraction view, an object view, or an OS process view) – multiple diagrams are fine.
Subsystem Narrative
What each subsystem means
Major limitations on the current design (if any)

Modules/Objects Specification (Note: for some projects this section should be re-oriented towards describing what things you reused, or plan to reuse, and how they integrate with each other and the rest of your system. This will be discussed in class.)

List of Modules/Objects/Scripts/Programs within your system
For each module/object, provide a Specification

Name
Definition/Purpose - what it is/does
Narrative/Comment - how it works
What are the interfaces or APIs?
Data - What state does it keep (if any)?
Access - Who has access to the module/object/data?
Requires – What modules does this module depend upon?
Constraints - what constraints are there for this object/module? (e.g. must start first, must be registered with ..., must ....)
anything else necessary to fully describe the module

Diagrams you could consider using in providing this specification: UML class diagrams, event sequence (trace) charts, state transition diagrams, package diagrams, ...

Integration Test Plan

A test plan capable of demonstrating that the design meets the requirements. Test cases should cover each module/object interaction specified. The test cases can be grouped with the design entity to which they apply, otherwise a cross reference listing of some sort should be provided.

For each test

Test ID
Purpose of Test
Item(s) being tested
Input specification
Output specification

Expected Results or Test Oracle Mechanism

Test environmental needs or special test procedures

Initial Demonstration Plan

What and how will you demonstrate?

Tracking and Control Mechanisms

Configuration Management: how will your modules/objects be managed?

SVN? CVS?
file structure, sub-directories, Makefiles, etc.
where is your persistent data going to live?

Requirements Cross Reference: what modules/objects satisfy what requirements?

a table mapping requirement to module/object

Modifications to Prior Documents

Requirements

If any requirements changed make them explicit. Highlight why the requirement was changed/added/deleted and by whom (customer, developer, etc.). If your requirements have not changed, then so state.

Glossary

Define any "irregular" terms used in the specifications above. This portion of the document may be written as an extension to the glossary submitted with the requirements, or may be a separate document that only defines terms local to the design activity.

Additional Documentation

This section is reserved for any additional documentation developed during this phase of the project. Specifically, if during the course of developing the architecture your understanding of the various technologies involved in the project changed, or you discovered items that were not documented but which are important, include that information here. Also list here the major background sources that you used during this phase or any that you plan to use during the remainder of the project. This includes references to similar systems and/or procedures.

Design Presentations.

See the syllabus for dates. Each team should prepare a 15 minute Powerpoint (or equivalent) presentation.

Your presentation should include the following:

Some context for your project (very brief!);
Current state of your project plan and comparison to the previous version of the plan;
Highlights of your design including

an overview of your architecture (this should comprise the bulk of your presentation) – the "one great diagram"
one or more key module/object specifications;

[As needed] Modifications to your requirements that arose as a result of your design process;
Overview of your integration test plan.