COMP 529 - Software Architecture

Project

In accordance with its credit weight, this course requires students to complete a significant project. The project will involve the architectural recovery of large and complex open source systems and the comparison of their architecture according to important architectural properties (e.g., extensibility, reliability, performance).

Specifically, a team of two or three students will select large and complex open source systems that address a common set of requirements using a different approach. Each student in the team must work on one system.

The project is worth 45% of the final grade, but a mark of 50% for the project is required to pass the course, irrespective of the total final mark. Although one report per team must be submitted for each milestone, a portion of the mark is individual.

Milestones

  1. Create a build tutorial.
  2. Description of the system’s architecture.
  3. Comparison of the systems’ architecture.
  4. Final presentation.
  5. Final report.

Submission Policy: All deadlines are firm. This is to ensure fairness, a speedy feedback, and consistency with the course schedule. Please plan ahead. If you are not done by the deadline, submit your partial solution. The WebCT submission site allows you to submit early and to resubmit. To avoid the usual issues with last-minute submissions, you are encouraged to submit early. After a small grace period the webCT system will block submissions. Milestones not submitted on time are subject to a significant penalty (Immediate penalty of 20% of total possible mark, with an additional penalty of 4% of total possible mark per hour (e.g., a submission 2hrs late on work marked out of 100 receives -28 marks).

Criteria to select a system

  • Systems must be open source.
  • Systems must have more than 50 000 non-commented, non-blank lines of code. You can use ohloh to quickly assess the number of lines of code of a system.
  • Systems must have a non-trivial feature set.
  • The systems must not be built on the same backend (a simple common library is ok though).
  • Simple frontends are not acceptable (e.g., a large fraction of the interesting code in the Arora browser comes from WebKit.).
  • The systems must have a similar feature set (e.g., vector-based is not the same as pixel-based).
  • Frameworks and libraries are not acceptable. (e.g., django, jquery, hibernate, spring, etc.).
  • Platforms and product lines are ok as long as only one application is compared in detail.
  • Web applications are not acceptable (unless you can convince us that it’s interesting and as complex as the examples noted below)

System Examples

These systems are given as examples only. You must ensure that they meet the criteria above, especially the number of lines of code and the absence of a significant backend. Teams of three must find a relevant third system. Teams of two may select an alternative system as long as it meets the criteria (e.g., git vs. bazaar instead of git vs. mercurial).

  • Apache vs. nginx
  • OpenOffice vs. KOffice (writer applications, spreadsheets)
  • git vs. mercurial
  • firefox vs. chrome
  • eclipse vs. netbeans (the IDE, not the platform)
  • vim vs. emacs
  • thunderbird vs. evolution (or other complete email client)
  • gimp vs. cinepaint (or krita, or any pixel-based drawing application)
  • songbird vs. amarok (or banshee or rythmbox)
  • pidgin vs. kopete
  • gnucash vs. kmymoney
  • kate vs. gedit
  • mysql vs. postgresql
  • evince vs. okular
  • ArgoUML vs. Dia (diagram editor)
  • Umbrello UML Modeller vs. AndroMDA (modeling and code generation)

Milestone 0 - Team and Systems Selection

Deadline: January 14th @ 11:30 AM

Send one email per team to the instructor and the TA. The subject of the email should be: “COMP 529 Milestone 0”. The email should first give a list of the students in the team (full name and mcgill id).

The email should then provide three lists of systems that would be analyzed by the students in order of preference. Each “list” should include the name of the systems, the url of the systems, and the name of the student who would study the systems (one student per system). If the system is a product line, please specify which application you will study in detail. The systems will be attributed on a first-come, first-served basis.

If the systems were not in the system examples list, the email should describe the set of core requirements that are fulfilled by the systems.

Evaluation: Failure to complete the milestone on time will result in a penalty of one point deduced from the total project mark.

Milestone 1 - Build Tutorial

Deadline: January 21st @ 11:30 AM

Submit one report per team. The report will contain a maximum of four pages (six pages if you work on three systems) with a maximum of two pages per system. The text body font size must be 11 pt and the margins must be at least 0.75 inch. Commands that must be entered on the command line must be in monospace font (e.g., Courier New), and user interface pointers must be in bold. For example, click on the menu File | New.

For each system, describe the system in a paragraph (what it does, the main features, the number of lines of code, the number of contributors or downloads if available, the main programming languages used in the system, etc.).

Then, write a step-by-step tutorial to (1) download the source code and the dependencies of the system, (2) compile the system, (3) run the main test suite, and (4) run the system.

The tutorial will contain the following subsections:

  • Prerequisites: software that you assume the reader already has (operating system minimal version, jdk, compiler like gcc, system libraries, etc.). It is a good idea to include a link for less-known prerequisistes.
  • Source Code and Dependencies: steps required to download the source code and the dependencies. This could be a cvs or git command to download the latest source code, a series of step to download a zip file and unzip it, etc. If there are many dependencies that must be individually downloaded, a link to an online list is enough (as long as the process to install these dependencies is explained in the tutorial). Otherwise, you can include an annex containing the links of the dependencies. The annex does not count toward the page limit.
  • Compilation: steps required to compile the system.
  • Test: steps required to execute the main test suite of the system.
  • Run: steps required to run the system.

The goal of this milestone is to ensure that you can download and execute the source code of the systems you will be analyzing. You will probably need to debug your system to understand how the various parts interact together so we want to ensure that all students can “play” with their systems.

Advice

I regularly compile new systems and it sometimes takes many attempts before I succeed (undocumented dependencies or flags, etc) and it can take many hours to compile a large system on my speedy computer (forget it on your netbook). You may even have to post on the system’s mailing list. The bottom line is: don’t do this 24 hours before the deadline.

Evaluation: 5%

The following criteria will be used to evaluate the report:

  • Completeness (Individual, 2 pts) Are the instructions complete or are there steps missing?
  • Quality (Individual, 2 pts) Are the instructions easy to follow, clear, and without typos?
  • Cohesion (Team, 1 pt) Is the report cohesive: is the same font/spacing used, are the writing styles similar?

Milestone 2 - System Architecture

Deadline: February 14th @ 11:30 AM

Submit one report per team. The report will contain a maximum of 10 pages and a minimum of 8 pages per system. Please consult the report guidelines for information about the format.

The report will contain the following common sections:

  • Introduction: present the family of systems you are analyzing, their domain, what features they have in common, how they differ on the surface (e.g., programming language, audience, age, size). Max: 1 page. The page does not count toward the total number of pages for each system.

Each system will be presented using these sections:

  • Overview: provide an overview of the system that your friends who are not studying computer science could understand. Present the main features of the system (especially if they differ from the other system), how the code is organized (e.g., the main folders in the repository, the main packages, naming convention, folder patterns) and how it relates to the features. You can draw a diagram if it helps.

  • Module View: provide at least one significant module view of the system using a diagram. Describe the role of each module, how it is represented in the code (e.g., by a package), how it relates to the other modules. If it is only a partial view of the system, mention what is not displayed. You can display a second view if you have the space, but make sure that your first view is well documented and explained. You can use lists or tables to complement your diagram. The view should contain at least five modules.

  • C&C View: provide one significant C&C view of the system using a diagram. Describe the relationship between this view and the module view, clearly indicate the type of each connector (e.g., using a legend, in the text, etc.). Explain at least the control flow or the dataflow of a common scenario (e.g., with a sequence diagram, with a list of steps, etc.). If your C&C view does not represent the whole system, mention what is not displayed. Mention any architectural styles that you encountered while recovering the system’s architecture. Describe how your C&C view relates to your module view: the two views do not need to be closely related and they can be about different parts of the systems. The view should contain at least five components.

  • Connectors: For each connector in the previous C&C view, indicate how they are implemented in the code. For example, name the classes or the methods that are called and which classes or methods are making these calls. Some connectors will be easy to describe because they are implemented in a clean interface (e.g., a Facade), while some connectors are abstracting a set of scattered method calls. In the latter case, you do not need to name each method call, but you need to indicate the main methods. If there are more than 10 connectors, document only the 10 most important ones.

    Hint: Numbering the connectors in the C&C view will help tremendously!

  • Allocation View: provide one allocation view of the system using a diagram. If the system’s allocation is simple (e.g., it can be represented as one program running on a machine), present a scenario where the system interacts with its environment (e.g., auto-update, accessing a server or being accessed by a client, etc.). Clearly indicate the type of relationships in the diagram, the role of each components, and why you selected this particular view. Describe how your allocation view relates to your two other views.

  • Conclusion: informally evaluate the quality of the system’s architecture and implementation. Max 1/2 page.

Evaluation: 20%

Each section will be evaluated according to the following criteria:

  • Completeness: Are the main artifacts and relationships presented in each section? Is the level of granularity right?
  • Correctness: Are the diagrams and the text precise? Are the architectural terms used appropriately? Are the artifacts and relationships represented accurately?
  • Quality: Are the diagrams and the text easy to follow, clear, and logically structured?

Each section will weight:

  • Intro: 1 pt (common)
  • Overview: 1 pt (individual)
  • Module View: 5 pt (individual)
  • C&C View: 4 pt (individual)
  • Connectors: 5 pt (individual)
  • Allocation View: 3 pt (individual)
  • Conclusion: 1 pt (individual)

Hint: Although the intro and the overview are only worth 1/20 each, they will impact our general understanding of the other sections.

Milestone 3 - Architecture Comparison

Deadline: March 14th @ 11:30 AM

In this report, you will compare three aspects of your systems’ architecture. By aspect, we mean feature implementation or non-functional requirements (e.g., extensibility, maintainability, security). The three aspects do not need to be of the same granularity or of the same nature, but we require that one aspect be fine-grained (e.g., a low-level feature). Submit one report per team. The report will contain a maximum of 12 pages and a minimum of 10 pages (min 13, max 16 for teams with three systems). Please consult the report guidelines for information about the format.

The report will contain the following sections:

  • Introduction: present the systems briefly and mention the three aspects of their architecture that will be compared. Max: 1 page. The page does not count toward the total number of pages.

Each aspect will then be presented using these subsections.

  • Aspect Overview: describe the aspect being studied, why it was selected, and how it differs across the systems.
  • Diagram and Description: draw one diagram of the aspect for each system. Make sure to show not just how the aspect is implemented, but also how it integrates with the architecture. Use the same viewtype for all diagrams in this subsection. Describe each diagram separately. You can draw more than one diagram per system if necessary.
  • Comparison: compare the systems from the point of view of this aspect. For example, you can describe the different trade-offs each system is making, you can compare the connector types and the architectural styles, you can compare how the general architecture made this aspect easy (or difficult) to implement, etc. Indicate which system has a better architecture from the perspective of this aspect and justify your choice. Make sure that this subsection refers to material seen in class. This is the most important subsection.

At the end of the entire report:

  • Conclusion Write a conclusion (max 1 page). Summarize the differences between the systems (from the perspective of your three aspecs). Indicate which system has the best architecture according to these three aspects and justify your decision.

Evaluation: 30%

Each section will be evaluated according to the following criteria:

Completeness: Are the main artifacts and relationships presented in each section?

Correctness: Are the diagrams and the text precise? Are the architectural terms used appropriately? Are the artifacts and relationships represented accurately?

Quality: Are the diagrams and the text easy to follow, clear, and logically structured?

Each section will weight:

  • Intro: 2 pts
  • Aspects: 8 pts per aspect (6 pts individual, 2 pts for the group)
  • Conclusion: 4 pts

Individual grade will be awarded for the aspect section.

Milestone 4 - Presentation

Prepare a 20-minute talk (25 minutes for 3-person teams and 15 minutes for 1-person team) about your project (one talk per project). Your talk should address these points:

  • Introduction: present the family of systems you are analyzing. Give some interesting facts such as LOC, programming languages, age, etc.
  • Architecture Overview: briefly present one view of the invariants in your system. Briefly describe the differences in the implementation of these invariants.
  • Aspect 1: Compare one aspect of your systems based on your milestone 3 report.
  • Aspect 2: Compare a second aspect of your systems based on your milestone 3 report.
  • Conclusion.

You won’t have enough time to cover all the details of your systems’ architecture: it is highly preferable to focus on a few aspects than to go quickly over many aspects. Rehearse at least once together and twice alone.

Not all team members need to present, but all team members must be in the class (e.g., to answer the questions). For example, one teammate can do the powerpoint slides with all the diagrams and the other can do the presentation.

Evaluation: 25%

  • Completeness: Are the main features, components, relationships, and differences presented in the talk. Is the level of granularity right?
  • Correctness: Are the diagrams and the presentation precise? Are the architectural terms used appropriately? Are the artifacts and relationships represented accurately?
  • Quality: Are the diagrams and the presentation easy to follow, clear, and logically structured? Is it a rehearsed talk or a bad off-the-cuff dud.

Your peers (50%), the TA (25%) and the instructor (25%) will evaluate you. There will be four points out of 25 (one point per presentation day) awarded for your presence in class.

Milestone 5 - Reference Architecture

Deadline: April 11th @ 11:30 AM

In this report, you will describe a reference architecture of the form invariants plus variation points for the family of systems you studied. First, find at least five invariants and three variation points in your systems. Then, describe the invariants and the variation points using three viewtypes (module, components and connectors, allocation). For each viewtype, identify the invariants and variation points, and indicate how each system fulfill (or not) these invariants and variation points. Submit one report per team. The report will contain a maximum of 12 pages and a minimum of 10 pages (min 13, max 16 for teams with three systems). Please consult the report guidelines for information about the format.

It is perfectly fine to start from your milestone 2 report and make it more general. Make sure that you take into account all the comments from the TA to improve your report. You will not be able to document the entire reference architecture in 12 pages for such complex systems, so we expect you to present only the most significant parts.

The report will contain the following common sections:

  • Introduction: present the family of systems you are analyzing, their domain, what features they have in common, how they differ on the surface (e.g., programming language, audience, age, size). covered. Max: 1 page. The page does not count toward the total number of pages.

  • Domain Model Overview: Present an overview of the reference architecture’s domain model: glossary of most important terms, main objects, main features, main interactions. You do not need to draw any diagram in this section (but you can if it helps). Make sure to indicate the scope of your reference architecture and the level of granularity. For example, do you assume that all the systems built using that reference architecture will use the same programming language, is there a particular feature not covered at all by your reference architecture. Max: 2 pages.

  • Module View: provide at least one significant module view of the reference architecture using a diagram. Describe the role of each module, how it relates to the other modules. If it is only a partial view of the reference architecture, mention what is not displayed. You can display a second view if you have the space, but make sure that your first view is well documented and explained. You can use lists or tables to complement your diagram. All the invariants and the variation points of your reference architecture should be presented in this section, even if they do not appear in the view (but really, they should!).

  • C&C View: provide at least one significant C&C view of the reference architecture using a diagram. Describe the relationship between this view and the module view, clearly indicate the type of each connector (e.g., using a legend, in the text, etc.). If the type of the connectors can vary, mention what types can be used. Explain at least the control flow or the dataflow of a common scenario (e.g., with a sequence diagram, with a list of steps, etc.). If your C&C view does not represent the whole reference architecture, mention what is not displayed. Mention any architectural styles in your reference architecture. The C&C view does not need to be closely related to the module view and they can be about different parts of the reference architecture. The view should contain at least five components.

    Hint: Numbering the connectors in the C&C view will help tremendously!

  • Allocation View: provide one allocation view of the reference architecture using a deployment diagram. If the reference architecture’s allocation is simple (e.g., it can be represented as one program running on a machine), present a scenario where the system interacts with its environment (e.g., auto-update, accessing a server or being accessed by a client, etc.). Clearly indicate the type of relationships in the diagram, the role of each components, and why you selected this particular view. Describe how your allocation view relates to your two other views.

  • Conclusion: summarize your reference architecture in 1/2 page.

Evaluation: 20% (one grade per team)

Each section will be evaluated according to the following criteria:

  • Completeness: Are the main artifacts and relationships presented in each section? Is the level of granularity right?
  • Correctness: Are the diagrams and the text precise? Are the architectural terms used appropriately? Are the artifacts and relationships represented accurately?
  • Quality: Are the diagrams and the text easy to follow, clear, and logically structured?

Each section will weight:

  • Intro: 1 pt
  • Domain Model: 4 pts
  • Module View: 5 pts
  • C&C View: 6 pts
  • Allocation View: 3 pts
  • Conclusion: 1 pt