Course Manual

1 Prerequisites

To participate, you must be know material from the following courses:

• Modelleren en Systeemontwikkeling (MSO), because UML is frequently used as a description language for architectures.
• Imperatief Programmeren (IMP), Functioneel Programmeren (FP), because code inspection occasionally is required, and design patterns are expressed using program fragments.
• Internet Programming (INP), Computerarchitectuur en netwerken (NW), because we delve into actual systems.

It will be advantageous to already have followed Software Engineering (SWE), Advanced Functional Programming (AFP).

2 Software Architecture

The main purpose of an architecture for software is to be able to reason about software before actually building it. An architecture describes a system in such a way that insight can be achieved and decisions can be made about its feasibility, feature trade-offs, and realisation. Usually a software architecture for a system acts as the intermediary between client, implementer, and other involved stakeholders, in order to reach to an agreement about the functionality of a system. A software architecture touches upon many aspects, all of which must be part of the skill set of a software architect:

• Requirements engineering. Allthough a client knows what is desired of a system, this usually is too vague to be usable for a precise description necessary for reasoning about a system. Requirements therefore must be elicited (extracted) from a client and described.
• Functional requirements. A system does something, it performs a function, a job. Functional requirements describe the 'what must be done' by a system.
• Non-functional requirements, software quality, global invariant. What a system does, may be described by describing its functionality, but this does not say how good this must be done, what the quality of it is. For example, a website allows browsing (functionality), but it may take hours before its content is displayed (quality). Upholding a particular quality requirement is equivalent to maintaining a global invariant, that is, guaranteeing that some property always holds.
• System structure and design. A design of a system concerns the highlevel structure of a system, without touching upon the actual implementation. A design must fullfill both functional and quality requirements, and must be implementable. History has shown which designs fullfill which functional and quality requirements; many are known as architecture and design patterns.
• Architecture assessment. After the construction of a software architecture, (1) does the architecture indeed describe what it must describe, and (2) does it solve the problem posed by the involved stakeholders, that is, does it fullfill the requirements and will it work?
• People skills. An architecture has a pivotal role in the construction of a system involving many people: client, implementer, manager, etc. In practice, dealing with those involved people and the associated social and political agendas may consume more effort than the effort required for the technical part.

In an architecture for a system, quality (global invariants), functional requirements, and design are jointly described with the sole purpose of proving that the design fullfills requirements. Additional design level organisation, patterns, invariants, and other restrictions must be specified as to find out how a design indeed can fullfill requirements. Trade-offs and uncombinable solutions ideally should be detected as part of making of an architecture. For example, the combination of a distributed database and immediate update visibility of those databases after a change via a user interface is likely to be impossible because distribution implies communications, which in turn implies delays.

3 Purpose and overall structure of this course

This course focusses on a subset of the much larger skill set of a software architect. In particular, this course intends to prepare you for dealing with the most likely question you will get as a technical expert from a hypothetical client: ``can you implement feature X in system Y?''. The immediate answer might be ``yes'' because you just have learned how to do this. The software architect however would consider the consequence of combinding X with feature Z of the system Y: Z might break, or Z may perform worse, or it might be too costly to also modify Z for interacting correctly with X. Such considerations are made when architecting a system, and set the role of architecting apart from the role of (only) designing, implementing, and coding.

The focus of this course therefore lies on the relationship between requirements -in particular quality requirements-, system structure and design, the trade-offs (or impossible feature combinations). Said differently, the purpose of this course is give better insight in how technical solutions chosen in a system contribute to desired behavior, and how and when choices have to be made between desirable features. In this course this insight is offered by looking at existing systems and how they accomplish their expected job.

The overall structure of the course is as follows:

• Schedule. First some introductory lectures and a reading assignment, followed by a project, wrapped up by reviewing other projects. After the initial lectures each week there are presentations, reading assignments, paper writing, and reviewing. Not all weeks there will be meetings.
• Reading assignments. There are two reading assignments: (1) to get familiar with the concepts and nomenclature of SWA, (2) to understand better the various systems looked at during the course.
• Projects. Projects consist of exploring a particular system, focussing on the mentioned relationship between technicalities and quality requirements. The focus of project presentations and the paper description of the architecture of a system is on (1) which quality requirements are fullfilled using which techniques, (2) what the trade-offs of the system are.
• Project review. Findings of each project are reviewed and verified by reviews by other project teams, their results submitted in paper form and presentation.

4 Concrete structure of this course

4.1 Project teams

Projects are done by teams, each consisting of 3-4 participants. A team investigates a particular system of their choice, presents its findings both on paper and via presentation, and reviews the findings of another team, those findings also to be presented on paper and by presentation. The individual contribution of team members must be clearly indicated, as judgement will be based both on the effort and results of the team as a whole as well is individual member contribution. A team will first be judged as a team, and then on a per individual basis.

4.2 Reading assignments

There are two reading assignments, each serving a different purpose during the course, to be done individually:

• Architecture background info. The first reading assignment intends to provide background information, mostly for later use during the course. The assignment is to read the material and come up with at least one question for each read paper, to be answered by yourself as well. For each paper both question and answer are submitted as part of the reading assignment. The question is not supposed to be like ``why is this comma missing?'', but like ``it seems the author has ignored this or that problem'', subsequently answered by finding a possible solution, pointing out work by others, etc. The intent of this assignment format is to really make you read the paper, question it, understand both its value and limitations, etc etc. In addition extra papers have to be searched and chosen by yourself.
• Widening system knowledge. The second reading assignment intends to provide more knowledge about the range of systems dealt with during the course. Each project team provides one paper (reference, URL, ...) which describes best the problem a particular system solves, and how it accomplishes that. Again you come up with a question, this time not be answered by yourselves but by the team looking at the system corresponding to the read paper. The answer is incorporated into the architectural description of the system, which can be relatively short (considering the number of participants). The intent of this assignment format is to (1) help project teams to be more critical towards their system, (2) learn more about more systems, (3) make the presentations more lively, (4) prepare you for reviewing.

4.3 Deliverables

Individual participants are expected to do and be judged by the following:

• Reading assignment 1. The 1st reading assignment consists of reading papers and submitting feedback on the papers, in the form described below.
  • Read a choice of 10 papers from the background reading material. Submit a question + answer (as described above), using a couple of paragraphs of text per question.
  • Choose and read 2 papers not from the list (or same literature page), but searched and found by yourself, of which you think that they should have been included in the SWA literature, either replacing another paper, or as an additional paper. Submit a brief description of the reason why you think your choice is the right one.
• Reading assignment 2. Read each paper as provided by a team, and as above pose a question, this time to be submitted to each team.
• Presence and participation. Each participant is expected to be present at every meeting, lecture, presentation, unless circumstances beyond one's control make this impossible. Active participation is expected: think, doubt, ask questions, be critical in a constructive way.

Teams are expected to do and be judged by the following:

• System investigation. Each team reports their findings of investigating a system by means of a presentation and a paper:
  • size: approx. 10 pages x teamsize, in normal A4 + letter format, excluding table of contents, frontpage, etc.
  • submission format: PDF only, submitted via email to the teacher.
  • architectural content: an architecture description + comparison with 2 other systems; see below.
  • paper question answering: an answer for each question, indicating from who the question came. The answer may be very brief, like 'see page X', as the questions are supposed to help steer the system exploration. If not answered as part of the architectural content, a more extensive answer must be given.
• Review of system investigation. Each team reviews the work of another team, summarizing the review in a presentation.
• Presentations. Depending on the total number of participants and teams, there will be approx. 20 mins per team per presentation and time for discussion, depending on the particular topic. In principle this takes 3-4 hours, but the schedule allows for overflow to subsequent slots, so there is time for dealing with technicalities when necessary. Each team gives presentations on (see also the schedule):
  • System technical overview
  • Chosen quality aspects, use cases, suspected trade-offs, alternate systems
  • System architectural review, by chosen quality aspects and use cases, that is, the oral variant of the written system investigation to be submitted in the same timeframe.
  • Review of peer team architectural descriptions Each team member is expected to at least give (part of) one presentation. The presentations are submitted as well.

4.4 Paper content: how to organize your findings

4.4.1 `Ideal' architecture document

Ideally, an architecture document contains the requirements (functional and non-functional) of a system, its realization at a sufficiently detailed level, and a rationale (a 'proof') that its realization fullfills the requirements. For a new system a minimal structure could be as follows:

• A description of the architecture, structured according to the IEEEP1471 framework. In this framework the interests of stakeholders are explicitly described by means of viewpoints/views. For the case study of this course at least the viewpoints from the "4+1" model have to be used, with UML as the language for expressing the models.
  • logical view. Use (e.g.) class + sequence diagrams.
  • process view. Use (e.g.) component + sequence + state diagrams.
  • physical view. Use (e.g.) deployment diagrams.
  • development view. Use (e.g.) component diagrams.
  • 'scenario view': illustrate the concepts in the other views by discussing a scenario (i.e. 1 particular use case walkthrough) and how it relates to these other views. This is a (informal and/or argumented) proof (or rationale) that the chosen architecture will be able to realise the use cases (this is the +1 from the 4+1).
• Usually more viewpoints than the previous `standard' ones are considered. Such a viewpoint corresponds to a particular interest of a stakeholder and as such is an answer to a specific concern of this stakeholder. For example, the cost or security of the system.
• A (informal and/or argumented) proof (or rationale) that the chosen architecture indeed can be implemented. Here the connection is made with technology, that is, existing software/systems, previous implementations and experience, etc. in the form of literature study, usage of systems, prototyping, etc. Because alternatives exist, show which alternatives have which effect on the quality aspects (e.g. by using an impact matrix), which alternative is the 'best' and how this can be validated and measured. This is the place where the confrontation between a client's wish and technological feasibility takes place.
• A proposition for the realisation of the system, which includes expected costs, planning and estimated required resources (personel, equipment, ...).

4.4.2 Architecture document for this course

For this course we look at existing systems with the intent of retrieving, or reverse engineering, the original architectural description. Because of the size and structure of this course, this can only be done partially, so a slice is to be be taken from the hypothetical complete description. This slice corresponds to a particular trade-off, which itself is a combination of quality requirements which cannot all be satisfied at the same time. This conflict is observed via use cases, which themselves correspond to specific paths of control through the system. The architectural description therefore should describe these ingredients, using as much as necessary from the above `ideal' description format. Furthermore:

• It should be of sufficient detail to be able to pinpoint where in the system trading between conflicting quality requirements of a trade-off is done. It also should be of sufficient detail such that subsequent reviewing can explore alternate use cases to find out how resistent the structure of the system is to use beyond its original intended use.
• The technical discussion should be based on available documentation and -if necessary- source code, but should be expressed in terms of architecture and design patterns.

An additional part of the architecture document is the inclusion of and comparison to other similar systems: a system does not exists just on its own, but frequently has predecessors and/or coexists with variants. Find 2 similar systems, a predecessor (if possible) and a variant. If no predecessor exists, find 2 variants. The investigated system should be compared on quality aspects guaranteed, underlying technical realisation, and alternate ways of dealing with the chose trade-off.

In summary, the paper should describe:

• A system, an overview of what is does, quality aspects addressed by the system, a trade-off between such aspects, the realisation and technical aspects of the implementation of these aspects and the pinpointing where the trade-off is dealt with.
• A comparison with 2 other systems, to be chosen freely.

4.5 Review paper content

Reviews should be done by using change impact analysis and risk analysis, of which the first should be emphasized. In general, change impact analysis attempts to find out the impact of a change on some artefact X to another artefact Y, especially important for (software) maintenance. Here the focus is on requirements, that is, what parts of an architecture description are influenced when requirements (and/or use case) change. If an architecture caters for a small change this would be 'good'; if an architecture needs to be re-architected this would be 'bad'. A risk analysis would find such 'bad' spots.

The review should describe an evaluation of the architecture description of a colleague team by, ideally including the following:

• Finding and describing a requirements (+ use case) change which only would cause a small change in the architecture. I.e. find what the system also can do without much additional re-architecting.
• Finding and describing a requirements (+ use case) change which only would cause the architecture to fall apart. I.e. find what the system should sensibly be able to do, but only can be accomplished with much additional re-architecting.
• Observing whether the above questions can be answered by the architecture description. Point out what is missing. This coincides with the clarity and preciseness judgement criterium below.

Again, the above is limited by what is given in the architecture document. It may be necessary to delve into material not included in the architecture document.

4.6 Judgement

As mentioned, judgement will be based on the above deliverables as well as the following criteria:

• Clarity and preciseness. Trade-offs and other issues need to be pinpointed with as much as technical detail, without resorting to more vague remarks.

For all assignments a non-trivial submission must be made, if not this automatically means that the course cannot be passed. If non-trivial submissions are made and this still results in an insufficient mark, there will be an opportunity to do additional work, to be determined on an individual basis.

4.7 Grading

Grading is done on the basis of assignments, with the following weights:

• Reading assignments: 0.2
• Architectural description paper: 0.4
• Architectural description review: 0.2
• Presentations and presence: 0.2

5 Submission

Submission format. The submission format for all submittable material is PDF, that is, don't use proprietary formats. Submissions are to be sent to the teacher by email, including in the subject header the text [SWA-submission], combined with (1) a choice from [Reading1], [ArchitectureDocument], [ArchitecturePresentation], or [ReviewPresentation] depending on the submission, and (2) your identity, a choice from [Your Name] or [Your Team]. For example, if you are named Foo Bar then submit your first reading assignment with subject [SWA-submission][Reading1][Foo Bar]. If you omit this it is more likely that your email gets lost, or will be administered incorrectly.

Submission time. Each deadline date may be interpreted as "the submission must be in the mailbox of the teacher at 8:00 of the first working day after the deadline".

-- AtzeDijkstra - 14 Apr 2010