Merge pull request #17 from Lutando/dev

Dev

.vscode/launch.json

@@ -0,0 +1,74 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Akkatecture.Examples.UserAccount.Application",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/examples/simple/Akkatecture.Examples.UserAccount.Application/bin/Debug/netcoreapp2.0/Akkatecture.Examples.UserAccount.Application.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/examples/simple/Akkatecture.Examples.UserAccount.Application",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Akkatecture.Walkthrough.Application",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/examples/walkthrough/Akkatecture.Walkthrough.Application/bin/Debug/netcoreapp2.0/Akkatecture.Walkthrough.Application.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/examples/walkthrough/Akkatecture.Walkthrough.Application",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Akkatecture.Examples.ClusterClient",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.ClusterClient/bin/Debug/netcoreapp2.0/Akkatecture.Examples.ClusterClient.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.ClusterClient",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Akkatecture.Examples.Seed",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.Seed/bin/Debug/netcoreapp2.0/Akkatecture.Examples.Seed.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.Seed",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+            "internalConsoleOptions": "openOnSessionStart"
+        },
+        {
+            "name": "Akkatecture.Examples.Worker",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.Worker/bin/Debug/netcoreapp2.0/Akkatecture.Examples.Worker.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/examples/cluster/Akkatecture.Examples.Worker",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+            "internalConsoleOptions": "openOnSessionStart"
+        }
+    ],
+    "compounds": [
+        {
+            "name": "Akkatecture.Examples.SeedWorkerCluster",
+            "configurations": ["Akkatecture.Examples.Seed", "Akkatecture.Examples.Worker", "Akkatecture.Examples.ClusterClient"]
+        } 
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,15 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "command": "dotnet",
+            "type": "process",
+            "args": [
+                "build",
+                "${workspaceFolder}/examples/cluster/Akkatecture.Examples.ClusterClient/Akkatecture.Examples.ClusterClient.csproj"
+            ],
+            "problemMatcher": "$msCompile"
+        }
+    ]
+}

README.md

@@ -1,5 +1,7 @@
 
 <a href="https://akkatecture.net/"><img src="https://raw.githubusercontent.com/Lutando/Akkatecture/master/logo.svg?sanitize=true" width="100%" height="200"></a>
+
+
 [![Build Status](https://travis-ci.org/Lutando/Akkatecture.svg?branch=master)](https://travis-ci.org/Lutando/Akkatecture)
 [![Build status](https://ci.appveyor.com/api/projects/status/cxdg8eyk7d5nmqgj?svg=true)](https://ci.appveyor.com/project/Lutando/akkatecture)
 [![Nuget Package](https://img.shields.io/nuget/v/Akkatecture.svg?style=flat)](https://www.nuget.org/packages/Akkatecture/)
@@ -16,11 +18,11 @@ Go ahead and take a look at [our documentation](http://akkatecture.net/docs/gett
 
 ### Features
 
-* **Distributed:** Backed by akka.net's actor system. Akkatecture enjoys the benefits of a reasonable distributed computing computation model.
-* **Message based:** For high levels of message throughput and processing Akkatecture [does not ask, it tells](http://bartoszsypytkowski.com/dont-ask-tell-2/).
+* **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](http://bartoszsypytkowski.com/dont-ask-tell-2/).
 * **Event sourced:** By design, aggregate roots derive their state by replaying persisted events.
-* **Highly scalable:** Actors with their thread safe and distributed nature gives us this plus point.
-* **Configurable:** Through akka.net's hocon configuration.
+* **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
 
@@ -33,7 +35,7 @@ Akkatecture comes with a few examples on how to best use it:
 
 * **[Cluster](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster):** A more involved sample that shows you how to do distributed aggregates using clustering. Read the [readme](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/README.md) for the sample for a good overview of the example.
 
-* **[Test Example](https://github.com/Lutando/Akkatecture/tree/master/test/Akkatecture.TestHelpers/Aggregates):** 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.
+* **[Tests](https://github.com/Lutando/Akkatecture/tree/master/test/Akkatecture.TestHelpers/Aggregates):** 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
@@ -57,17 +59,18 @@ var changeNameCommand = new UserAccountChangeNameCommand(aggregateId, "foo bar b
 aggregateManager.Tell(changeNameCommand);
 ```
 
-### Assumptions About Akkatecture Users
+### Assumptions About Akkatecture Developers
 
-You should have a comfortable grasp of domain driven design, cqrs, and event sourcing concepts.
-It would also be benefitial for you to be familiar with actor systems, akka.net, and the extensibility points that akka gives you through hocon configuration.
+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](https://akkatecture.net/docs/walkthrough-introduction) 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.
 
 ### Contributing
@@ -107,9 +110,9 @@ There are many different opinions and best practices when it comes to building o
 
 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 semi-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.
+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. I also am of the opinion that commands translate well semantically in actor systems since you are telling the actor what you want, and the actor might or might not "respond" with a fact or a bag of facts relating to what that command produced in context of that aggregate.
+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](https://gitter.im/akkadotnet/akka.net) 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
 

appveyor.yml

@@ -1,4 +1,7 @@
-version: 0.0.{build}
+version: 0.1.{build}
+branches:
+  only:
+  - master
 skip_tags: true
 image: Visual Studio 2017
 configuration: Release

examples/cluster/README.md

@@ -2,15 +2,15 @@
 
 The Cluster Sample is made up of three projects, `Akkatecture.Examples.ClusterClient`, `Akkatecture.Examples.Worker`, and `Akkatecture.Examples.Seed`. Here is a brief description of each project.
 
-## [ClusterClient](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.ClusterClient)
+## Akkatecture.Examples.ClusterClient
 
 The cluster client project is the code that interfaces with the cluster. It can be seen as the way to invoke the domain from an external place. It works by opening a proxy to the actual worker(s). All requests done through the client are transported / serialized / deserialized through the actor system and the requests are routed to the correct cluster shard that runs on the worker.
 
-## [Worker](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.Worker)
+## Akkatecture.Examples.Worker
 
 The worker is where all the real computation is done. The worker is responsible for routing commands to the right aggregates and the aggregates then process the commands, which may or may not result in events being emitted from them, resulting in those aggregate events being persisted to their event journal. In typical scenarios the worker would be deployed in numerous nodes within a network on the cloud or in a kubernetes cluster.
 
-## [Seed](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.Seed)
+## Akkatecture.Examples.Seed
 
 The seed or seed node is only responsible for akka service discovery. Its only purpose is to exist at a well known location so that nodes within the actor system can effectively discover each other through the seed node. It is important that the seed does no work that can potentially disrupt its service level. In this sample the seeds address is 127.0.0.1:6000, the 10 workers are addressed from 127.0.0.1:6001-6011, and the console client is on 127.0.0.6100.
 
@@ -21,3 +21,7 @@ This sample uses the same domain model as the one found in the [simple](https://
 If you take a look at the hocon configurations for the [client](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.ClusterClient/client.conf), the [worker](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.Worker/worker.conf), and the [seed](https://github.com/Lutando/Akkatecture/tree/master/examples/cluster/Akkatecture.Examples.Seed/seed.conf), you will see that they all point to the same well known address (127.0.0.1:6000). This address is the seed nodes address, it tells the actor systems to use that address to initiate cluster gossip, and thus to establish the clustered network of actor systems. Each of the projects use the default akkatecture hocon configuration as a fallback configuration because this configuration has akkatecture opinionated "sane" defaults.
 
 The sample is as easy as running all three projects at the same time. To interact with the domain just press enter on the clients console window, resulting in random commands being created, which are then fed through the cluster proxy that will serialize, deserialize, and route the commands to the necessary aggregate. To exit the applications safely, Press `Q` and enter. 
+
+The purpose of this example is to show how you can distribute your actorsystem using `Akka.Cluster`. Doing this does not require any changes to your domain code. Basically now your domain can be distributed across separate, networked nodes.
+
+> To run the project in jetbrains rider or visual studio code, run the `Akkatecture.Examples.SeedWorkerCluster` configuration in the IDE.

examples/simple/README.md

@@ -15,4 +15,12 @@ This is the domain of the sample which is a basic model of user accounts, it sup
 
 # Akkatecture.Examples.Application
 
-This is the console application that creates the actor system and interfaces with it. First an aggregate manager is created, this aggregate manager is responsible for creating the aggregate actors beneath it, it is also responsible for supervising these actors and for routing messages to the appropriate aggregates. After this is done, a command for aggregate creation is made, and then the command is pushed through the aggregate manager, then a second command is done that pushed a change name command to the same aggregate that was previously created. Run the code to see how it works.
+This is the console application that creates the actor system and interfaces with it. First an aggregate manager is created, this aggregate manager is responsible for creating the aggregate actors beneath it, it is also responsible for supervising these actors and for routing messages to the appropriate aggregates. After this is done, a command for aggregate creation is made, and then the command is pushed through the aggregate manager, then a second command is done that pushed a change name command to the same aggregate that was previously created. Run the code to see how it works.
+
+### Description
+
+In this sample, we instantiate the actor system and the various domain entities required for it to work. The domain entity required to 
+initialize this, is the `UserAccountAggregateManager`. We then interface with the domain by telling the manager to create user accounts 
+by instantiating and telling it a `CreateUserAccountCommand`.
+
+> to run the application in jetbrains rider or visual studio code, run the `Akkatecture.Examples.UserAccount.Application` configuration in the IDE.