Deliverable 2: Concrete Architecture and Beta Release

Software Architecture and Design (Fall 2003)

Last Modified: October 20th 2003

Submission Details

The following items must be submitted electronically on or before November 7^th using the 'submit' command:

Formal architecture document (pdf file)
Code (all source files, installation and startup scripts, tests, etc.)
Unit test document
Installation guide

Formal Architecture Document

What is an Architecture Document for?

The purpose of document is to provide a concrete description of the components of your system's architecture. In addition, the Implementation Plan gives you an idea of how long the project will take and how to distribute development tasks to each of your team members.

While writing this document keep in mind that the intended audience for this document is management and the development team. Do not make your report longer than necessary; shorter reports that contain appropriate information are preferred. Your report should not be longer than 40 pages, including all diagrams and appendices. Your document should be clear, concise and useful. For example, organize your report so it is easy navigate to information that you may need later, e.g. Process View Diagrams.

Tips:

To verify the clarity of your document, proofread it. -- It's like testing your code before you submit it.
To improve the conciseness and clarity, not to mention quality, revise your document. -- It's like optimizing your code.

What do we mean by 'Formal'?

You are to write a formal document, not a working paper. It is our intent to allow you to develop your formal writing skills and style. The Markers will be primarily focused on the content of your documents, but a substantial amount of marks have been explicitly allocated for things like clarity, presentation, style, etc. This is in addition to the marks allocated for the Abstract, Introduction, References, etc. Also, since this is not a working paper and the intended audience includes management you will be severely penalized for submitting an unprofessional document. As a rule of thumb, unprofessional means that your company could not show your document to a client. Bottom line, do not forget to run spell check, make sure all diagrams appear properly in your submission, etc.

Document Structure and Content

Title Page

Title -- About 3 to 6 words making clear what your report is about.
Author -- Your names, email addresses, student ids, group number, etc.
Date -- The date of the most recent change to the document
Abstract -- About 1/3 to1/2 of a page, single-spaced, presenting a summary of the key points in your report and any important conclusions, targeted at knowledgeable manager

List of Figures

1.0 Introduction

Describe the purpose of the document and its indented audience. Include any assumptions that you are making about the audience (e.g. Knowledge of Java, Familiarity with IP Telephony, etc.).

1.1 Document Conventions

Describe or define any new terminology or special conventions that you use in the document. For example, any nicknames or abbreviations used to refer to elements of your system must be defined here. Diagrammatic Conventions can either be described in this section or in the header of the section where they are used.

1.2 Overview

The purpose of this section is to outline the structure of your document and briefly describe the content of all major sections. To this end you should provide a 1-2 sentence description of each section of the document. For example,

The following section contains a description of the ___, ___, and ___ components of the system architecture. This includes ___. Section 5 discusses the proposed Implementation Plan in terms of ___, ___ and ___.…There are 2 Appendices. The first contains …

Whether you chose to include references to specific section numbers as part of your overview is a matter of writing style.

2.0 System Architecture (Development And Process Views)

Include a Development View diagram of the entire system. That is, a diagram showing the relationships between the major components of your system. The term component usually refers to a subsystem or a module, but can also refer to a process, a file, or a database.

Provide a description of each component in your system including the component's responsibilities (What it does) and a component-specific Process View diagram with description (How it works).

Important Notes:

You must describe all components of the system, not just those you are implementing for this deliverable.
Depending on your architecture, you may need to defer some design decisions and leave some parts under-designed.
Make sure any uncommon abbreviations or notation you use is described (Students often forget to do this).

3.0 Inter-component Interfaces (formerly called External Interfaces)

Thoroughly describe all Inter-Component Interfaces. That is,

For message-based interfaces (e.g. binary or text-based), provide examples of each type of message and a description of proper message syntax (e.g. a schema, a grammar, etc.)
For programmatic interfaces, provide a documented list of all exposed objects, methods, functions, variables, etc.
For database interfaces, provide a database schema (if you haven't already done so in the previous section) and include the source (e.g. SQL or XQuery) for all queries you intend to use

Having a thorough description of the inter-component interfaces will help your group members code in isolation. That is, component developers can write their code against a predetermined set of thoroughly described interfaces. This helps to speed up the development process.

Notes:

You may find it more natural to describe the interfaces exposed by a component as part of the description of that component. Feel free to do so.
Components are the boxes in your Development View Diagram and Inter-Component Interfaces are the lines between the boxes.

4.0 Off-the-shelf Components

Those of you who indent to use off-the-shelf components or frameworks must provide a brief description of these products including a thorough description of why you have decided to use them. A few paragraphs for each product including a link to more information should suffice.

5.0 Architectural Scenarios

To help you debug your architecture and to demonstrate the proposed operation of your system include several well-chosen architectural scenarios.

6.0 Implementation Plan (Code View)

6.1 File Organization

Provide a folder hierarchy diagram, which depicts the organization of your source files. Provide a brief explanation or justification of the structure you have selected.

Explain the build process. For example, for C++, is there a makefile in each directory? For Java, how is package compilation handled?

For each component in your development view list all of the files that implement that component. Do this using a Diagram or a Table. If a file corresponds to more than one component then you must express this information in a useful way. If you prefer, you may instead do this for each process and thread in your Process Views.

6.2 Development Plan

List of all development tasks needed to get the system from its current state to a complete state. For each task include:

A description of the task or a descriptive task name;
The task's type. That is, 'testing', 'write new code', 'modify existing code', 'integrate components', etc;
An estimate of the lines of code and time to complete. Whenever possible you should use Function Points or CoCoMo to calculate your estimates;
Any components or inter-component interfaces that the task corresponds to (Their may not be one or their may be more than one);
The name of the group member assigned to complete this task.

The assignment of group members should be based on a critical path analysis using Pert and Gantt charts. Perform this analysis and include the Task Dependency diagram, and the Pert and Gantt charts. Make sure to highlight the critical path on both charts. Incorporate the fact that some tasks need to be completed by one deadline (the Deadline for this deliverable) while other tasks don’t need to be completed until some time later (the deadline for the next deliverable). Ask a TA, or the Professor, if you are not sure how to do this.

7.0 Glossary

Include a glossary that briefly defines all the key terms used in your architecture, giving when appropriate, the "type" of the item being explained. The Glossary differs from the Document Conventions section in that a glossary contains all the technical terms that you use in your document (e.g. TCP/IP, XML, Component, etc.). Meanwhile, Document Conventions contains only the terms that either you invented or that are crucial to the understanding of the document.

8.0 References

List any publications (documents, websites, etc.) that you refer to in your document. You should also list documents that a reader might want to read in conjunction with yours.

Implementation Requirements for Beta Release

For the Beta release of your system you will implement the essential elements of your system. In addition to the requirements specified in the previous deliverable, the beta release of your system must implement the following:

Account Management

Create an account
Change customer/account information
Assign multiple subscriptions to an account/customer
A customer can choose their phone number -- If it is available then assign it to them. If it is not available return an error
A customer can also choose which phone they want
Cancel subscription
Suspend subscription -- Release assigned phone but not the phone number
Reactivate subscription -- Attempt to allocate a phone, if successful then mark the subscription as active. Otherwise, return an error
Change the permissions associated with a subscription (i.e. Send Calls, Receive Calls)
List all accounts. Include the dialled numbers associated with each account

Phone Management

Add new phone to system: add an phone record to the database
Remove phone from system: remove phone record from database. If a customer owns the phone then do something intelligent and justify your decision somewhere in your documents.
Reset of phone's call processing (see project introduction document for details)

All of the operations listed above are to be performed through a Graphical User Interface (GUI).

For more specifications on these requirements refer to your SRS or the original project documentation. If these requirements contradict your SRS consult your TA or the Professor.

Integration Tests

You will implement a set of automated integration tests, which demonstrate the correctness of the code you have written. Integration tests are basically unit tests done at a Component level (i.e. the Unit is a Component). To implement these tests you may use a common unit testing framework such as JUnit or CppUnit. Your integration tests should cover the set of functionality exposed by each component of your system. However, you need only provide tests for the components and functionality that is required in this deliverable or in the previous deliverable.

Update your Unit Testing Working Paper in light of the additional tests.

Installation Guide

Write an installation script. This script can assume that an instance of MySQL is available. The script will login to the database, create any tables that you need and load them with the necessary data. The script may accept arguments but should have default values for all of these arguments.

You will also write scripts to properly start the various components of your system. These scripts may accept arguments (e.g. port numbers), but once the user specifies a value they will not need to specify it again. For example, once a user specifies the port for your database, they will do not need to specify that port when starting the server or the phone processes. Tip: You can do this using system variables or by programmatically modifying your startup scripts.

All scripts should have a '-h' option which outputs help (usage) information.

The startup scripts for your phone process must have an option, '-e', which automatically starts a phone emulator (using the given IP and port). The phone process will then connect to the emulator instead of connecting to a real phone. There are two emulators available. The first was written by a TA the second was written by students. They are both written in Java and have similar functionality. These emulators will allow you to test your system without needing to use an actually IP Phone. Moreover, they can be run on any machine so you do not need to be in the lab to use them (i.e. you can develop at home). The emulators can be found in the following locations:

      /u/cs446/VoIP/public/FakeInterface/*    (written by a TA)
      /u/cs446/VoIP/public/ipphoneclient.zip  (written by students)

Your startup script needs to support one emulator or the other, it does not need to support both.

Update your Installation Guide in light of the changes to your system (including the addition of installation and startup scripts).