Technical Architecture - motown-io/motown GitHub Wiki

Approach

Requirements

Motown's architectural requirements, as described on the Overview page, lead to the following architectural approach.

  • An asynchronous, event driven platform for scalability.
  • Event sourcing will be used to keep track of history.
  • Domain-driven design will be used to capture the domain logic.
  • Add-ons integrate using an event structure so third parties can develop both open and closed add-ons.
  • The platform can be composed for its runtime (from lightweight to heavy load).
  • The system will be based on open source components so third party developers can easily contribute to the system or its add-ons.

Patterns and Principles

This architectural approach leads to a number of design decisions. The first of these is applying Alistair Cockburn’s “hexagonal architecture”, also known as “ports and adapters”. In short, the hexagonal architecture prescribes developing the core of your application without a dependency on your UI, database, or other inputs and outputs. This separation between inputs, outputs and the behavior or logic of your application allows for a composable system, which allows extension from third party add-ons.

![Hexagonal architecture][hexagonal-img]

This is achieved as follows:

  • Composability is enabled by giving implementations of the system the freedom to choose its own persistence and communication solutions. For instance, event sourcing could be enabled using persistence solutions ranging from simple file system storage to large clustered databases.
  • Add-ons are enabled because the core of the application is agnostic to its inputs and outputs. These inputs and outputs can be provided by first party Motown add-ons but could also be provided by third party add-ons (open or closed).

![CQRS][cqrs-img]

The second design decision is applying the [Command Query Responsibility Segregation (CQRS) pattern][fowler-cqrs]. CQRS is, at its core, a relatively simple architectural pattern that allows you to use a separate model for updating information (command) and a separate model for retrieving information (query). CQRS naturally fits with some other architectural patterns:

  • CQRS is a good fit for complex domains. Another natural fit for these domains is domain-driven design (DDD). DDD’s patterns (e.g. entities, aggregates, value objects) will be used to model the core domain of the system. DDD also naturally fits the hexagonal architecture as the domain layer in DDD delegates technical details to the infrastructure layer.
  • Updating information in CQRS is done by sending commands to a domain. A natural consequence of using commands is to generate events that describe the required changes to the domain. Adding event sourcing and storing the domain’s events in the order they were applied gives us historical data for research purposes, replayability of past events for robustness, and an audit log.

Combining all these architecture patterns would lead to the following (general) high level application architecture (as described in the [Axon Framework documentation][axon-docs], more on Axon later).

![High level application architecture from Axon Framework's documentation][axon-overview-img]

Although the above describes a general application architecture for applications applying CQRS and related architecture patterns in general, and Axon Framework in particular, a few differences are noteworthy for Motown’s architecture. Most notable are the scopes of the subsystems. These are illustrated in the following image.

![Scope of Motown's subsystems mapped on high level application architecture][cqrs-scope-img]

As can be seen in the image above, Motown Core’s scope is limited to command handling, the domain, and event sourcing. Both third party as well as first party add-ons (e.g. Operator API, OCPP) need to implement the event handling and (user) interfaces (OCPP add-ons typically don't have UIs but do have interfaces to other systems).

Further Reading

The above is just an introductory explanation of the concepts used in Motown. To get a more in-depth explanation of these concepts, check out the following links:

  • [Slides we used to explain the concepts used in Motown.][technical-architecture-slides]
  • [Martin Fowler's article about CQRS.][fowler-cqrs]
  • [Udi Dahan's article about CQRS.][dahan-cqrs]
  • [Greg Young's article about CQRS.][young-cqrs]
  • [Microsoft's series of articles about CQRS and Event Sourcing.][microsoft-cqrs]

Continue with Getting started or the Developers guide.

[hexagonal-img]: assets/images/ports-and-adapters.png "Alistair Cockburn's hexagonal architecture, or "ports and adapters" from http://www.dossier-andreas.net/software_architecture/ports_and_adapters.html" [fowler-cqrs]: http://martinfowler.com/bliki/CQRS.html "CQRS by Martin Fowler" [cqrs-img]: assets/images/cqrs.png "CQRS from http://martinfowler.com/bliki/CQRS.html" [axon-docs]: http://www.axonframework.org/docs/ "Axon Framework's reference guide" [axon-overview-img]: assets/images/axon-overview.png "Architecture overview of a CQRS application from http://www.axonframework.org/docs/2.1/single.html" [cqrs-scope-img]: assets/images/cqrs-scope.png "Motown's subsystem scopes mapped on the CQRS architectural overview" [technical-architecture-slides]: assets/slides/20140312MotownTechnicalArchitecture.pdf "Slides explaining Motown's technical architecture" [dahan-cqrs]: http://www.udidahan.com/2009/12/09/clarified-cqrs/ [young-cqrs]: http://codebetter.com/gregyoung/2010/02/16/cqrs-task-based-uis-event-sourcing-agh/ [microsoft-cqrs]: http://msdn.microsoft.com/en-us/library/jj554200.aspx