CISC 498 Information Technology Project
School of Computing		Internal Design Document

Overview

The purpose of a system's internal design document is to communicate to implementers how the system should be built. The internal design document should specify the system's architecture, deployment information, algorithms of note, special plans for addressing noteworthy quality requirements, and programming tools to be used.

Internal design is iterative; plan to revise and rethink aspects of your design as you work through implementation, and as you continue to work with your customer to refine your understanding of the system's requirements.

The contents of an internal design document are influenced by the kind of software being developed. A simple web application will typically have a less stringent level of document than that of a safety-critical system such as control code for a nuclear reactor or software controlling brakes in a car. You may adapt the following template as necessary to suit the software you are developing.

Structure

Your external design document should be about 20 pages in length, and should contain the following sections:

Introduction	Remind the reader of the goals of your system, and give an overview of the structure and contents of the internal design document.
Programming environment	Detail the programming tools and languages that you will use to create the system. Specify, for example, your IDE, programming language(s), compilers (and versions), database system, source control system, UML tool, etc.
Software architecture	This will most likely be the largest section of the document. See details below.
Data design	If your system may interact with persistent data, for example, input/output files or a database, specify the format of this data. Useful ways of specifying your data might include BNF specification of data files, XML Schema specification of XML formats, and ER diagrams and relational schemas for databases.
API design	If your system provides an API to application programmers, provide a clear and detailed specification of the API.
Algorithms	Specify any complex algorithms used in your system. If the algorithm is standard, provide a reference to where the reader can learn about it. If the algorithm is non-standard, provide pseudo-code or other appropriate description.
Notable tradeoffs	You may have had to make design tradeoffs to meet the system's quality requirements (e.g., related to availability, security, performance, etc.) Discuss these tradeoffs, with specific reference to your system's design as discussed in the above sections.
Notable risks	Discuss any areas where you potentially risk failing to meet the system's requirements. Relate these risks to specific aspects of the internal design. Specify how you plan to address and ameliorate these risks.
Milestones	Update the milestones from your project plan to cover the weeks from Nov. 18, 2008 to Feb 24, 2009, your system presentation.

Note in the above that different systems will place more or less emphasis on different parts. Some systems will provide no API, therefore will require no API specification. Other systems will have no complex algorithms to discuss. Other systems may have little or no persistent data. Adapt this structure to best suit your application.

Software Architecture

The description of your software architecture will consist of:

• Component and deployment view. This should identify the major components of the system, show how they are allocated to nodes, and establish the architecture's subsystem structure. I suggest using the "calls-perspective" notation from CISC 322, based on UML component and deployment diagrams.
• Class-based view. If appropriate, show the object-oriented design of parts of the system, using UML class diagrams and package views.
• Identify architectural styles and design patterns you have chosen to employ.
• Specify the interfaces of key components, specifying for each operation in the interface its input/output parameters, pre/post-conditions and exceptions.
• For all of the above, provide sufficient English-language text to explain your design.

In general, the goal of the architectural description is to be sufficiently detailed, precise and clear that a design team can use the document as the basis for implementation.