DEV Community: Oliver Libutzki

archifacts is launched

Oliver Libutzki — Sun, 12 Sep 2021 13:52:55 +0000

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.

// Detect dark theme var iframe = document.getElementById('tweet-1427342753952899080-704'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1427342753952899080&theme=dark" }

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.

// Detect dark theme var iframe = document.getElementById('tweet-1421848177142026245-559'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1421848177142026245&theme=dark" }

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!

Do you really need an API?

Oliver Libutzki — Sun, 04 Apr 2021 20:14:50 +0000

"Low coupling, high cohesion", "information hiding": Well known design principles. Nevertheless, they are not taken seriously in many software architectures, especially when it comes to the interaction between the frontend and the backend.

APIs are valuable to hide information

By providing an API systems decide which information they expose to the outside world and which information they keep secret (Information hiding).

Why is that important? Because the broader an API is the more expensive it is to maintain. Think about the extreme of exposing every implementation detail. Every change in the system might break the clients which use the code. That's the reason why we strive for having small APIs. I wrote a post about this topic in the context of Event Sourcing.

Regardless of its size an API prevents us from evolving our system in a free manner. We always have to document the API carefully and consider not to break our clients. Changes have to be introduced in a backward compatible way or we have to align the deployments of our systems which quickly ends up in a deployment monolith hell.

API as product

But why do systems provide so many APIs, if it's so hard to maintain them? One reason might be that the API is the system's Unique Selling Point. The API is the product und you earn money by providing this API. In this case it's worth the efforts to document it, to use techniques like hypermedia and care about backward compatibility. Your clients will appreciate it and your API product shines.

Separation of frontend and backend

I argue that those API products are rare. Way more often the existence of a broad API is a sign for badly chosen boundaries - a violation of the "Low coupling - High cohesion" principle.

While this investigation applies to backend-to-backend communication, too, I would like to focus on the frontend. I question that we need an API to connect the backend and the frontend.

It's natural that the backend and the frontend are highly cohesent, because whenever some new data needs to be displayed on the frontend the backend needs to be adjusted. So why do we try to decouple them by putting a wall (an API) in between them?

Most of the time such a design is driven by organizational or technical circumstances. There are dedicated backend and frontend teams, but I wonder if the overhead of maintaining an API is always taken into account when deciding to separate the teams.

The desire for using client-side rendering

Another driver is the desire to implement the frontend with a modern Javascript UI library like Angular, React or Vue.js. In contrast to server-side rendered (SSR) approaches these libraries render the view at client-side (CSR) in the browser and rely on services (REST, GraphQL,...) provided by the backend to retrieve data and perform actions.

Self contained and CSR are no contradiction

Although I think that SSR is highly underrated these days, I can understand that the frontend requirements might be addressed better by a modern Javascript library.
But... using such a library does not necessitate an API! Think about delivering the service as a self-contained system, including the backend AND the frontend. Sure, you have a technology and environment break as the backend code is executed server-side and the frontend code is executed in the user's browser. This break requires the usage of HTTP in order to synchronize both environments.

I call this a bridge rather than an API as you can evolve the backend services hand in hand with the frontend. There is no need to document an API carefully or to deal with breaking changes, because there is just one client out there. And this client is well-known, because it's located in the very same system. The consequence is that the backend and frontend are always deployed as a whole and those documentation and compatibility challenges disappear.

Conclusion

Technology should not be the driver for system design. Regarding the interaction between the backend and the frontend take the requirements into account and decide if you want to go for a monolithic frontend or self-contained systems. "Low coupling - high cohesion" is a powerful guideline!

If you decide for a self-contained system it's up to you to choose a server-side or client-side rendering approach. Although CSR and SPA (Single Page Application) often are lumped together you can use CSR while still having a per-module frontend.

References

I had the idea of writing this post while listening to the SoftwareArchitekTOUR Podcast - Episode 82 (German) with Stefan Tilkov and Eberhard Wolff. Thanks for the inspiration!

Good resources to get deeper into self-contained systems and micro frontends:
Self-Contained Systems
Micro Frontend

Why Event Sourcing is a microservice communication anti-pattern

Oliver Libutzki — Fri, 28 Jun 2019 11:26:22 +0000

Event-driven architectures in general and Event Sourcing in particular gain traction in the last couple of years. This trend is caused by the fact that we strive after building modular systems which are resilient und scalable. Microservices is the term which is used in this context quite often. In my opinion microservices are just one way to implement a Bounded Context. The heart of a modular system are the boundaries of a module and the most promising idea how to identify these boundaries is the Strategic Design introduced by Eric Evans' Domain Driven Design. It helps you to identify/discover your modules with their boundaries (Bounded Context) and describes the way how these Bounded Contexts are related to each other (Context Map).

Note: I will presuppose some foreknowledge about certain terms as I do not want to explain them for the thousandth time. I decided to link to the explanations of microservices.io, Wikipedia or Martin Fowler's Bliki, so it's up to you do dive deeper into a certain topic, if you feel uncomfortable with your knowledge.

Domain Events as the heart of the Ubiquitous Language

Although not explicitly mentioned in Eric's book Domain Events facilitate the idea of the DDD concepts quite well. Techniques like Alberto Brandolini's Event Storming shift the focus on events from a technical to a organizational / business level. We do not talk about some UI layer events like a ButtonClickedEvent, but about Domain Events which are part of the business domain and which are spoken and understood by the business experts. These Domain Events are first-class concepts and provide a great way to form the Ubiquitous Language which all participants (domain experts, developers,...) agree on.

Domain Events used for cross-boundary communication

Domain Events can be used for facilitating the communication between Bounded Contexts. Let's assume we have an online shop with three Bounded Contexts: Order, Delivery, Invoice.

A Domain Event of the Order context is Order accepted. The Invoice as well as the Delivery context is interested in the occurence of this event as it causes some internal processes to be started.

The decoupling myth

The usage of Domain Events helps you to develop decoupled modules. Modules might be offline temporarily. Domain Events do not care about unavailable modules, they describe something that happened in the past. It's up to the other modules how fast they process the events. What you get is a resilient system by design.

Beside temporal decoupling Domain Events promise another advantage, at least at the first glance:
The Order context does not have to know that the Invoice and Delivery context listen to its events. Actually it even doesn't need to know that those contexts exist.

That's cool, but the challenging part is the event payload. Which data do put into the event?

The simple answer: Event Sourcing!

Events are useful, so why not giving them as much power (and responsibility) as possible. That's the basic idea of Event Sourcing. You do not store the state of an aggregate by updating its data (CRUD) but by applying an event stream.

Beside that fact that you can replay events to rebuild the application state, one great feature of Event Sourcing is that you get a complete and reliable audit log for free. So when such an audit log is required, Event Sourcing should definitely taken in account while evaluating the persistence strategy.

Is Event Sourcing just a persistence strategy?

You might wonder why I came from Domain Events straight to persistence strategy as these concepts obviously work at different layers / abstraction levels.

... and that's my point: Event Sourcing is a local decision made by a single Bounded Context! The events should not be exposed to the outside world! Other Bounded Contexts do not know about each other's persistence strategy and therefore they don't know and don't care, if another Bounded Context uses Event Sourcing.

If you use Event Sourcing at global scale, you expose your persistence layer.

Your persistence becomes your public API. Every time a Bounded Context adjusts its persistent data, we have to deal with a public API change.

I'm pretty sure everyone agrees that it's a bad idea that different Bounded Contexts share data in a (relational) database because of development und runtime coupling. But where is the difference?

There is none. It doesn't matter if we share events or database tables. In both cases we share our persistence details.

There is a way out

I still argue that Domain Events are a perfect fit for the communication between Bounded Contexts, but these events shall not correspond to the events used for Event Sourcing.

My proposed solution is the logical consequence: Regardless whether you use a CRUD or an Event Sourcing approach for persistence you publish Domain Events to a global event store. These Domain Events are your Bounded Context's public API. If you prefer the usage of Event Sourcing in your Bounded Context you store these events in a local event store which only accessible from this Bounded Context

The freedom of choice

Having dedicated Domain Events in your public API opens up the possibility to decide how to model these events. You are not restricted to the layout which is predefined by the Event Sourcing events.

You have two options for each occurrence of a "real world event":

Open Host Service with Published Language

Publish exactly one domain event which contains all the data which might be needed by other Bounded Contexts. In DDD terminology one would call this an Open Host Service with a Published Language.

The occurrence of the real world event Order accepted leads to one published Domain Event OrderAccepted. The payload of this event contains all the data which Order expects other Bounded Context's to be interested in... so hopefully the Invoice and the Delivery contexts find all the information they need.

Customer/Supplier

Publish multiple dedicated Domain Events, one for each event consumer. You have to discuss each particular Domain Event with exactly one other party (the consumer) and don't have to define a shared model. DDD calls this relationship Customer/Supplier.

The occurrence of the real world event Order accepted leads to one published Domain Event per consuming Bounded Context: InvoiceOrderAccepted and DeliveryOrderAccepted. Each Domain Event contains exactly the data which is requested by the consuming context.

I do not want to discuss the pros and cons of the two options. I just want to highlight that you are free to choose the number of Domain Events and their payload.

This is a great advantage you should not underestimate, because you can decide how to evolve your Bounded Context's API and are not committed to the events you need for Event Sourcing.

Conclusion

Exposing persistence details to the outside world is a well-known anti-pattern. When talking about persistence we think about database tables in the first place, but I explained why the events used for Event Sourcing are just another way how to persist data. Therefore exposing these events is a anti-pattern as well.

// Detect dark theme var iframe = document.getElementById('tweet-784691906005635072-812'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=784691906005635072&theme=dark" }

Event Sourcing is powerful, if it's used in an appropriate (local) way. At first glance it seems to be the silver bullet for event-driven architectures, but if you look in deeper, you realize that it might lead you to a tightly coupled (distributed) system... and that's not your aim, for sure.

References

Beside my personal experience I got a lot of inspiration from different abstracts and conference talks. I would like to highlight the talk Event-based Architecture and Implementations with Kafka and Atom by Eberhard Wolff. Especially the chapters Event Sourcing and Whats's in the event? are highly relevant in the context of this blog post. The online shop example I chose is inspired by this talk.

There are some other resources you can consult if you would like to get some additional information:

Domain Events vs. Event Sourcing by Christian Stettler, Blog post
What they don’t tell you about event sourcing by Hugo Rocha, Blog post
A Decade of DDD, CQRS, Event Sourcing (CQRS/ES is NOT a top level architecture) by Greg Young, Conference talk