Sapiens Works

Using DDD, CQRS, Event Sourcing With A Vague, Fast Changing Domain

Mon, 30 Oct 2017 00:00:00 +0000

If you’re a startup, there’s a high chance that your product/service is new and disruptive. This means you (or the stakeholders) have just a vague idea of what you want and what can be called Domain is just a mishmash of things that change every day. Is it a good idea to use DDD, CQRS or Event Sourcing in this case?

Yes, it is! It will simplify your work greatly, if you really understand DDD/CQRS/ES . At this point, you might be puzzled how can DDD be a good choice when the domain is fuzzy and there’s no domain expert. Not a big problem, because it’s all about understanding what the stakeholder want to accomplish, step by step.

Now truth be told, especially in cases like this, you’d be happy if you can get even a half-assed idea, because nobody really knows what they want, it’s all about vague, raw concepts and maybe, very crude business processes. But regardless, you can latch on the most important thing: language.

Sure, the domain language is volatile, things will change daily and many times drastically, but the good news is you need to live in the present, not the future. Present concepts, present rules are what matter, we don’t care much about ‘what if’. So yeah, basically an iron YAGNI.

In order to keep things sane and productive, first step is to see the whole application as a group of (high level)functionalities. For example, for Twitter would be stuff like: register, login, follow, tweet, retweet etc, basically all the app features that can be used by the users(I’m including API here too). So, start identifying application functionality.

Next step is, when modelling, to treat each functionality as independent. What I mean here is that the resulting model for one functionality should be decoupled from other models. Applying CQRS, it means that command models are not reusable, they are unique and specific to each functionality. From DDD point of view, it means we don’t reuse Aggregates. This way, each functionality is decoupled and they can evolve differently, according to needs.

What about Event Sourcing? If domain changes a lot, then the events will change too, right? Is it worth it? Of course it is! First of all, domain events are notifications of changes that already happened. Their structure may change if details change (but the data itself remains), but when it comes to business rules the changes affect the future, not the past.

Let me give you an example. Chances are you have a degree/certification in something. In order to get that you had to pass an exam that verified that you have certain knowledge. Let’s say 10 years have passed. The syllabus changed and the exam now requires any exam taker to know the new stuff. So, anyone passing the exam now will be according to the new rules and content. But what about your 10 years old degree? It stays the same, you don’t need to change it, the new rules don’t apply to you (the past).

The events are the degrees obtained after the exam (according to at-the-moment business rules). Once you have them,they don’t go back to being re-validated when business rules(exam) change. They are old data and yes, their details can change and you add/remove those new fields to make it technical compatible to current version. But in the end, they are just data. When things change, our model change but the existing data stays the same. We should also acknowledge that the event class structure as an implementation of a domain event is not a synonym (but a destination) for the event data stored in the db.

However, this require a certain approach i.e your aggregates should basically be events factories. A business object should contain only rules and a transient state that wouldn’t be persisted. Simply put, your business objects don’t contain business data with rules, only the business rules required to create events.

With ES and CQRS, a specific domain state can be restored as a readonly model by replaying events (which basically means assigning data).

By doing that, you keep things maintainable. The domain model implementation is mainly rules (organized as specific one-use aggregates, value objects and services), while persistence gets only the valid relevant business data. The important thing here is that persistence contains the whole domain state expressed as events streams and projections.

Simple Example

Let’s assume you’re building the next Facebook and right now the registration functionality requires only username and password. You’ll end up with an UserRegistered event.

public class UserRegistered
{
    public string Username {get;set;}
    public byte[] PasswordHash {get;set;}
}

Two weeks pass and you decide that all new users needs to provide an email address too. This means that you need to change the aggregate to enforce the new rule. Also, the event (class) itself needs to be changed (add property Email). Any new user will be required to provide an email, everything is good. What about the previous users?

This is not a case where we can ‘upgrade’ somehow existing user info, so basically the app UI will present a popup after login, telling them to provide a valid email. This means adding another event EmailUpdated or similar and now, the domain has the emails for the ‘old’ users as well. That’s why we look at the business state (persisted relevant business data expressed as events) as a whole. It can be updated by means of different aggregates and events. The projected queryable model is also updated.

Regarding technical implementation, while the event structure has changed, the existing data is still the same and this means you need to map the old data to new structure (which is the job of the Event Store). As I’ve said before, old events aren’t re-validated by new rules so the question now is, what happens when we replay events and the projected read model.

I’ll start with the latter. Using a RDBMS means you need to update one or more tables definition in this case you add a new column Email which is nullable. The read model needs to reflect the fact that not all existing users have an email. This is a simple scenario and here things are as CRUD as they can get.

If a db schema changes very much or you’re using a nosql db, maybe the easiest method is to regenerate the whole read model.

About restoring an object state by replaying events that contain old data, first of all is important to remember that the restored state is immutable and the events are just sources of data. No business rules come into play, an Apply function just ‘maps’ information from an event to object state. Again, this function should be aware that Email can be empty.

Basically, when the domain changes, we update the model in our app, but because we have and want to keep the old data, the model still needs to account for artifacts of old rules as they affect the current domain state. In our example, email wasn’t needed and that generated specific data, then email was added and the model now correctly requires email for new users while it also deals with the implications of the old rule i.e users without an email.

As a domain evolves, the rules keep changing, but the existing business data doesn’t. Therefore everytime we deal with a business rule change, we have to consider its residual implications from a business point of view first(i.e non-technical) and technical second.

In our example, regardless of how many times the rules change, it may always be 1 user who registered at the beginning and never returned. So, you either have the concept of an abandoned account that needs to be deleted or, as long as the app exists you need to remember that some users didn’t provide an email (business pov) and the Email property/column can be null/empty (implementation).

Conclusion

Every business changes in time, the only difference is the pace. When dealing with a new, vague, volatile domain the pace is very fast but in the end you’d have the same issues you’d have when the domain changes at a slower pace. It’s harder because you have to grow yourself into a Domain Expert but from an application design and implementation point of view, things will be very similar. In the end, what makes the app maintainable is how we’ve applied the principles behind DDD/ES/CQRS. Recipes, libraries and frameworks are just tools that should be used according to the above-mentioned principles.

How To Handle Business Rules in Domain Driven Design

Wed, 23 Aug 2017 00:00:00 +0000

The main point of DDD is to identify relevant domain behaviour, which means getting to know plenty of domain rules. Now, the tricky part is we have domain rules at different levels and all of them are important. Let’s start with the simplest ones.

Value objects (VO)

We’re using VOs mainly for their business semantics but a lot of them encapsulate simple business constraints. A VO implementation guarantees that value is valid from a business point of view. And there can be many rules involving that value, however, at this level it’s more of basic rules like: “quantity > 0”. In some cases you might more complex validation rules and in that case, a Factory even a Domain Service are better suited to encapsulate those rules.

For example, I might have a TransactionDatethat has 2 rules: it can’t be a weekend day and it can’t be an official holiday. It’s easy to enforce the first rule, DateTime has properties for that, but hte second rule clearly is out of the VO scope. And since calculating holidays is not domain behaviour, the best thing is to have a Factory that will always create that VO.

If you’re thinking: “But what about restoring it from the database?”, I’d argue that using a CQRS approach means VO are always created and stored, while a Read Model (of that VO) is restored. At least this is what I consider to be the most maintainable approach.

To view things in a simple manner a VO = specific data + very close related business constraints.

Aggregates (Agg)

An aggregate by its definition is a group of ‘lower level’ concepts that need to always consistent. Technically speaking, an Agg is literally a group of value objects + Agg level domain rules. Note that these are rules that are required to maintain the aggregate consistency i.e rules that keep things valid and prevent the Agg entering an invalid state.

I will digress a bit here, because from the domain rules point of view the Agg contains validity constraints, while from a consistency point of view the Agg defines a consistent area in our business model, which technically speaking is a Unit of Work. From another point of view, the Agg works only with VOs (these are the Agg’s ‘data’) which themselves are a mix of data and business rules.

So, which rules belong to the Agg? The ones which involve the role and the place of the VOs inside the Agg. Stuff like: “all Agg components are required”. Never rules that involve the Agg itself as part of a bigger operation.

Actually, the hardest and the most important part of identifying an Agg is to identify the relevant VOs, the Agg rules themselves are quite easy to spot. And if your business rule target the Agg as a whole then it’s an ‘outside of the Agg’ rule that should be part of a Domain Service.

Domain Services

Most of the obvious business rules which don’t validate simple values will fit here. You know that “username must be unique” rule? That’s the one! Or “the user can post at most 15 videos” etc. A lot of developers mistakenly put this as part of the Agg which itself is improperly modelled, resulting in a long term mess waiting to happen.

These should be part of a Domain Service and depending on the rule, it can be technically trivial or not, to implement it.

Business Impact

Yeah, we have to talk about that ‘cuz the rules can have an… impact… on how simple or complex or maintainable your code will be. And that translates into how quickly you will deliver functionality aka productivity, how much technical debt you’ll going to acquire and how expensive (in money or work-hours) enforcing a business rule will be.

Here it’s something you have to talk to the Domain Expert and the project owner. In the end everything boils down to what’s cheaper for the business: to enforce a rule 100% or to accept occasional violations.

Let’s take the “user can post max 15 videos” rule. The simple implementation is to read your business state (read model for CQRS) and find out how many videos that user has. The only problem is concurrency (and not eventual consistency). What happens if the user presses the button twice fast or something.

It’s a fact of life that everything is (perceived) delayed. Even with the fastest hardware and there’s still going to be a delay from the moment you sent that query until you get the results. 1 microsecond before or after someone changes things. It’s inevitable.

And that matters when you’re dealing with high concurrency. Because at one point the business rule will be violated. The question is what happens next. Sure, you can come up with some complicated solution to enforce it, but is the Client willing to pay the price? Maybe is cheaper to ignore those edge cases with very little probability to happen and possible 0$ business impact. Or that rule needs to be enforced at all costs, no matter what.

What if the rule is very important but it’s a line of business app used by at most 5 people with close to 0 chances to become a high concurrency app? We can implement a very simple solution which takes advantage of that and we’re very aware that won’t be scalable past a specific number (that we hope it won’t be achieved). As always, it depends, but you have to be aware of both the technical and business context. And there’s no single best solution that works for every situation.

Luckily, very few applications need 100% percent enforced rules and are highly concurrent. And for those cases, you need very specific solutions.

In implementing rules, we look for the simplest solution and try to evaluate the probability and impact of the edge cases.

Conclusion

Business rules can be found everywhere in the domain and it’s our objective as domain modellers to assign those rules to the relevant patterns. And probably you’ll be surprised to find out that most rules are part of VOs and Domain Services. That’s why properly understanding all the patterns is the key to success: all are equally important and we should let the Domain tell us what belongs to where, instead of playing favourites (I’m looking at you ‘Aggregate’ classes full of primitive type properties).

DDD Decoded - Domain Relationships Explained

Wed, 24 Aug 2016 00:00:00 +0000

One of the most trickiest things to understand in DDD is the domain relationship between 2 concepts. Most of the time when people think relationship they use the programmer mindset and they look for: has-a or is-a or parent-child or (worse) one-to-many etc relationships. Which is valid when you write code but absolutely wrong when you do domain modelling.

What we’re looking for is a Domain Relationship i.e how the Domain sees the relationship from a business point of view or, to be more precise, what is the level of association/partnership between the concepts and what business rules are involved in maintaining the relationship. And usually there are 2 types: strong/always and weak/optional.

Strong (always) domain relationships

This one is the easiest: it simply means that in a given business case, a concept always needs the other. Examples: Customer and Order, Author and Tutorial etc. Contrary to how many devs think, it’s never “Customer has orders”, it’s always an action about an Order which might involve or not the Customer. When the customer places an order, we need to create that order and we’re going to use a specific Order aggregate. But orders don’t just appear from thin air, a customer is always involved so we can’t create a new order without mentioning the customer.

Order concept requires at its creation a Customer so, in our Order model, we need to find the representation of the Customer that will be used by the Order aggregate. In most cases, we only need the simplest model that represents the existence of the Customer, so we’ll use its id. That id is a Value Object and will be a part of the Order aggregate. We don’t care about a Customer aggregate, because we don’t need one for this business case. The Order is the main concept, Customer is secondary.

However, if we are in a “Cancel order” case, there is no Customer-Order relationship to care about (there is an Order-OrderStatus one, though). So, we can cancel the Order without involving/mentioning the Customer, but, as I’ve said, there’s a different relationship to take care of now.

Let’s say that an Order always needs to have a status. It might be tempting to include it as part of the aggregate but… if you look at it like the business does, it makes no sense for this Value Object to be part of it. What makes sense is to consider the Order Status as being a sort of metadata associated with an Order.

When the Order is created, the only place where this relationship should be represented is the resulting OrderCreated event. That’s because a status like “Pending” is implicit, we don’t need any particular input or business constraint for it. But we still need to ‘announce’ that the order has that status, because it is part of the business state change.

Now, when cancelling an order, we need to specify a different status for the order, however because we can have different outcomes based on the existing order status, we need to identify an aggregate just for that. This aggregate involves the Entity Order (via OrderId) and the Value Object OrderStatus and while being a model specific to changing the order status (representing the relationship itself) the resulting change is still associated with the Order concept.

Using Event Sourcing, this means that the OrderCanceled event is considered to be part of the Order and so, the entity’s id is the order’s id. But the aggregate is about the relationship between Order and OrderStatus, it’s not just an Order aggregate. If this sounds weird, I can only say that it will make sense with more experience.

Weak (optional) domain relationships

Basically, 2 concepts can be associated together. Think Post and Category. Both concepts are independent, but they can work together. In the business case “Assign post to category” we need to create the association between them according to business rules. The relationship aggregate will involve both concepts and we get an interesting situation, because we end up with 2 entities but we need only one to act as the aggregate root. Which will it be?

Clearly, we shouldn’t just flip a coin. We need to understand the concepts better as well as the purpose of their association. It turns out that Category exists to organize posts, while a Post really doesn’t care about categories. This relationship is more important (relevant) for the Category so, we select it to act as the aggregate root. This means that in the resulting event, the entity id would be that of the Category while PostId will be just a field.

Being a relationship, even if changes are considered to ‘belong’ to a specific concept, the aggregate is always a model for the relationship.

An interesting example is deleting something. If I soft delete a post, what I have is in fact a new relationship between the Post and Deleted status, the status is never part of the post itself (as a concept) but always some metadata associated with the post. Btw, the status is a Value Object even if its implementation is just an enum.

Another example can be “Pay invoice”. Yet again, a relationship between an Entity (Invoice) and a Value Object (InvoiceStatus) . The status is metadata for the invoice and we need a relationship aggregate to change the status. From the domain point of view, something associated with the Invoice entity has changed.

Conclusion

The hardest part about domain relationships is to properly identify them; many times, especially when an Entity and a Value Object are involved, we can think that the VO is part of the Entity’s aggregate, when in fact it’s a relationship that might need its own aggregate. But with more practice, spotting relationships will become second nature.

DDD Decoded - Modelling with CQS

Mon, 22 Aug 2016 00:00:00 +0000

While CQS/CQRS are a bit newer than DDD, they work so well together, one simply has to use it. And I don’t mean CQRS from an architectural point of view, but from a modelling point of view.

Simply put, when we identify a business case we ask ourselves: “Does this case has the intention to change the business state”? We’re not talking about a particular state (objects, tables etc) but about business state as a whole (remember that in real world any change is implicitly persistent). If so, then it’s a command case else it’s a query case (this is CQS at work).

Being in a query case means that you know you won’t be changing anything and that the models will be read-only (this is CQRS, because we end up with specialised read models).

But in a command case, things are a bit different. Many concepts can be involved however, usually only one will be represented by a command model. The other concepts will be represented by read models. We apply CQS for each concept and we end up with specialised command/query models for each, basically CQRS (not to be mistaken for a CQRS architecture, which is a different thing, but based on the same CQS principle).

As an example, let’s say we have the Create invoice business case. Clearly, the business wants to retain the new invoice, so our business case will change the business state. We’ve identified a concept too, the Invoice for which we need to find a relevant representation. However, because we’re creating the invoice, it means we need a command representation i.e an Aggregate.

That’s great, but there’s more concepts involved besides the Invoice. We need to get the products and prices from an Order, we also need to calculate Tax and so on. Each of these concepts have a model as well, but because we don’t need to change the business state for which those concepts are in charge, it means we’re going to have read models representations. So, the Order model will be some read-only structure which contains all the data needed by the invoice. We always try to identify the most relevant model for that specific case, and not a generic model good for everything.

As a generic ‘rule’, consider the business case as being like a bounded context i.e it has a model which makes sense only inside it. Concepts are involved in many business cases, but we work only with their most relevant models and based on the action we need, either write or read, we end up with a command model or a query model for each concept.

So, in a command case, we can find both command and query models of different concepts while in a query case, we’re dealing only with read (query) models. Applying CQS early when modelling helps us to know upfront what types of models we’re looking for, which gives us a bit more clarity and a productivity boost.

DDD Decoded - Application Services Explained

Fri, 19 Aug 2016 00:00:00 +0000

We have all those domain models, aggregates and domain services but they are just parts of business cases, floating around. We need something to put things together, to orchestrate the fulfillment of a specific business case. We need a manager of sorts and in DDD that role is performed by an Application Service.

What does an Application Service (AS) actually do?

The simplest way to look at it is as the ‘hosting environment’ of a business case. It takes care of invoking the correct domain models and services, it mediates between Domain and Infrastructure and it shields any Domain model from the outside. Basically, in a DDD app, only the Application Service interacts directly with the Domain model. The rest of the application only sees the Application Service (interesting choice of name).

Business functionality is expressed as business cases and the AS acts as a shell, encapsulating one business case (it should anyway, in practice we can host a simple process i.e more than one business case, but that’s more of a pragmatic compromise). This means the UI/API or some higher layer talks to the AS responsible for that requested functionality and the AS gets to work. At most, the calling layer receives some result which shouldn’t be nor contain a domain model i.e entities or value objects.

It’s important to note that an AS doesn’t have any business behaviour. It knows only what model to use but not how that model works. So, the AS knows which Aggregate to invoke, it knows about some Domain Services that might be required, but that’s it.

An example

Let’s continue the money transfer example. But now, we have the business rule that says the transfer can be done only if the account balance has enough money. So we’re introducing 2 Domain Services: Calculate account balance and Can account be debitted both implemented as functions of a IDomainServices abstraction. But we also need an AccountBalance Value Object.

For obvious reasons, the code is heavily simplified. Also, this is just one of the possible implementations. It’s a matter of style in the end, as long as the code is clear and respects the domain model you can go wild with the implementation.

  public class AccountBalance
    {
        
    }

    /* Domain Services implementation */
    public interface IDomainServices
    {
        AccountBalance CalculateAccountBalance(AccountNumber acc);
        bool CanAccountBeDebitted(AccountBalance balance,Debit debit);
    }

    /* abstraction representing the query model, implementation resides in Infrastructure */
    public interface IDomainQueries
    {
        AccountNumber GetAccountNumber(string number);
    }

    /* Event store abstraction, basically our 'repository' */
    public interface IEventStore
    {
        
    }

    //command object, data structure
    public class TransferMoney
    {
        public Guid Id { get; set; }
        public string AccountFrom { get; set; }
        public string AccountTo { get; set; }
        public decimal Amount { get; set; }

    }

    /* Application Service!!! */

    public class TransferManager
    {
        private readonly IEventStore _store;
        private readonly IDomainServices _svc;
        private readonly IDomainQueries _query;
        private readonly ICommandResultMediator _result;

        public TransferManager(IEventStore store, IDomainServices svc,IDomainQueries query,ICommandResultMediator result)
        {
            _store = store;
            _svc = svc;
            _query = query;
            _result = result;
        }

        public void Execute(TransferMoney cmd)
        {
            //interacting with the Infrastructure
            var accFrom = _query.GetAccountNumber(cmd.AccountFrom);

            //Setup value objects
            var debit=new Debit(cmd.Amount,accFrom);

            //invoking Domain Services
            var balance = _svc.CalculateAccountBalance(accFrom);
            if (!_svc.CanAccountBeDebitted(balance, debit))
            {
                //return some error message using a mediator
                //this approach works well inside monoliths where everything happens in the same process 
                _result.AddResult(cmd.Id, new CommandResult());
                return;
            }

            //using the Aggregate and getting the business state change expressed as an event
            var evnt = Transfer.Create(/* args */);

            //storing the event
            _store.Append(evnt);
            
            //publish event if you want
        }
    }

This particular approach uses a message driven architecture as well as Event Sourcing. We see how the AS orchestrates the business case; the domain model isn’t aware of the command object, the event store or the result mediator. One thing that might be confusing is the branching, it almost looks like the AS needs to know the domain rules of what happens when an account balance is too low, however it doesn’t :) . That’s one of the “tell me if I can continue with the business case” type of situations and the AS uses a Domain Service to get an answer for that. Again, it’s a matter of knowing who is responsible for something, not how something needs to be done. The AS never micro-manages.

If you want to keep things even simpler, you can call this service directly from the UI/API layer, and make Execute() return a CommandResult. We can implement things as complex or as simple we want, as always, it depends on many factors.

Conclusion

The Application Service is the host of a business case and acts as a mediator between the app and the domain model. As long as you keep the domain behaviour inside the dedicated patterns and none leaks into the AS, you’re good to go. Implementations vary and there’s not a recipe of how a “good” AS looks like. Just remember its role and respect the domain model, the actual code is up to you.

DDD Decoded - Domain Services Explained

Tue, 16 Aug 2016 00:00:00 +0000

Domain services are a bit confusing at first, when you don’t know exactly what a an Application Service is. Also, many developers try to cram a lot of business rules in their Aggregates, when a Domain Service (DS) would be more appropriate. But let’s start with the beginning….

Why do we need Domain Services?

Some business rules don’t make sense to be part of an Aggregate. For example, you want to check an account balance before debiting an account. Or you want to see if a certain operation is allowed by the business rules (not to be mistaken for user authorization). Or you want to perform a simple calculation according to domain rules. Basically, any business rule required to move forward a business case, which doesn’t belong to an aggregate should be a Domain Service. This is the DDD term for business behaviour outside an aggregate or a value object.

How to identify a Domain Service (DS)?

The easiest way is to simply check if the rules are having to do with business constraints required to maintain an aggregate invariants, including its value objects. If they’re not, they’re a DS, even if it seems related to that aggregate somehow. Many times you need to generate a value object that will be part of the aggregate. For ex: you need a Tax Calculator behaviour which will generate a Taxes value object which is a part of the Invoice Aggregate.

In other cases, you might need to allow an operation. Remember the transfer money example? Wha if we have a rule that says that you can’t debit the account id the amount is lower than the balance? In this scenario we’re actually dealing with 2 Domain Services: one is used to calculate the AccountBalance Value Object (VO) the other encapsulates the “amount must be greater than the balance” rule.

What about the Anaemic Domain anti-pattern?

In a business case we can use multiple DS and this might look like the Anaemic Domain. But it’s not, the reason being that Aggregates should be as small as possible, not because someone said so, but because they should contain only the relevant behaviour for that model. Not every related behaviour. If something is ‘outside’ an Aggregate, then it’s probably is a Domain Service.

Implementation tips

A DS is just a name signaling business behaviour. It doesn’t mean you have to implement it in one way or another. In many cases you can implement all the domain services from that Bounded Context as (static) functions in one class, while in other cases you might want one class per DS. As with everything, it depends.

A DS should be visible and consumed inside that Bounded Context only! Yes, you can define interfaces that can be used by your application service, they’re great for testing, however their concrete implementation should be in the same BC as the business cases where it’s used.

External services

Let’s say we need to calculate tax but the domain expert says they’re using some website to do it (and luckily for you, it provides an API and a client library). We need that functionality, but it’s implementation is not part of our Domain. This is what I call an External Service. The easiest way to use it is to define an abstraction (interface part of your BC) that will act as if it’s a Domain Service, however its implementation will be part of the Infrastructure and it will act as a wrapper around the client library. This is how we keep things decoupled. If later the calculation will be performed in-house, just implement a new class inside that BC and reconfigure the DI Container. Simple stuff.

What if we need a service which is part of our app but part of another BC? For a monolith, you can cut corners and use it directly (assuming you weighted in the consequences). For a distributed app, I’d suggest the External Service approach. In the end, for the BC it’s something outside its boundaries, it doesn’t matter where the actual functionality is implemented as long as it’s not inside the boundaries. For the BC’s point of view, it’s an external service.

Conclusion

We have Domain Services simply because we want to keep a concept’s model relevant, so any behaviour which doesn’t naturally fit that model needs to be expressed somehow. Also DS shouldn’t care about state, they represent domain behaviour only (their implementation should be stateless).

DDD Decoded - Bounded Contexts Explained

Fri, 12 Aug 2016 00:00:00 +0000

In DDD, we organize the Domain into Bounded Contexts(BC), with at least 1 BC. An important pattern, the BC is a bit tricky to “get” and to explain, but I assure you that you need it for proper DDD and it simplifies things on the long run.

What is a Bounded Context?

What if I told you that you’ve been using the bounded context principle for a while, without knowing it? You know those UI, Business and Database/Persistence layers? Those are literally bounded contexts, an implementation of the separation of concerns principle. A complex Domain can be considered a bunch of functionalities, but we like to group them into ‘specialized’ modules, where each module is responsible for a high level concern.

If the Domain would be a company, the BCs would be its departments: accounting, HR, marketing, production etc. Each with its own responsibility, different but working together. And since DDD is about being Domain driven, we want to design our application similarly to how the real domain(business) is organized.

Why do we need a Bounded Context?

It’s more than just mimicking the business’ structure. The keyword here is bounded, that is, each BC has boundaries, limits that isolate the model from other BCs(if there are more than one). Actually, the boundaries are the main benefit of a BC because they ‘contain’ a specific model, allowing us to focus on it. We can say that the main utility of BC is that it allows better decoupling, which is the most important trait of maintainability. Basically, we group together related models while keeping them separated from other models.

And like everything else in DDD, we aren’t the ones designing or deciding BCs, we identify them. The business already knows what responsibilities and limits each department has, we’re just putting that information together.

How we identify a BC?

Well, we pay attention to the language. The ubiquitous language is not just a DDD buzzword. It means that the business language has the same meaning in a certain context. Invoice means something to Accounting, but it can be just the name of a class for a programmer. Just because the name is identical doesn’t mean it’s the same concept. And Marketing can say Customer and Accounting can say Payer but they can both mean the same thing for the business as a whole.

The important part here is that names are by themselves irrelevant. We need to understand the concept’s definition that makes sense in that context in order to place a business case in a certain BC. Many times is quite easy, Create an order is part of ECommerce but sending the order’s confirmation email is clearly part of a different BC, something like Marketing or Sales. How you send the email it’s an implementation/infrastructure detail and we’re not interested in that (at this point).

How do the BCs communicate?

Since the model of a BC makes sense only inside that BC we can’t just use (refer) other BC’s model directly. But in many cases we need information available in another BC. How can we get it, without breaking the boundaries?

Enter Domain Events. They represent changes of the global business state, but they do have another, very useful technical trait: they are messages, simple data structures. They are no longer a model , they are simply information and they don’t belong to a BC, they are domain wide valid.

If one BC is interested in data from another BC, it will just subscribe to the relevant events and then it will use that data to maintain its very own read model (yes, that’s CQRS in action). And since messages are data and not part of a model, boundaries are not violated. All this should be part of the BC’s own infrastructure.

But what about invoking a business case which is part of a different BC? When you need that, it means you’re dealing with a business process, a sequence of business cases, however, even if a business case belongs to a BC, the process itself doesn’t and we’re going to have a process manager a.k.a saga in charge, which is a technical implementation detail. When we identify a process, we care about which business cases are part of it, the manager itself doesn’t exist as part of the domain.

A business case shouldn’t invoke directly the next business case i.e it shouldn’t act as a part-time project manager; in order to achieve decoupling and to maintain boundaries, business cases don’t know anything about other cases, it’s the process manager’s job to know and to invoke the next case.

In special situations…

..you might want to couple one BC to another, because it’s the easiest way. It can be a valid, good enough solution, but you have to be careful. The trick here is to find the right compromise between decoupling and easy implementation.

Conclusion

The Bounded Context concept is very important for the maintainability of the app. It allows us to deal with relevant models that don’t overlap. It’s important to note that this is a logical grouping criteria and we can implement everything inside a monolith. But if the app needs to be scalable and we go distributed, then we may want to implement one BC per app/process/server.

DDD Decoded - Entities and Value Objects Explained

Fri, 29 Jul 2016 00:00:00 +0000

One of the staples of DDD mindset is the partitioning of business concepts into: Entities and Value Objects . Notice, that I’ve said concepts not objects. The difference is that an object might be an implementation of a model of a concept. It’s not about how we write code, it’s about how we ‘label’ a business aspect, in a more developer friendly manner.

Why do we need these tactical patterns?

One practical advantage of DDD is that it tells us how to organize domain information in a way that we can implement it easier. Once we know we’re dealing with an Entity or a Value Object, we get some hints about how to continue modelling or how an implementation looks like.

Entities are concepts whose instances are uniquely identifiable

Actually, it’s a bit more: yes, they all have one immutable, read-only aspect or detail (call it however you wish) that acts as an identifier, but the thing with an entity is that we can change everything related to it (except its id) and it remains the same instance. It sounds a bit abstract and dry, but things are usually simple. It’s quite easy to identify a concept that is an entity: the domain expert will refer to it as a single, identifiable item. Customer, Invoice, Order, Article, Post etc are examples of common concepts which are entities. As long as the business care about tracking each instance of that concept, we’re dealing with an Entity.

In many cases, you get the hint directly: the domain expert will mention a unique number or unique id or serial number etc as being part of that concept definition. Even more, when we identify models for business cases which change the instance of that concept, we keep seeing the identification detail mentioned every time.

What being an Entity tells us

The most important hint is that an entity designates a ‘bigger’ concept, therefor we’re dealing with an aggregate and we need to ‘dig’ deeper in order to find out its composition and its business rules. Another thing is an entity can’t part of an aggregate of another entity. But we can have references (not the best word) that is, an aggregate can ‘point’ to another entity. Maybe a better way of saying it is that when we have a domain relationship between 2 entities and one ‘needs’ the other one, the expression of it is a reference a.k.a the id of the other entity.

An example is an Order is always placed by a Customer, so the Order entity has a relationship with the Customer concept, in the sense that we need to represent the Customer as being part of the Order (Create) aggregate. But since Customer is an Entity, only its id will be part of the Order aggregate.

Value objects are simple or composite values that have a business meaning

A reminder that early DDD was mixed with OOP, a better name for the Value Object(VO) would be a Value Concept. But the name stuck so we keep saying Value Objects even if its implementation is not an object. VOs usually are not treated with the same respect as the Entities, however they are equally important. It’s not that hard to identify a VO, it’s a concept that doesn’t have an explicit identity detail. Actually, we can say that the identity of a VO is represented by all the values that VO has. Change something and it becomes another value.

VO not only have values, but they incorporate business constraints that the values needs to respect. Basically, a VO is a ‘smaller’ concept, which is part of a (big concept) Entity. Most VO are small enough, 1-2 values but we can have bigger VO which combine other VOs.

Let’s take an example: A Price is a concept which is represented by 2 values: Amount and Currency (itself a VO). It doesn’t have an explicit identity and most importantly, the business doesn’t differentiate between one $5 and another $5.

Another example is an Order’s ordered product, a detail of the Order Entity. And no, I haven’t seen any business talking about ‘OrderLines’, but they talk about an order’s Items. The VO OrderItem is a composite of 3 things: Product, Quantity and Price. As a concept, Product is an entity and a VO can’t contain Entities so what we’ll have is a ProductId (or SKU) which itself is a VO. And it might seem that OrderItem has an identification detail, the product, used to identify a specific item from the order and making the item look like an entity, but the important thing is that OrderItem is a component of the Order, a minor concept which isn’t used directly outside the Order. A business can’t identify an OrderItem only by its ‘id’, it always needs the Order itself to act as a context for that ‘id’. That’s what makes it a VO, a true entity doesn’t need another entity to be identifiable.

Sometimes is tricky to identify the nature of a concept, it might look like an entity, however if it represents a minor concept which make sense only as part of another Entity, then we’re dealing with a VO.

What a VO tells us

Business Constraints - a VO communicates business semantics and usually this means those values need to respect business rules. A VO is always valid.
Immutability - due to its nature, a VO never changes. It can’t change or else it becomes another value. So, set its value(s) once and that’s it.
Usually a component of an aggregate - Business functionality deals with Entities, it doesn’t care about a stand-alone VO instance. Ideally, all components of an aggregate are VOs.
Semantics > Structure - Price has an amount and a currency. Discount has an amount and a currency. Are they the same concept? No, and the business cares about that. Even if 2 VOs have identical structure and business constraints they aren’t the same and they should be implemented as different things. DRY doesn’t apply here, never reuse VOs!

These hints make it easy for us to implement a VO and personally I go for an object with business rules enforced in the constructor plus getters. We can have methods but those methods should never change the VO, you can only create new VOs.

In some cases, the VO implementation can be just a simple enum (think OrderStatus: Pending - InProgress - Completed), no need to complicate our life.

When CQRS is involved

While the nature of a concept is the same, regardless if it’s a Command or a Query, these patterns make sense only for the Command model. A query model is just some (read-only)data which can span multiple concepts. While we can use some VO for queries, it’s mainly a DRY convenience.

Conclusion

It helps to organize the business concepts using these tactical patterns, as long as we identify things properly. The most common mistake I see is devs who point to a data structure full of primitive types and say:”I have this Entity”. Do not confuse the nature of a concept with a possible implementation of one of its command models.

DDD Decoded - Don't Fear Eventual Consistency

Sat, 23 Jul 2016 00:00:00 +0000

Inevitably when talking DDD, someone asks: “It’s all great with those aggregates, events and stuff, but how do I query things?”. Inevitably, the answer is:”Use CQRS” and inevitably, a new issue appears: “You have to account for Eventual Consistency (EC)”, a necessary evil.

But I’m going to say this: The only people worried about EC are CRUD programmers.

Let’s go back in time 100 years

No computers, no CQRS, no EC. Or maybe…. Neah! John and Mary have a shared account at a local bank and it just happens that they decided to withdraw 100$ the same day. Unknowingly, they interact with different tellers, just a couple of minutes apart. Being an epoch without computers, for every operation needing to check an account’s balance the tellers need to talk to another clerk who’s in charge of maintaining the balances. At the moment T, the first teller goes and gets the account balance (it’s 100$). Then he starts to fill in the required paperwork, then handles John 100$. In the mean time, at T+2,the second teller (serving Mary) goes to the back-office clerk and gets the account’s balance. While he’s on the way back, teller #1 goes to tell the clerk that a transaction has occurred and the account balance needs to be updated. Teller #2 returns to Mary, handles the paperwork and gives her 100$. Then he goes to the clerk and tells him to register the new operation, thus updating the account balance.

John and Mary withdraw together 200$, from an account which only has 100$. When the clerk calculates the latest account balance, it gets a negative number. Dang! We have a problem! Does the bank blame it on CQRS and Eventual Consistency, heads will roll because nobody used a Unit of Work? Nope! The bank says: “Meh… yet another opportunity to make money! Start charging interest on the negative balance and notify the client they owe us 100$(+interest)”. Business as usual.

As we can see, Eventual Consistency exists without computers or CQRS. Like rain, it’s a normal phenomenon in the real world. And businesses exist in the real world, so for them EC is just normality, even if a domain expert doesn’t know what the words “Eventual Consistency” mean. And being normality, the business has a solution for this problem.

As programmers, we are trained , almost indoctrinated to pray to the ACID god. We feel fragile if 2 changes aren’t wrapped in a transaction and EC is like the boogie man, we fear it and try to avoid it. But this is just the CRUD mindset, a one trick pony that doesn’t reflect a moderately complex domain.

DDD is about changing our mindset from CRUD, data driven to business driven. And the funny thing is, not only that EC is pretty normal but it’s the default,too. Remember that we try to identify aggregates i.e we’re actively looking for areas, islands that need to be immediately consistent in an ocean of eventual consistency. Those are not in-your-face visible, we have to carefully ‘hunt’ them, in a way proving that only in those cases we need a unit of work.

And maybe that’s one of the biggest things with DDD, the revelation that a model doesn’t really need to always be immediately consistent, like in the CRUD approach; some parts need it, others don’t. Our objective is to identify which needs what.

So, don’t fear Eventual Consistency and try to go beyond the limited CRUD mindset. CQRS works great and usually the delay between sync-ing our event store to a read model is measured in milliseconds. In a world without computers, the delay is way bigger and if the business can survive that, it won’t care about a couple of milliseconds.

DDD Decoded - The Aggregate and Aggregate Root Explained (Part 3)

Thu, 14 Jul 2016 00:00:00 +0000

Coding time! I bet you’ve been waiting for this part for some time. Yes, once we have our model, it’s time to write the code. Let’s start with the Value Objects first.

public class TransferNumber
    {
        public string Value { get; private set; }
        public Guid EntityId { get; private set; }

        public TransferNumber(string value,Guid entityId)
        {
            //validate format based on domain rules

            Value = value;
            EntityId = entityId;
        }
    }

    public class AccountNumber:IEquatable<AccountNumber>
    {
        public string Number { get; private set; }
     
        public AccountNumber(string number)
        {
            //validate format based on domain rules

            Number = number;
            
        }

        public bool Equals(AccountNumber other) => other != null && Number == other.Number;

    }

    public class Debit
    {
        public decimal Value { get; private set; }
        public AccountNumber Account { get; private set; }


        public Debit(decimal value,AccountNumber account)
        {
            Value = value;
            Account = account;
            value.Must(v=>v>=0);//business rule
            account.MustNotBeNull();//ensure VO is valid            
        }
    }
     public class Credit
    {
        public decimal Value { get; private set; }
        public AccountNumber Account { get; private set; }


        public Credit(decimal value,AccountNumber account)
        {
            value.Must(v=>v>=0);//business rule
            account.MustNotBeNull();//ensure VO is valid            
            Value = value;
            Account = account;
        }
    }

Code should be self-explaining, although I bet you’re wondering about 2 things:

Why TransferNumber gets a Guid?
Why there’s no VO implementation for the creation date?

Well, let me start with no. 2. The creation date doesn’t need encapsulation as there are no actual business constraints (in this example). Why complicate the implementation with another class?

TransferNumber acts as a natural id for the Transfer, however, for technical purposes, I prefer to have a technical id too, hence the Guid. We’ll be using it in situations where we need to specify the entity, but we don’t need a full Value Object, for example in messages.

And speaking of messages, here’s our domain change , expressed as a Domain Event

 public class TransferedRegistered
    {
        public Guid EntityId { get; set; }
        public string TransferNumber { get; set; }
        public decimal Amount { get; set; }
        public string DebitAccountNo { get; set; }
        public string CreditAccountNo { get; set; }
        public DateTimeOffset CreatedOn { get; set; }=DateTimeOffset.Now;
    }

A nice, flattened data structure, containing valid data. Valid, because it’s the Aggregate Root (AR) who’s in charge of its generation. Now, I’m going to use a more “exotic” approach for the AR’s implementation.

 public static class Transfer
    {
        public static TransferedRegistered Create(TransferNumber number, Debit debit, Credit credit)
        {
            number.MustNotBeNull();
            debit.MustNotBeNull();
            credit.MustNotBeNull();

            debit.Account.MustNotBe(credit.Account);

            var ev=new TransferedRegistered();
            ev.EntityId = number.EntityId;
            ev.TransferNumber = number.Value;
            ev.Amount = debit.Value;
            ev.DebitAccountNo = debit.Account.Number;
            ev.CreditAccountNo = credit.Account.Number;
            return ev;
        }
    }

Wait… what?! Static class??? Static function???!!! Say what?! Yeah, it’s called a functional approach. I prefer a hybrid OOP-FP style to code DDD models, especially ARs. Why? Because it’s the simplest implementation. Remember that AR is a role , and the function is the implementation. It makes little sense to make it a full class, when a function is sufficient.

Now, sure, I may have another command case involving Transfer but you see, each model is relevant to one case only and I want my code to reflect that. Basically,I want some boundaries between cases, so the class Transfer is the concept and each static method is an AR enforcing a specific model. Things being static it means they shouldn’t share any state. They’re grouped together only as a convenience.

Our AR makes sure the business rules are respected and then it communicates the change by generating and returning a domain event.

This is not the only way to implement our model, but I like it since it keeps things simple and our code is Event Sourcing friendly. In a future post, when we’ll talk about Application Services, we’re going to see how the AR is used by the service and what to do with the event.