Software Architecture


Due: Friday, Apr 24, 2015, 11:00pm

Slides due: Monday, Apr 27, 2015, 12:00am

Contents:

You have already worked to define a system you will deliver by the end of the quarter. The purpose of this next team assignment is to accomplish the detailed architectural design and phased product delivery plan for your system, before you implement your ideas in code. A common name for this document is a System Design Specification (SDS), although in our case, we are augmenting the design with planning components. Among other things, your SDS should answer the questions: what are your modules (packages, classes, or other units of abstraction), what are the responsibilities of each module, and how do the modules interact/collaborate?

Note that the SDS will be a living document. You will update it periodically during the development cycle. As part of developing the SDS, you may need to revise your SRS. Keeping these documents up to date with changes as they happen will make it easier to keep your team and customers in sync, and to meet your later deliverables.

After you complete your SDS, you will present it to your customers (during class), convincing them that:

Thus, there are two deliverables, with two different deadlines: a document and slides for a presentation. Both document and the slides should be in PDF format.

In evaluating your work, we will be looking to see that you have addressed all the necessary elements of an architecture, covered well the planning material described above, and made reasonable decisions related to all project components.


Document to be submitted

Your document should include an architecture section and a process section.

System Architecture

The System Architecture document provides a detailed definition of the system’s software components. It identifies the major modules and their functionality, and the interfaces between modules, required to implement the system. It should address the design of the system from the customer's viewpoint, as well as that of the developer or administrator. (This may require separate perspectives and/or diagrams.)

Describe, in detail, what data your system stores, and how. If it uses a database, give the high level database schema. If not, describe how you are storing the data and its organization.

For two design decisions for which you seriously considered an alternative, briefly describe that alternative. Discuss its pros and cons and why you chose the design you did.

If there are particular assumptions in your design, identify them.

You (and more especially your readers!) may find it useful to first create a customer view of the system (at a high level of abstraction) and/or a UML class/dependence diagram of the modules of the system.

Diagrams

For full points, the architecture section must include at least two views of the system architecture, with one view being a UML class diagram. You also must include two UML sequence diagrams outlining two of the use cases from your SRS.

The software tools section of the project webpage lists some tools you can use for drawing UML diagrams.

Class diagrams

The UML class diagram must include all major classes and enough detail to both answer questions about the design, and to let design be critiqued.

Your diagram should display all major classes, attributes (fields), methods (do not list get/set/is methods), inheritance/interface relationships, and associational relationships (named and directed, with multiplicity annotations).

If you are listing classes in your class diagram, take care not to forget important classes that would reasonably be needed to solve the task you are working on. Do not forget to include classes for all aspects of your system, such as user interface, data modeling, database interaction, any “helper” classes or utility code, etc. In the past, some groups have focused too much on user interface classes and have done a poor job capturing the details of the “model” of your system, the classes that actually represent the important data and behavior necessary for the task.

Sequence diagrams

The UML sequence diagrams should depict your product executing two of its important use cases. These can be the same use cases you wrote about in your requirements document (SRS). The sequence diagrams show the “life” of a user's interaction with the system (e.g., web request). Your diagram should show all participants (objects) in the sequence, all important directed messages between them, and their return values (if any). Show the request's path as it interacts with each part of your system to accomplish the task. Take care not to omit important steps or details. Make sure that the state of the system at the end of the path through the diagram matches the expectations from the use case to which it relates.

Accompanying one or both of the sequence diagrams should be a pseudo-code description of the same algorithm.

Use good design with decentralized control. Choose a flow of control that is reasonable for your type of project and the goal being achieved in the scenario. Ideally no one class or object should do too large a share of the work to complete the scenario.

Design tips

Your design should use the design principles discussed in this class and prior ones. Here are some general design tips, which essentially come down to “put functionality in a logical place”.

Process

The process section of your document should address 6 topics, described below.

Risk assessment

Identify the top five risks to successful completion of your project. For each, give:

Explicitly state how this has changed since the SRS.

When deciding which 5 risks to include, you can informally multiply the likelihood by the impact to determine the importance of a given risk. You should pay attention to risks in proportion to their importance. Don't belabor low-likelihood, low-impact risks.

Project Schedule

Identify milestones (external and internal), define tasks along with effort estimates (at granularity no coarser than 1-person-week units), and identify dependences among them. (What has to be complete before you can begin implementing component X? What has to be complete before you can start testing component X? What has to be complete before you can run an entire (small) use case?) This should reflect your actual plan of work, possibly including items your team has already completed. Consult your SRS Feature List for input.

To build a schedule, start with your major milestones (tend to be noun-like) and fill in the tasks (tend to start with a verb) that will allow you to achieve them. A simple table or spreadsheet is fine for this size of a project.

Team structure

Describe your team structure (how you have organized the team, what are members' roles and responsibilities), elaborate on milestones (external and internal), define tasks, and specify the team member responsible for each task. This should reflect your actual plan of work, including items your team may have already completed. You may find yourself revisiting your organization during the lifecycle of the project. Describe the way your team will communicate, for example: date/time of weekly meeting, location of weekly status reports, wiki, email alias.

Test plan

Describe what aspects you plan to test and why they are sufficient, as well as how specifically you plan to test those aspects in a disciplined way. Discuss unit test, system (integration) test, and usability test strategy, along with any specific test suites identified to capture the requirements (SRS). Identify the mechanism that you will use to track bugs that occur during use and testing. (For a large project, use of a specialized bug tracking tool is critical. For this project, we do not require it, but we strongly recommend it. Whatever you use must be kept up to date and visible to the course staff.)

We will not have covered this material in class by the time the SDS is due. Do your best and plan to revisit this section during a later phase of the lifecycle. Below is a sample structure for the section.

Documentation Plan

Define the documentation that you plan to deliver with the system, e.g., user guides, admin guides, man pages, help menus.

Coding style guidelines

For each programming language that you will use in the implementation of your project, provide a link to a pre-existing coding style guideline that the members of your project will follow. Do not try to make up your own guidelines.

Briefly state how you plan to enforce these guidelines.


Requirements and architecture presentation

Submit slides in PDF format for a 10-minute presentation that convinces your customer that you are on track for successful delivery of a worthwhile project. Each 10-minute presentation will be followed by a 5-minute Q&A session with the audience.

Your presentation should summarize the requirements (the project's purpose, what is novel about it, its UI and major features), its architectural design, and your planning for the implementation. You can't give all details about any of these; focus on what is most interesting, novel, risky, etc. 8-10 slides are typically appropriate for a 10-minute presentation, but you may use as many or as few as you think will be effective.

A good presentation will contain more slides with a diagram than without. Diagrams can be taken directly from your other documents, if appropriate, but you may find that the different format requires different drawings in some cases.

Exactly 3 group members must participate in the presentation. Different members will participate in future presentations. Don't go over 9-10 minutes; it is better to leave more time for questions than to fill your slot and deny the audience the chance to better understand your work.


Hints

Hints for the document and presentation

Be brief! We have listed quite a few types of information that is useful. However, many of these items can be concisely addressed. The point of a document is to convey information, and the longer your document is, the less chance someone has of reading the document and/or finding the information they want in it. (Also, your TA will thank you for being brief.)

Do not include content-free filler in your documents or presentations. This includes anything that could appear in identical form in another group's materials. For example, don't merely state as a risk, “we might fall behind schedule” (another example is “we don't know the tools”). Of course you might—so might anyone. What factors do you think are most likely to cause schedule slippage for your project? Why do you think those are the parts of the schedule with the greatest potential variance? What have you done, or what do you plan to do, to learn more about how long those particular tasks will really take?

When you create a class diagram, put every class into a module. For example, if you are using the Model-View-Controller architecture, then your class diagram should also reflect this. Create three regions in your class diagram (use colors or bigger boxes that contain the classes, and put each class in the relevant port of your class diagram).

Hints for the presentation

See Michael Ernst's hints on giving a technical presentation, and the hints for the proposal presentation.

Remind the audience of your goal, and especially of differentiating factors that make your project better than existing approaches to the problem.

Any description of your project, its goals, and what it does must include a picture (possibly multiple pictures) of its UI. When discussing the UI picture, don't just enumerate the components to the audience. Rather, discuss how a user performs some task using the UI.

There is no need to give a list of 20 development milestones. It's more important, especially in a talk where time (and audience attention) are limited, to focus on larger blocks. But even a list of 6 tasks (with dates) is not very interesting. It's more important to show the dependences among them, to make clear that the schedule is achievable. Your schedule must contain concrete deliverables; it is useless to just repeat the class due dates without saying what you plan to do at each step.

Do not present a sequence diagram, class diagram, or any other material just because it is there. Rather, ask yourself whether this is important and what key point it is bringing across. For example, it might indicate some key feature of your design, or how the parts of your system work together. The point is not to give a long list of procedure names, but to develop insight that would let someone else generate that list.

Class diagrams presented in a talk should usually be simpler than those in a document. For example, you don't have time to go over all the procedure names, so you should elide them unless there is a compelling reason otherwise. Your diagrams must not use unreadably small writing. Be willing to redraw your diagrams for the presentation.

Practice the presentation before you turn it in.

Presentation pitfalls to avoid

Here are some issues that previous students have had trouble with in their presentations. Most are already covered in the hints elsewhere, but they bear repeating.

Choose details carefully
Don't have too much text; the text will compete for attention with your spiel.
Don't have too many diagrams, and integrate them with your spiel.
Four features is a good number, either to explain your overall product or a library you have chosen; more than that will overwhelm rather than illuminating the audience.
The purpose of the slides is to help both the speaker and the audience.
Don't just tell what. Also tell why.
This was a particular problem with UML diagrams, but also in general. Here are some ways you could explain why a particular choice was made:
  • Alternatives, and why you rejected them.
  • Consequences of changing the choice.
  • For a library: what features does it provide that you will take advantage of? What alternatives are available?
  • What was difficult? What was unexpected? You know this is interesting, because it's something you didn't expect yourself. This can also explain why some other design was not chosen.
Schedule
Again, tell why, not just what: why did you order the tasks in the way that you did?
The schedule should not just a list programming tasks. It is a project schedule and should indicate all important events, including when you plan to get feedback from your customer.
Feedback/testing
We don't want to hear that you are using JUnit, or black box and white box tests. Think at a higher level; this is about testing your project, not just your program. In particular, what feedback do you plan to get, in what order, and how? And, why did you make those choices?
Risks
You have a twofold goal in this presentation: to inform the audience, and to get feedback from the audience. You will achieve both goals by admitting your difficulties. You won't fool anyone (especially the course staff) by trying to be perfect, and hiding information will cause you to receive less feedback.