IN4315: Software Architecture


Team Formation

As software architecture is all about collaboration and communication, the work must be done in teams:

  1. Required team size is 4
  2. Aim for diversity in your team. For example, aim at at a mixture of Embedded Systems / Software Technology / Data Science / Policy & Management expertise, different cultures, countries, etc.
  3. Form your group in Brightspace. Go to “Groups”.

If you are looking for partners, you can post a message on our Brightspace forum (there is a topic for partners wanted), and offer your expertise.

Getting Access to GitLab for Writing

All team members will get access to a shared GitLab repository hosting the sources of the DESOSA 2020 book.

Within this repository, each team will have one dedicated project sub-folder to work in. Teams should only add changes to their own sub-folder.

All documents are to be written in markdown, maintained under git in your GitLab repository. Follow all good software development practices in this repository, such as using issues and milestones for planning, merge requests, review, etc. Show that you are well-organized, and that the teachers can clearly see what you did and what you are planning to do.

You are encouraged to use issues and pull requests, properly labeling them with an identifier for your project.

Picking a Project

In principle you are free to pick any open source project on GitHub. Take the following factors into account:

You can check these constraints by using GHTorrent data on BigQuery. An active project will have 1 or more pull requests per day. To get you started, we hand-picked a list of projects which are large, actively developed, maintained by a vibrant community, and are not analyzed in the previous runs of this course.

To claim a project: Post on the Brightspace forum, title Claiming project P, explain why you like this project in the issue, and indicate the 4 team members that will work on this project as well as your group number. Make sure to add their GitLab accounts in the issue so we can find them.

Individual Journals

You will have considerable freedom in this course. Nevertheless, a steady heartbeat is required, and you are accountable for how you spend your time.

An architect is always eager to learn more. In this course, you have 5 EC available for software architecture in 8 weeks, giving a minimum effort of 5 * 28 / 8 = 17.5 hours per week that you should spend on this course.

Grading will be also based on the progress you made compared to your initial knowledge and skill level, not just based on a preset end-goal.

To make this possible, it is important that you and your team provide insight in what you do each week. To that end:

  1. Create a folder journal in your project folder.
  2. In that folder, create four separate files for each team member
  3. Each team member individually reports his or her own weekly experiences and effort in the course. It is important to commit and push these reports regularly, and that you commit your own updates.

In the journal, you can offer a story of what you learned, what activities you participated in (lectures, meetings). All effort related to the course can be included, including routes taken that do not directly lead to text in your essays (e.g., projects considered when selecting your project). For each week, also include the number of hours you spent that week on the software architecture course.


Strong writing skills are an invaluable asset for an architect. To quote Dan Heller in his “Ten Principles for Growth as an Engineer”:

Crisp technical writing eases collaboration and greatly improves your ability to persuade, inform, and teach.

Therefore, we will use this course to train and improve our writing skills.

Each team will write four essays. Each essay should be around 1000-1500 1500-2000 words. After 1500 2000 words teachers (or any reader, in fact), reserve the right to stop reading, which may affect your grade. We’ll be counting words by running Markdown Word Count, developed by a former Software Architecture student, on your .md markdown files.

Your essays will be evaluated based on the following:

  1. The text is well-structured, with a clear goal, a natural breakdown in sections, and a compelling conclusion.
  2. Sentences, paragraphs, and sections are coherent. They naturally build upon each other and work towards a clear message.
  3. The arguments laid out are technically sound, and of adequate technical depth.
  4. The English writing is grammatically correct
  5. The text clearly references any sources it builds upon
  6. The essay is unique and recognizable in its voice and its way of approaching the topic
  7. The essay is independently readable
  8. The story-line is illustrated with meaningful and appealing images and infographics.

The intended audience for the essays consists of computer science students or software engineers, interested in learning about architectural aspects of your open source project.

A publicly visible blog is available through which teams can publish their essays. Different from previous years, we are publishing the essays throughout the course (and not just all at once after the course). We will use the blog to engage with and share our work with the open source community. Published essays (blog posts) will carry a CC BY-SA 4.0 license, allowing the open source projects to include the resulting posts in their own documentation. You can decide yourself which posts you want to make public by means of simple meta-data flag in your jekyll markdown document.

Essay 1: The Product Vision

The starting point for your architectural analysis is a description of the vision underlying your project and its future success. Aspects to take into account include:

  1. A concise, inspirational characterization of what the project aims to achieve
  2. A description of the end-user mental model that is central to the system
  3. A characterization of the key capabilities and properties the system should provide
  4. An analysis of the stakeholders involved in the project, and how the resulting system is beneficial to them
  5. A description of the current and future context in which the system operates
  6. A product roadmap, laying out the main future directions anticipated for the upcoming years

It may be the case that some of these aspects do not naturally match your open source system under investigation. In that case, say so explicitly, and explain why you think this is the case in your essay. Instead offer a deeper analysis of other relevant aspects.

Relevant literature for this essay includes

Essay 2: From Vision to Architecture

While the first essay focuses on the set of fundamental concepts or properties of the system in its environment, in the second you explore how these are realized through its architectural elements and relationships, and the principles of its design and evolution. Aspects to take into account include:

  1. A discussion of which architectural views are relevant to your system (taken, e.g., from Rozanski and Woods 2 or Kruchten 4)
  2. The main architectural style or patterns applied (if relevant), such as layering or model-view-controller architectures.
  3. An overview of the development view, covering the system decomposition and the main modules and their dependencies, as embodied in the source code.
  4. A run time view, indicating how components interact at run time to realize key scenarios, including typical run time dependencies
  5. A deployment view, explaining where and in what way processes are deployed, for example through cloud solutions.
  6. Non-functional properties, and how potential trade-offs between them have been resolved.

It may be the case that some of these aspects do not naturally match your open source system under investigation. In that case, say so explicitly, and explain why you think this is the case in your essay. Instead offer a deeper analysis of other relevant aspects.

Relevant literature for this essay includes

Essay 3: Quality and Technical Debt

With key aspects of the architecture described, the third essay focuses on means to safeguard the quality and architectural integrity of the underlying system. Aspects to take into account include:

  1. A description of the overall software quality process used in your system
  2. A summary of the key checks conducted in the system’s continuous integration processes, and the configurations tested.
  3. An assessment of the quality of the test processes and possibly test adequacy (coverage)
  4. A mapping of recent coding activity on key architectural components (are there “hotspots” in terms of coding activity)
  5. A mapping of the system’s roadmap (expected features) onto architectural components, and on the underlying code
  6. An assessment of the code quality and maintainability for example using the views offered by SIG. Most relevant is the quality of those components most likely affected by future change (conform the roadmap)
  7. An analysis of the importance of code quality, testing, and technical debt in the discussions about new features, as visible in documentation, (GitHub) issues, or (GitHub) pull requests.
  8. Refactoring suggestions as offered by, e.g., SIG or SonarQube.
  9. An assessment of technical debt (if any) present in the system.

Again, it may be the case that some of these aspects do not naturally match your open source system under investigation. Also, doing all of these well may not fit in a single essay. Select those aspects that are most relevant, and do a thorough analysis for them.

If you conduct measurements, you may find that certain numbers point at poor code quality. In such cases, offer an explanation why the code ended up like it is now, assess whether trade-offs have been made, and demonstrate leadership by offering constructive proposals how to resolve the problems you found.

Relevant pointers for this essay include:

Essay 4: Deepening your Analysis

Your team’s final essay serves to deepen your analyis, and can be on one of the following topics.

Essay 4.VAR: Variability Analysis

An analysis of the variability modeling, management and implementation mechanisms that are relevant to your system, based on the lecture by Xavier Devroey. The details of this essay are described separately.

Essay 4.COL: Collaboration Analysis

An analysis of the collaborative and social aspects of the system under study, based on the lecture by Ayushi Ratsogi.

To that end, assess the socio-technical congruence in the development effort of your system under study as follows:

  1. Study the paper on socio-technical congruence by Cataldo et al (ICSE 2008) 6
  2. Using your results from Essay 2, identify a number of components that are loosely coupled, and a number of compnents that are tightly coupled.
  3. Analyze the communication network of the developers, for example by analyzing which developers communicate with each other in pull requests, issues, or other channels.
  4. Contrast the two dependency networks, and assess their congruence in relation to Conway’s law.

Essay 4.SUS: Sustainability Analysis

Look into the change history of the project and find code changes that are related to green computing, based on the green software engineering lecture by Luís Cruz. Present and discuss the rationale behind those changes:

When discussing energy efficiency, critical thinking is key. Aspects to cover include:

Essay 4.OTH: Topic of choice

A topic of choice, specific to your project. This can be based on

If you pick this option, consult the teachers first with a short proposal (a few sentences) explaining what you’d like to investigate, and how this is relevant to your project.


Once you are ready to submit your essay, please follow the following steps:

  1. Open a merge request on GitLab, and make sure that your team members review your changes. If everything looks good and everyone approves, you can merge your MR.

    Important note: Your MR needs to be merged for it to be considered submitted.

  2. To prepare your essay for peer reviews, a PDF, containing only your new essay, needs to be created. This can be done in two ways:

    • Download PDF from GitLab

      For each build of the master branch, a collection of single-essay PDFs is created and made available as a job artifact. Go to the Project Overview on GitLab, press the download button, and select single-essays (see the screenshot below)

      Select single-essays from the GitLab master branch job artifacts

      Once you have downloaded the ZIP file, you can find your essay within the directory corresponding to your project.

      Note: Your MR needs to be merged (into master) before it becomes available here.

    • Generate PDF manually

      Assuming that you have a working docker setup, it is easy to generate a PDF manually. In order to create a single-essay PDF manually, run the following command:

      $ make dockeressaypdf

      This command will ask you for the relative location of your to-be-submitted essay. Enter the correct path, and press enter. You can now find your essay in the target/ directory as a PDF.

      Note: This make command was added later. Make sure you are up to date with the master branch if the command is not available.

  3. Submit your essay to, the peer evaluation system that we use. After logging in with your NetID, you can find the Software Architecture course under “Enrolled Courses”. On the course page, select the correct assignment (corresponding to the essay you are about to hand in) and submit the PDF from step 2.

    Note: This only needs to be done once per team.

System Contributions

To familiarize yourself with the system under analysis, your team will contribute to the system. This will take the form of a pull request to the system. Aspects to consider include:

  1. It is probably a good idea to start with a very simple pull request, just to understand the whole process.
  2. Starting with a documentation pull request might be a good way to get started.
  3. Many projects have labels for issues that are easy to start with for newcomers to the project. Explore these and see if you can help.
  4. After one or two simple pull requests, try to contribute more substantially, for example in refactorings or simple features.
  5. In your interactions (in GitHub comments) with the developers who are responsible for integrating your change, be polite, to the point, and responsive.
  6. Follow any guidelines, for example in the projects file.

For pull requests you’ve actually submitted, you can enter the corresponding information in the yaml meta-data of your project file, and information about it will be shown in your blog pages.

There will be two deadlines, for two simple reports:

The two reports can be put in a file, which you can put in your journals folder (so that it is ignored by jekyll). As an indication, around 100 words will probably suffice per planned (or terminated) pull request.

Pull requests will be graded, based on the following criteria:

While your aim is of course that the pull request gets merged, the merge itself is not part of the grade.


  1. Jim Coplien Gertrud Bjørnvig. Lean Architecture for Agile Software Development. Wiley, 2010.  2

  2. Nick Rozanski and Eoin Woods. Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives. Addison-Wesley, 2012, 2nd edition.  2 3

  3. Peter Hruschka and Gernot Starke. arc42: Effective, lean and pragmatic architecture documentation and communication.  2 3

  4. Philippe Kruchten. The 4+1 View Model of architecture. IEEE Software 12(6), 1995. (doi, preprint, wikipedia

  5. The C4 model for visualising software architecture.

  6. Cataldo, Herbsleb, and Carley. Socio-Technical Congruence: A Framework for Assessing the Impact of Technical and Work Dependencies on Software Development Productivity. ICSE 2008.