wangchengqun/akkatecture

a cqrs and event sourcing framework for dotnet core using akka.net

Akkatecture

Akkatecture is a cqrs and event sourcing framework for akka.net. Fully optimised around using akkas non-thread-blocking message passing and event stream pub sub mechanism for event propagation. All in .net core (targeting netstandard 2.0).

Go ahead and take a look at our documentation, go over some concepts, and read the tips and tricks.

Features

• Distributed: Backed by akka.net's actor model. Akkatecture enjoys the benefits of a good distributed computing computation model.
• Message based: Making it highly scalable by being reactive from message passing, Akkatecture does not ask, it tells.
• Event sourced: By design, aggregate roots derive their state by replaying persisted events.
• Highly scalable: Work proceeds interactively and concurrently, overlapping in time.
• Configurable: Through akka.net's hocon configuration, you will be able to configure every aspect of your application.

Examples

Akkatecture comes with a few examples on how to best use it:

• Simple: A simple console based example that shows the most simple example of how to create an aggregate and issue commands to it.

• Walkthrough: Tutorial style sample based on the walkthrough in the Akkatecture documentation. The walkthrough proposes domain that should be modelled based on some business requirements. The walkthrough goes step by step covering all the primitives and features covered in Akkatecture to give you an understanding of the framework. The beginning of the walkthrough in the documentation can be found here.

• Cluster: A more involved sample that shows you how to do distributed aggregates using clustering. Read the readme for the sample for a good overview of the example.

• Tests: The test examples found in the Akkatecture.TestHelpers project is there to provide assistance when doing testing for Akkatecture. There is a simple domain modelled that includes an aggregate with a simple aggregate saga, and these are used to do simple black box style testing on Akkatecture using akka.net's TestKit.

Note: This example is part of the Akkatecture simple example project, so checkout the code and give it a run.

//Create actor system
var system = ActorSystem.Create("useraccount-example");

//Create supervising aggregate manager for UserAccount aggregate root actors
var aggregateManager = system.ActorOf(Props.Create(() => new UserAccountAggregateManager()));

//Build create user account aggregate command with name "foo bar"
var aggregateId = UserAccountId.New;
var createUserAccountCommand = new CreateUserAccountCommand(aggregateId, "foo bar");
            
//Send command, this is equivalent to command.publish() in other cqrs frameworks
aggregateManager.Tell(createUserAccountCommand);
            
//tell the aggregateManager to change the name of the aggregate root to "foo bar baz"
var changeNameCommand = new UserAccountChangeNameCommand(aggregateId, "foo bar baz");
aggregateManager.Tell(changeNameCommand);

Assumptions About Akkatecture Developers

It would be ideal if you have some expirience in domain driven design, cqrs, and event sourcing. It would also be beneficial for you to be familiar with actor systems, akka.net, and the extensibility points that akka gives you through hocon configuration. However, if you follow the walkthrough you will be acquinted with many akka.net concepts.

Status of Akkatecture

Akkatecture is still in development. The goal of this projects first version is to provide you with the neccassary building blocks to build out your own cqrs and event sourced application without having to think of the primitives.

akkatecture is currently missing these crucial features:

• aggregate state snapshotting.
• persisting event metadata.
• typed actor references.
• schedueled jobs.

Contributing

Akkatecture's documentation source is here, if you have any suggestions or improvements that can be made to them.

Useful Resources

There are many different opinions and best practices when it comes to building out ddd based solutions. Here are a few articles and resources that can give you a good foundational grounding on the concepts used extensively in this project.

Domain-Driven Design

• Domain-Driven Design Reference by Eric Evans

CQRS & Event sourcing

• CQRS Journey by Microsoft published by Microsoft
• An In-Depth Look At CQRS by Mike Mogosanu
• CQRS, Task Based UIs, Event Sourcing agh! by Greg Young
• Busting some CQRS myths by Jimmy Bogard
• CQRS applied by Gabriel Schenker

Eventual consistency

• How To Ensure Idempotency In An Eventual Consistent DDD/CQRS Application by Mike Mogosanu

Video Content

• CQRS and Event Sourcing by Eric Evans
• An Introduction to CQRS and Event Sourcing Patterns by Mathew McLoughling
• The Future of Distributed Programming in .NET by Aaron Stannard

Motivations

Doing domain driven design in a distributed scenario is quite tricky. And even more so when you add cqrs and event sourcing style mechanics to your business domain. Akka gives you powerful ways to co-ordinate and organise your business rules by using actors and message passing, which can be done by sending messages through location transparent addresses (or references). The major benefits of using akka.net is that we can isolate our domain models into actors where it makes sense.

Akkatecture gives you a set of opinionated generic constructs that you can use to wire up your application so that you can focus on your main task, modelling and codifying your business domain.

Akka.net gives us a wealth of good APIs out of the box that can be used to build entire systems out of. It also has a decent ecosystem and community for support. Akkatecture is also of the opinion that commands translate well semantically in actor systems since telling commands is a form of message passing that fits well into the actor model paradigm.

Acknowledgements

• Akka.NET - The project which AKkatecture builds ontop of, without akka.net, Akkatecture wouldnt exist.
• EventFlow - Akkatecture has adapted the api surface from event flow to work in the akka actor world.
• Nact - For giving us basis to write our documentation. Powered by gatsbyjs.

License

The MIT License (MIT)

Copyright (c) 2018 Lutando Ngqakaza

https://github.com/Lutando/Akkatecture

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.