[2022] Queensland - CSSE6400 Software Architecture - Assessment - Documenting an Architecture
Documenting an Architecture Software Architecture
Semester 1, 2022
Summary
In this assignment, you will demonstrate your ability to understand and subsequently communicate the architecture of an existing software project.
1. First, you need to choose a suitable open source software project. The project must have non-trivial
functionality and architecture.
2. You will write a report which describes the architecture of your selected software project.
1 Introduction
The digital world relies heavily on open source software, as seen by the recent log4j vulnerability.1 Fortunately, open source developers often maintain high quality documentation for the users of their projects. Unfortunately however, many open source projects do not maintain the same high quality documentation for the architecture of their software projects. This can cause difficulty for developers who want to contribute to the project, but first need to understand it.
In this assignment, you have the chance to right this wrong. Your task is to find an open source software project with a sufficiently complex architecture and document it. You may optionally choose to share this documentation with the project developers. You are encouraged to do this, as the perspective of a newcomer to a project is often invaluable to the seasoned developers.
Before looking for projects, read some of the architecture documentation written by students at TU Delft: https://delftswa.gitbooks.io/desosa2016/content and https://delftswa.github.io.
It would also be advantageous to read through one of the architecture descriptions in either volume of The Architecture of Open Source Applications: http://aosabook.org.
2 Finding a Project
Criteria for the software project:
• The project cannot be covered in the tutorials or by the TU Delft students above.
• The project must have at least one release within the last year.
• The project must be an executable system or library with a significant software structure. (e.g. A CSS
library is not executable nor does it have a significant software structure.)
Places to look for projects:
• GitHub explore page: https://github.com/explore;
• Apache project list: https://apache.org/index.html#projects-list;
• Awesome Open Source https://awesomeopensource.com/;
• in class discussion with other students;
• or, ask your tutor.
3 Report Structure
Title Name of the software project.
Abstract Summarise the key points of your document.
Introduction Describe the software project, explaining its key functionality and target users.
ASRs Describe the project’s architecturally significant requirements.
Context Provide an overview of the software system’s context and its external dependencies.
Architecture Describe the software’s architecture in detail.
Critique Evaluate the software’s architecture, describing its advantages and disadvantages.
Conclusion Highlight the key points or lessons learnt about the software’s architecture.
4 Report Content
How you present the information in your report, is up to you. You need to select an appropriate notation to provide a visual representation of the software’s architecture. You need to select appropriate ways of describing the architecture.
The “Architectural Views” notes [1] describe different types of views that can be used to describe aspects of a software architecture. The notes also describe two different notations that can be used to describe parts of a software architecture. You need to decide which views are appropriate to provide an accurate, informative, and complete description of the project’s architecture. The notation you use to provide visual information about the architecture must convey that information appropriately. Your textual commentary needs to expand on the information provided in the diagrams.
The introduction section of your report must include a link to the project’s main repository (e.g. Ruby on Rails Repo2) and, if useful, any other important sites related to the project (e.g. Ruby on Rails3). The introduction should provide enough information so that a reader who is not familiar with the project can understand what it delivers.
You need to identify what you think are the project’s architecturally significant requirements (ASRs) and, in particular, the quality attributes that are important to the project’s success. You need to justify why these requirements are important. You should consider how these attributes would be prioritised to make decisions when trade offs need to be made in the design. Your critique should describe how well the software’s architecture supports delivering the ASRs that you identified as being important.
The context should help the reader to understand who uses the system and its dependencies on other systems. It should elaborate on the general introduction of the system to provide a starting basis to understand the software system’s architecture.
Provide a detailed description of the software system’s architecture. It should cover all important aspects of the architecture. You should include diagrams to help the reader understand the details of the architecture. You should describe any security risks inherent in the software architecture. Your critique should evaluate and discuss what security design principles appear to have been followed in the design of the software and how well they guard against the security risks. Your critique should also assess the advantages and potential drawbacks of the architectural design.
You are not expected to get down to the level of describing the detailed design of the software. You should not need to provide class diagrams for the entire system. You may need to provide class diagrams to highlight important features supported by the architecture. For example, a class diagram showing a plug-in API, and how the application uses a plug-in, would be informative.
You may use tools to generate diagrams and to extract information from source code that is used to create diagrams or other documentation artefacts.
The audience of your report is software developers who are familiar with software architecture and design. You may assume that the reader is familiar with UML and C4 notations.
5 Presentation
The presentation assessment task scheduled later in the semester will be based on the project you select for this assignment. In the presentation you will provide
