Introducing scope42 - Improve your software architecture with precision! 🎯✨
Tags: architecture, productivity, news, showdev
Published: 2022-10-25 13:00:46

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.

<center>_Let's see how architecture improvement can be organized
 and assisted by tooling_ 🚀</center>

## Table of contents
  * [Introduction to aim42](#introduction-to-aim42)
  * [The birth of scope42 ](#the-birth-of-scope42)
    * [Management of items](#management-of-items)
    * [Relationship graphs](#relationship-graphs )
    * [Docs-as-code ](#docsascode)
  * [State of the project & roadmap ](#state-of-the-project-amp-roadmap)
  * [Tech stack](#tech-stack)
  * [Your feedback is welcome ❤ ](#your-feedback-is-welcome-%E2%9D%A4)

## 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
>
> &mdash; <cite><a href="https://aim42.github.io/#_about_aim42">About aim42</a></cite>

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:[^aim42-domain-model]

* _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](https://www.aim42.org/)
* [The Method Reference](https://aim42.github.io/)
* [The GitHub Repository](https://github.com/aim42/aim42)

## 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.

![scope42 logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tesn9ssam3ar5e9lxbgg.png)

<center>[github.com/scope42/scope42](https://github.com/scope42/scope42)</center>


### 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.

![scope42 items table](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fwd9zmahkby4qkcywsu5.png)

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.[^obsidian]

![scope42 items graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9l6x1p82lk55vot3e4lw.png)

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](https://app.scope42.org) 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](https://web.dev/file-system-access/) (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](https://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):

```yaml
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](https://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.

{% embed https://twitter.com/scope42_org/status/1582788370584940544 %}

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.

{% embed https://github.com/scope42/scope42 %}

<center>**The app is available at [app.scope42.org](https://app.scope42.org).**</center>
<br />

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](https://arc42.org/overview) 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](https://adr.github.io/)). 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](https://github.com/doctoolchain/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](https://www.viewpoints-and-perspectives.info/home/perspectives/). This principle is for example implemented for diagrams by [Structurizr](https://www.structurizr.com/help/perspectives). 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](https://www.typescriptlang.org/)
- UI is built with [React](https://reactjs.org/) and [Ant Design](https://ant.design/)
- Relationship graphs are created using [Cytoscape.js](https://js.cytoscape.org/)
- Code is organized in a monorepo powered by [Turborepo](https://turborepo.org/)
- The CI/CD pipeline is based on [GitHub Actions](https://github.com/features/actions) and [Changesets](https://github.com/changesets/changesets)
- The production version of the app and deployment previews for pull requests are hosted on [Netlify](https://www.netlify.com/)

Tech choices and other architecture decisions are documented using scope42 itself [in the repository](https://github.com/scope42/scope42/tree/main/architecture).

## Your feedback is welcome ❤

If you think this app could be useful to you, don't hesitate to [try it out](https://app.scope42.org) yourself!

If you have any feedback, feel free to leave a comment here, open an issue/discussion on [GitHub](https://github.com/scope42/scope42) or get in touch with [@scope42_org](https://twitter.com/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 ❤

[^aim42-domain-model]: In the actual [aim42 domain model](https://aim42.github.io/#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.

[^obsidian]: [Obsidian](https://obsidian.md/) 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.