I am very happy to announce the launch of archifacts - a library which helps you to extract the building blocks and relationships between them out of your Java or Kotlin application's bytecode.

In this blog post I'd like to explain the motivation for creating this library.

Tackling outdated documentation

Some weeks ago I stumbled upon this tweet by Tudor Girba.

When you crawl through the comments you quickly realize that most of the discussions are about the challenge to keep documentation up-to-date. In my current project we ran into this trap as we created a very extensive documentation which was not able to keep pace with the application's progress.

I do not say it's impossible to keep your software system and its documentation in sync, if they are independent artifacts, but it requires a high amount of discipline and effort.

I recommend to document the architectural concepts by hand and to derive the application's concrete building blocks automatically.

In general you have two options: You can model your application on a higher abstraction layer and generate code and documentation out of this model. Model-driven software engineering (MDSE) and DSLs are are promising approach to implement this strategy.

While this is a good idea in the first place you rarely model a whole application. Most often some stubs are generated which are implemented using a General Purpose Language (GPL) like Java, C# or Python. Therefore you cannot be sure that all the information is contained in the model... and that results in an incomplete documentation which is as bad as an outdated documentation.

In my opinion the most promising approach to document the actual behaviour of a system is to extract it from its foundation: the code.

Introducing archifacts

This is where archifacts kicks in. It analyzes your Java or Kotlin application's bytecode and builds an architecture model. Having this model in place you can use it to enhance your documentation by generating information about your modules, building blocks and relationships between them.

In this very first release archifacts ships integrations for Spring Framework, Axon Framework and jMolecules, a library which helps you to express your architectural concepts directly in the source code.

There is also some very basic support for generating documentation using AsciiDoc and Simon Brown's C4 model.

archifacts stands on the shoulders of a giant: ArchUnit and its fabulous Core API to extract the concepts from the bytecode.

Moduliths similarities

Conceptually, there a lot of similarities to Moduliths.
Moduliths helps you to build modular Spring Boot applications which are preferred to be deployed as a single unit. Like archifacts Moduliths uses ArchUnit to enforce certain architectural constraints and - based on some rules - it's able to identify the application's building blocks.

Although I'm convinced that Moduliths is a great starting point for building modular Spring Boot based applications, it was not the best choice for my use case. Moduliths has some impacts and expections regarding the application's structure. It has advanced semantics what a module is and which rules are enforced.

After providing some issues and PRs for Moduliths I decided that it's more efficient to build a library which is completely agnostic of any other runtime technology like Spring Boot.

I do not want to place archifacts as a competitor to Moduliths. It has a slightly different scope and maybe it makes sense to join forces some day.

How to get started

If you want to see archifacts in action as quick as possible check out the jmolecules-spring-data-example. It generates some
C4 diagrams and a textual architecture overview for a jMolecules example.

Please keep in mind that archifacts is in a very very early state, but I already published the first release to Maven Central, so everyone can use it and give feedback. Any contributions are highly welcome. To get in touch you can use GitHub and/or follow the project on Twitter.

I really hope that archifacts will come in handy for some other projects.

One last shoutout to Nils Ehmke for all the valuable discussions, reviews and contributions. Thank you!