As software architects, we often face legacy systems that have many architectural issues. Also in greenfield projects, the architecture is developed iteratively and needs to be improved on a regular basis.

Table of contents

• Introduction to aim42
• The birth of scope42
  • Management of items
  • Relationship graphs
  • Docs-as-code
• State of the project & roadmap
• Tech stack
• Your feedback is welcome ❤

Introduction to aim42

aim42, the Architecture Improvement Method, is an open, community-driven framework for working on software architectures.

aim42 supports software evolution, maintenance, migration and improvement - in a systematic and pragmatic way

— About aim42

It defines a process consisting of three phases

• Analyze
• Evaluate
• Improve

accompanied by cross-cutting concerns. The method reference collects concepts and patterns that can be used to implement the process. It proposes three main types of entities of special interest:¹

• Issue (problem)
• Risk (potential future problem)
• Improvement (remedy)

Instances of these, I'll call them items, need to be collected, managed, and associated with each other. This is where the question of tooling comes into play.

aim42 is licensed under Creative Commons Attributions Sharealike. For more information refer to:

• The official website
• The Method Reference
• The GitHub Repository

The birth of scope42

I came into touch with aim42 in the course of my master's thesis which was concerned with improving the software architecture of a legacy system. I approached this with my standard means of note-taking but realized at some point that a dedicated tool would be beneficial. This birthed the idea of scope42 and I started to work on it after finishing my thesis.

Management of items

One of the first challenges that arise, as the number of items grows, is managing them. This requires structured metadata (e.g. title, status) as well as a way to filter and sort by it.

This is the core functionality of scope42. It is similar to a ticket tracker. An existing generic one would require quite some configuration work to get started - scope42 comes with the aim42 domain model out-of-the-box. It even incorporates some content of the aim42 method reference so you can learn it along the way.

Also, I try to provide a modern and slick UI that is not overloaded but focused on the particular domain. The aim is to make the act of writing documentation as fun as possible. At least in my personal experience, this is already quite successful.

Another notable feature is the integrated full-text search and quick access to items via the Strg + K / ⌘ + K shortcut.

Relationship graphs

While you can link tickets in classical trackers like JIRA, visualization of these relationships is not a common feature.²

The connection of items (e.g. issue is caused by another issue, improvement mitigates risk, etc.) are at the core of the aim42 domain model. It is an important concern and the overview can get lost quickly with a growing number of items.

Because of this, scope42 features relationship graphs for visualization. On an item's details page, you can quickly see its direct connections. Also, when viewing a list of items (e.g. filtered by specific criteria), a graph displays the relationship between these items.

Docs-as-code

The scope42 web app runs in your browser - no need to download anything. However, a vital difference to most such applications is how the data is stored. There is no database.

All items reside as files on your local machine. The app interacts with them via the File System Access API (currently sadly does not work in Firefox, only in Chromium-based browsers). This ensures privacy (data is never sent anywhere) and data ownership - if scope42 disappears tomorrow, you will not lose your data.

Another important aspect of data ownership is an open format. You should, at any point, be able to take your data and use it somewhere else. In fact, scope42 is built around the idea of processing the structured data managed with it and e.g. incorporating it into your existing documentation.

A main driver for the choice of a concrete format is the concept of docs-as-code. It is based on the idea that documentation is stored in a lightweight text-based format. It can then - similar to or even alongside code - be checked into version control, authored with your editor/IDE, and automatically processed and tested. You can read more about this topic at docs-as-co.de.

Applying this approach to more structured data is a bit of a challenge. As a compromise between human-readability and machine-readability, a format based on YAML is used. Example (improvement):

title: Upgrade Spring Boot version
created: 2022-05-02T17:25:16.909Z
modified: 2022-05-02T18:09:42.952Z
status: implemented
tags:
  - backend
  - urgent
  - security
ticket: https://github.com/scope42/scope42/issues/91
description: The current version of Spring Boot upgrades dependencies to secure
  versions of Log4j.
resolves:
  - issue-3
modifies:
  - risk-1
comments:
  - author: Jane Doe
    created: 2022-05-02T17:27:17.630Z
    content: Accepted and placed into the fast lane on the board.

In many places (for example item descriptions and comments), Markdown is supported for formatting. This includes advanced features like GFM extensions, code syntax highlighting, links to scope42 items, Mermaid diagrams, and more to come. For more information see docs.scope42.org/markdown.

For collaboration, you can use your file-syncing technology of choice. It is recommended to check your scope42 data in a Git repository. As for your code, this enables a detailed change history and the ability to merge concurrent modifications.

State of the project & roadmap

I already use scope42 for multiple real architecture projects at work. The experience from these - and iterative improvements based upon it - have led to the first stable release being recently published.

It is still in a relatively early stage in terms of features that I have in mind. But the release of version 1.0.0 means that there will be no breaking changes to the data format in the foreseeable future. You can safely start to use it and will be provided with automatic migrations if necessary at some point.

The project is completely open-source and free software. It is published under GPLv3 on GitHub.

title: Upgrade Spring Boot version
created: 2022-05-02T17:25:16.909Z
modified: 2022-05-02T18:09:42.952Z
status: implemented
tags
  - backend
  - urgent
  - security
ticket: https://github.com/scope42/scope42/issues/91
description: The current version of Spring Boot upgrades

There is a large roadmap of planned features I am eager to implement. These for example include UX improvements like an advanced Markdown editor, more Markdown features, and item management capabilities.

In the long run, scope42 will be expanded from an architecture improvement tool to a general architecture documentation platform. In most projects, these two concerns will naturally play together. For example, if you use the arc42 template for your documentation, the aim42 items would be integrated into chapter 11 "risks and technical debt".

In fact, there is already an additional item type decision (ADR). This falls more into the realm of documentation (arc42 chapter 9). However, it quickly became clear that ADRs are also connected to aim42. Often, proposed improvements need to be assessed by architecture decisions, especially if there are multiple options to resolve an issue.

In addition to this, the focus will be laid on exporting data and integration with other tooling. This includes a convenience library for programmatic processing, static site export, and a set of recipes, e.g. for integrating with things like docToolchain.

Lastly, a great advantage of this application over a static collection of Markdown/AsciiDoc files will be dynamic adaption for specific tasks. It should be possible to view your documentation from different architectural perspectives. This principle is for example implemented for diagrams by Structurizr. It will be applied more universally by scope42. Also, it may be useful to tailor your documentation to different target audiences (e.g. developers, management) as described by arc42.

Tech stack

• Code is written in TypeScript
• UI is built with React and Ant Design
• Relationship graphs are created using Cytoscape.js
• Code is organized in a monorepo powered by Turborepo
• The CI/CD pipeline is based on GitHub Actions and Changesets
• The production version of the app and deployment previews for pull requests are hosted on Netlify

Tech choices and other architecture decisions are documented using scope42 itself in the repository.

Your feedback is welcome ❤

If you think this app could be useful to you, don't hesitate to try it out yourself!

If you have any feedback, feel free to leave a comment here, open an issue/discussion on GitHub or get in touch with @scope42_org on Twitter.

My dream would be to build a community around this tool that shapes it so we can all profit from each other and make our daily work even more fun and effective 🚀

Following for updates on any platform is greatly appreciated - as well as sharing this article with people you think may be interested ❤

1. In the actual aim42 domain model, risk is not a primary entity type but an extension of issue. In scope42 I decided to make the distinction more sharp. Also, there is another entity type cause in the method reference. I modeled this as a relationship between issues/risks instead. ↩

2. Obsidian is good at visualizing relationships and would adhere to docs-as-code. However, it is only free for personal use. Software architecture is often worked on in a commercial setting. ↩