Akka Persistence Typed documentation

The main discussion is how much documentation we want and how much we should simply forward to Akka docs.

My first impression is that we do need some documentation in Lagom because Lagom embraces CQRS and the Akka docs do not focus on that as the main use case. If we want to guide someone into Lagom’s proposition, we need to cherry-pick the different pieces of the Akka docs, for instance: clustering, enforcing replies, aggregate consistency boundaries, tagging, etc.

Alternatively, we could add a CQRS section to the Akka documentation that basically would prescribe the same as Lagom. Then Lagom just points to it.

What follows is a collection of thoughts after comparing Lagom’s docs and Akka Event Sourcing docs.

Event Sourcing vs. CQRS with Event Sourcing

Akka docs don’t focus on the CQRS story, but rather on Event Sourcing. As a result, the model is not treated as a consistency boundary. For instance, Akka mentions that you could call an external service while validating an incoming command. This is a rare case for an Event Sourcing setup, but not ‘wrong’. For a CQRS application, where the model is expected to be consistency boundary, that’s totally not recommended.

Lagom should not mention remote command validation nor how to spawn child actors. We can mention how to log, for instance, but those other use case breaks the encapsulation of an Aggregate and make CQRS feel much more complex than it should be.

Cluster Sharding

Although Akka recommends the usage of Cluster Sharding, but it’s not a central piece of the documentation. That’s understandable for Akka, but Lagom is all about sharded data. And since we will be replacing the PersistenceEntityRegistry by ClusterSharding, it should take a more prominent role in the Lagom documentation.

For Lagom users, it’s very important to keep that link, because of how it relates with distributed reactive microservices

The whole read-side processors and topic producers part depends on cluster as well, therefore we need to make it a centrepiece of everything we do. This was not super obvious in Lagom, although you can’t escape it. With Akka Typed, Lagom users will have to use ClusterSharding directly (to register and to lookup entities) and that puts the cluster sharding at the centre. I find it a positive development, we must simply embrace it.

Tagging

Lagom documentation must cover tagging partition so we can connect with the read-side. This need to be covered by Lagom. Lagom has now the AkkaTaggerAdapter. Whatever we do, that part will stay in Lagom. I mean, if we have a “CQRS using Akka Persistence Typed” section in Akka, we still need the tagging on Lagom side.

Changing Behavior

Lagom example should model an FSM to show how to change behavior using Akka Persistence Typed. Akka has such an example as well, but I found it not so straightforward.

The reason being that the docs make some considerations regarding how changing behavior is different from general Actors. Again, that makes sense for Akka users. They come from classic Actors to Behavior to EventSourcedBehavior.

Enforcing replies

Akka doesn’t document ExpectingReplies as the most common use case. For CQRS, that makes lots of sense.

[octonato]

Alternatively, we could add a CQRS section to the Akka documentation that basically would prescribe the same as Lagom. Then Lagom just points to it.

I’m convincing myself that this is the best approach. If we have a story to tell about how to build CQRS apps using Akka Persistence Typed, that should be in the Akka docs. Not in Lagom nor in Play.

[octonato]

hey @solarmosaic-kflorence,

For your info, there is a PR for the issue you reported https://github.com/lagom/lagom/pull/3350.