
Can you imagine your team deploying to production every day?

I’ve worked in some teams that deploy to production multiple times a day, and some teams that do it as many times in a
quarter.

The former teams:

👫 fostered a collaborative culture where all developers were responsible for to speaking to users, and paired and mobbed
relentlessly

🚦 had repeatable and reliable deployment pipelines that could verify any change’s suitability for deployment in minutes

🧐 maintained robust monitoring and observability setups that helped them quickly diagnose issues

Do you know what they also did?

They decoupled deployment from release.

Thanks to their highly collaborative culture, the teams were only ever working on one or two things at a time. There was
a sustainable and steady flow of work through the teams. They all clocked off at 5pm having achieved a lot.

Often, work in progress was deployed to production 😮

But most of the time it was entirely hidden. The new code just wasn’t externally accessible.

Other times the code was visible, but some of the legacy code was yet to be migrated to the new interface.

Seldomly, they used feature flags to hide the functionality. This was less preferable though as it complicates testing.
Which combination of feature flags settings do you test with?

Have you ever worked in such a team? If so, reach out to let me know!️ 



I have been part of a lot of teams that estimate the size of the stories on their backlog.

Every Sprint, the team dedicates time to refining the backlog. Beyond debating and negotiating the acceptance criteria,
the team rightfully ask whether the story in question could be broken down into a smaller story.

Then they size it. Some teams use Fibonacci numbers to do this. Others like to use T-shirt sizing. Your milage may vary.
Nonetheless, time is spent debating its size and coming to a conclusion.

At the beginning of the next iteration, the Sprint Planning meeting comes about. More time is spent deciding whether the
Sprint is full enough. Some teams will review past Sprints to assess how much they've done previously. Someone points
out that the last Sprint was different to the upcoming one because of some unplanned work popped up out of nowhere.

Then comes the daily stand up. With it only being day 2 of the Sprint, most of the stories lie in the 'Not Started'
column. They mentally weed out the stories they've not started so that they can talk about the progress on the couple
they have.

Next, one of three things happen:

1. The team completes all the work in the Sprint, and decide to pull in more work, not after giving themselves a little
   metaphorical pat on the back for beating their prediction of course.
2. The team complete the Sprint having completed all the work and nothing more. They must be really good at estimation
   you tell yourself. It's a shame that this is the first time they've got it bang on in the last two months.
3. The team fails to get all the stories done in the Sprint. The next retrospective is spent debating what went wrong,
   and what they can do to estimate better next time. Sad panda emoji are aplenty.

This is a lot of work that could have been avoided. The goal of an agile team isn't to judge themselves on their ability
to estimate work. The real goal is to provide value to the business as quickly and cheaply as possible, running small
and cheap experiments to learn whether or not they're heading in the right direction.

What would happen if we just stopped all this estimation?

There is still a tonne of value in assessing stories to see if they could be broken down. Smaller stories allow you to
learn more quickly and at a lower cost. I wholly recommend checking
out [Fifty Quick Ideas To Improve Your User Stories](https://fiftyquickideas.com/fifty-quick-ideas-to-improve-your-user-stories/)
by Gojko Adzic and David Evans for help with this.

Furthermore, if you are maintaining a backlog, you should also make sure that stories are prioritised. This helps you to
make sure you're always working on the backlog items are the most likely to provide the best learning opportunities.

But is estimating the size of each individual story really necessary? What are you getting out of it?

I would encourage you to experiment with working without estimations for a little while. See how it goes. Does your
throughput increase? Do you commit to less work and spend less time context switching day-to-day? Give it a try and let
me know how you get on. 



During the development of an application or library, it is often the case that we need to call another piece of code
that *might* not behave as expected.

For example, imagine you were developing an application that allowed a user to delete a file stored on disk. We need to
consider a couple of scenarios:

- What if the file didn't exist?
- What if the application doesn't have permission to delete the file?

Likewise, connecting to a database is another scenario where something might go wrong:

- What happens if the credentials are incorrect?
- What happens when the database is down?

To write safe code, we need a way to call the potentially problematic code without the world blowing up in our face when
something goes wrong.

Often enough, the code that raises the fact that something isn't quite right is not code that you wrote yourself. This
is the case in the examples above - you'd delegate managing files to classes within the `java.io` and `java.nio`
packages, and connecting with databases to classes in the `java.sql` package. It will be these classes that figure out
that the file you're trying to delete doesn't actually exist, or that the database that you're trying to connect to isn'
t available.

Other times, you may have written the risky code yourself. Perhaps you have written an application service that allows a
user to change their email address, and you need a way of telling the code calling the application service that the user
who is changing their email address doesn't actually exist!

## How do I know that I'm dealing with risky code?

Without being an expert in all of the potential error states of the functionality provided by library code you're
calling, it is not always obvious what can go wrong. The good news is that it's not up to you, the client developer, to
figure it out.

It is the developer writing the risky code who is responsible for declaring that something might go wrong. They have to
say that something *exceptional* might happen. In other words, they have to declare that the method that they are
writing throws an Exception.

Consider the following example code:

```java
public Database connectToDatabase() throws DatabaseNotAvailableException {
  if (connectionManager.isDatabaseAvailable()) {
    throw new DatabaseNotAvaiableException();
  }

  return connectionManager.connect();
}
```

Notice that this code declares that it might throw a `DatabaseNotAvailableException`. In the event that the database is
not available, this exception is thrown, popping the `connectToDatabase()` method off of the call stack, and returning
the flow of control back to the calling method. If the database is available, the connection proceeds.

## How do I handle the exception if it is thrown?

If you call a risky method, you'd better be ready to handle the risk! Most of the time, you'll be dealing with what are
called checked exceptions. There's another type called - you guessed it - unchecked exceptions, which we'll come back to
later.

You'll usually handle the exception by wrapping the call to the risky method in a try / catch block.

```java
public long countItems() {
  try {
    Database db = connectionManager.connectToDatabase();
    return db.executeQuery("count * from items_table");
  } catch (DatabaseNotAvaiableException e) {
    // Let someone know that something went awfully wrong.
    return -1;
  }
}
```

This says "try to do the risky `connectToDatabase()` operation, but if something goes wrong, return -1 instead".
The `DatabaseNotAvailableException` thrown by the `connectToDatabase()` method is *caught* by the catch block, and
handles it by returning `-1`. If the Exception is never thrown, the query is executed, its result returned, and the
contents of the catch block are never executed. (Note that returning -1 is probably not the best way to handle a
database not being available, it just allows me to illustrate the point without getting distracted!)

However, you are not obliged to handle the exception. You can, if you choose, pass the responsibility of handling the
exception to the method that called you. You achieve this by declaring that the method also throws the exception, which
is sometimes referred to as "ducking" the exception.

```java
public long executeQuery() throws DatabaseNotAvailableException {  // 🦆
  Database db = connectionManager.connectToDatabase();
  return db.executeQuery("count * from items_table");
}
```

In this scenario, the method that calls `executeQuery()` is responsible for handling
the `DatabaseNotAvailableException`. It could do this by wrapping the call to `executeQuery()` in a try / catch block,
or again passing the responsibility up the call stack.

When calling a method that throws a checked exception, these are your only two options. You either catch it, or specify
that you throw it. In the Java world, this is known as "The Catch or Specify Requirement".

## How long can pass on the responsibility for?

You can duck exceptions as many time as you like. Even your `main()` method can duck the exception if you really want it
to - your code will compile just fine. Just don't expect the Java Virtual Machine to handle it for you; it's not that
clever. It will just shut down if and when it comes across such an exception.

## What is an exception anyway?

Good question. Did you notice the `throw new DatabaseNotAvaiableException()` in the example above? It looks like we were
constructing a new object. In fact, we were. Exceptions, are just a special type of Object. More precisely, they are
objects which extend the `Exception` class, which itself extends the `Throwable` class.

![Exception Class Hierarchy](/posts/exceptions-in-java/exception-hierarchy.png)

You won't usually throw an instance of the `Exception` class itself since it is too generic. Instead, you want to
provide the context behind what has gone wrong by subclassing either `Exception` itself, a built in subclass
of `Exception` such as a `LogicException`, or a subclass of one of your own exception types.

## Does that mean I can throw more than just Exceptions?

Yes! There's another type that extends Throwable - Error. The class hierarchy actually looks like this:

![Throwable Class Hierarchy](/posts/exceptions-in-java/throwable-hierarchy.png)

It's quite likely that you'll never throw or catch Errors yourself though. They tend to be used for problems that affect
the JVM itself, and so aren't involved in day-to-day application development.

## Unchecked Exceptions

Problems like a database not being available or a file not existing could happen at any time and need to be handled
within your application code for when the worst happens. However, other problems, such as accessing an index of array
that does not exist, are simply just the result of programmer error. In an ideal world, you would never write code to
handle those cases, you would just not write the bug in the first place.

For times when an API is used incorrectly in this way, a special type of exception, known as a runtime exception, can be
thrown. A runtime exception is simply an instance of the `RuntimeException` class (or a subclass of it), which itself
extends `Exception`.

![Runtime Exception Class Hierarchy](/posts/exceptions-in-java/runtime-exception-hierarchy.png)

Along with instances of type `Error`, instances of type `RuntimeException` are known as unchecked exceptions. This is
because The Catch or Specify requirement does not apply to them. After all, if you've made a programmer error, you are
much better off writing code to fix the bug than writing code to handle the exception caused by the bug. That said, you
can still catch runtime exceptions if you want to. There's nothing stopping you.

## Chained Exceptions

Recall the example above where we tried to count the number of items in a table, and where we returned `-1` if the
database was not available.

```java
public long countItems() {
  try {
    Database db = connectionManager.connectToDatabase();
    return db.executeQuery("count * from items_table");
  } catch (DatabaseNotAvaiableException e) {
    // Let someone know that something went awfully wrong.
    return -1;
  }
}
```

In reality, returning `-1` is far from ideal. What does `-1` mean? Is there a negative count? Can `-2` also be returned?
It would be far better if we communicated the issue back to the caller, but how do we achieve this without leaking low
level implementation details through our nicely layered architecture?

To maintain our levels of abstraction, we want to keep our exception classes aligned with the level of abstraction we
are currently in. Suppose that the above method existed within a class called `SqlInventory` that implements
the `Inventory` interface. Application services interacting with an inventory don't want to concern themselves with
exceptions about a database. For all they know, the underlying implementation of the inventory might use a file-based
storage mechanism, or a third party API.

We can avert this problem by instead throwing a new exception that's aligned with the language of the inventory, perhaps
an `InventoryException`.

```java
public long countItems throws InventoryException () {
  try {
    Database db = connectionManager.connectToDatabase();
    return db.executeQuery("count * from items_table");
  } catch (DatabaseNotAvaiableException e) {
    throw new InventoryException("Database not available");
  }
}
```

But what about all the information stored within the `DatabaseNotAvailableException`? We've just thrown it all away,
never to be seen again. This is where chained exceptions come in.

The various `Throwable` constructors allow us to pass a causing exception in as a parameter, letting us to "chain" the
exceptions together.

```java
public long countItems() {
  try {
    Database db = connectionManager.connectToDatabase();
    return db.executeQuery("count * from items_table");
  } catch (DatabaseNotAvaiableException e) {
    throw new InventoryException("Database not available", e);
  }
}
```

Now, when logging the existence of an `InventoryException` further up the call stack, the `getCause()` method declared
in the `Throwable` class can be called to retrieve the `DatabaseNotAvailable` exception and log the additional
information contained within it.

## Conclusion

Dealing with errors when programming is part of the job description. Databases fail, networks are unreliable, and files
become corrupted. Exceptions allow us to handle these errors elegantly, enabling the normal flow of our code to stay
focussed on the task at hand, and letting us explicitly deal with the exceptional cases independently.


Legacy blindness is a term coined by Eric Evans - the first time I heard it was when
watching [his talk at DDD Europe 2018](https://youtu.be/T29WzvaPNc8?t=432). In the talk, Eric defines legacy blindness
as the state of the models and language of legacy software being so ingrained in the way that we think about a domain
that we are unable to see other options. He also notes that this is a particularly strong force when the legacy is a
good one.

On the past few software projects I've worked on, I've observed exactly this phenomenon, and have witnessed first hand
the effect it can have on a project.

Part of our job as software developers is to talk to business experts, and drill down into the domain, the events that
occur, the objects that we might model, and the rules that govern the way that the business works. In doing so, we learn
the vocabulary that the business uses to talk about their processes. We can then use that to create useful models in the
software that are able to evolve and accommodate new requirements as they come up by closely mirroring the real world
processes.

To quote Eric Evans again (this time from [his talk at DDD Europe 2019](https://youtu.be/pMuiVlnGqjk?t=291)):

> In almost every project we are working in a problem space where there is already a lot of software; our software will
> have to coexist with that software.
> Perhaps we're talking about a refinement of the existing software. Perhaps we're talking about some new piece of
> software that will integrate with another piece of software. Or maybe we're talking about a new piece of software that
> is replacing a piece of existing software. But there is always existing software.

Often, the business processes are themselves defined (and constrained) by the existing software, and hence so is the
language used. This can cause issues for us as developers: It's safe to assume that if we are here, it is because the
software is being improved, or redeveloped, and so we wish the new software to be a better fit for the business use
cases, and solve the problems caused by the incumbent software.

However, if the way that the business thinks about the problem space is tightly linked to the current solution, it can
be difficult to solve these problems, and the team can find themselves effectively reimplementing the existing system.

## How do we avoid the trap of legacy blindness?

### Educating ourselves on the domain

It's easy as a developer to treat all problems the same - implement the logic, satisfy the acceptance criteria, and
never really worry whether you're working in ice cream distribution or car insurance.

However, to make your model truly useful and maintainable, and to also write the best software that you can, you
ultimately have to educate yourself in the domain in which you are working.

This will allow you to have more productive conversations with the domain experts, help you ask more specific questions,
and find edge cases or new requirements more efficiently.

If there is literature available in your domain, read it, and form your own mental models of the domain. You can align
these with the specific ones from the company, prod and probe your own understanding, and identify which aspects of the
vocabulary are driven by the domain, and which are purely constructs in the existing software.

### Discussing how the problem would be solved without software

If everything happens in the existing software, then rather than asking how things are done at the business, it's often
a useful technique to take a step back and ask how the problem would be solved in the days before software, or if
software weren't available to us now.

You'll find new words and concepts, identify different contexts (through physical hand off of paperwork for example),
and cut through the model imposed on the business processes by existing software.

### Event storming

If you're looking for a framework to base workshops around, event storming may be useful to you. It's a lightweight and
flexible way of investigating a business domain, and can also help get you out of the mindset of the existing software's
UI, getting back to the fundamentals with events, users, commands, external systems - universal truths of the business
that exist outside the existing software.

### Decouple ourselves from the existing software

It's usually dangerous to attempt to replace existing software all at once. As a result, there will be a time when our
software coexists alongside the existing software. Often, we will need to integrate the two.

It's important to decouple the new software from the existing wherever we can, so that the structures and language of
the existing system doesn't leak into our new software and affect our judgement and model.

An anticorruption layer is a technical solution that we can use to help us do this. We can isolate the code for
integration with the existing software within a separate module, and leverage infrastructure such as queues or event
streams to keep the old system up to date. Once we have replaced the existing software, the module can be unplugged,
leaving no sign in our new application that the replaced software ever existed.

## Learn from the existing software

While it is important to avoid the pitfall of accidentally rewriting legacy software line for line, the legacy software
is legacy for a reason - it will solve a lot of the business problems, and often get a lot of the modelling right.

Watch and question users using the existing software, and see which bits work well and which bits are causing the
issues. Keep an eye out for any workarounds or 'hacks' that users use to fit their business processes into the system.
Listen for any words used by the users or domain experts that aren't present in the software. Take note of these
translations - it's gold when a user points at a form field and says 'well this is *really* the...'

By making yourself familiar with the legacy software, you can also spot language that is legacy software specific, and
gently nudge the team towards using more useful and more accurate domain language when talking about requirements or
user stories, and when writing the UI.

## Summary

Step one of avoiding legacy blindness is to learn to recognise it. Try to get back to the fundamental business concepts,
and where the business wants to go, rather than getting hung up on how things are currently done.

Learn about the domain, collaborate closely with domain experts, and learn the lessons that are to be learned from the
existing software, while always refining your model to be the best it can be at reaching the goals of the project.



As regular attendees on the London technology Meetup scene, we have always enjoyed the various conversations we have had
with fellow Meetup goers over the years. They form a good part of how we grow as developers, providing us with insights
and opinions from a broader range of experiences.

Approaching the redesign of our site, we naturally wanted it to also foster discussions about the topics that we are
interested in, namely domain-driven design, continuous delivery and product development. Needless to say, we needed a
commenting solution.

## Disqus

The most ubiquitous standalone commenting platform out there is most likely Disqus. However, if you think you are
getting Disqus for free, think again. As is the way, it turns out that they have a little side business selling the data
on your commenters to advertisers: [http://data.disqus.com/](http://data.disqus.com/). At the time of writing, this
subdomain was not even secured with HTTPS. If I worked at Disqus, I'd probably be a little insecure too. They have no
shame in quoting "Every 30 days, Disqus collects 1.6 trillion data points across 2 billion monthly unique visits to our
audience platform."

Furthermore, after reading a damning indictment on David
Calhoun's [blog](https://www.davidbcalhoun.com/2020/ditching-disqus-migrating-away-since-it-has-become-a-monster/), I
learned that Disqus makes nearly one hundred additional HTTP requests. It turns out that not only is Disqus bad for your
privacy, it is bad for your site and the planet too.

## Evaluating Commento

Keen to find an alternative solution to Disqus, I started to review some of my favourite blogs for inspiration. The
answer came from Marco Behler's [blog](https://www.marcobehler.com/), which I have always found instructional. Its
clean, no-nonsense writing is backed by great commenting functionality, powered by [Commento](https://commento.io/). I
signed up to the trial and got to work.

## Local Development

An immediate frustration with Commento was the lack of support for local development. The hosted version of Commento is
configured with the domain at which you host your site, which is obviously not localhost:3000.

The solution to this conundrum came from [Remy Sharp](https://remysharp.com/2019/06/11/ejecting-disqus), who pointed out
that the Commento script inspects the `window.parent.location` object. The fix is simple - simply update the object to
point to your site's domain. Since our site is built with [Next.js](https://nextjs.org/), this involved using
a `useEffect()` hook in our guide page's component.

```javascript
useEffect(() => {
  window.parent = {
    location: {
      host: "www.kiteframe.co.uk",
      pathname: meta.commentoId,
    },
  };
});
```

## Consistent IDs

By default, Commento uses the browser's URL to determine which page's comments should be loaded. This sounds ideal,
until you want to change the page's URL as part of a site restructure or an SEO optimisation. In the event that you do
change a page's URL, you must update the div element containing the comments to include a `data-page-id` attribute as
follows:

```javascript
<div id="commento" data-page-id="/original/path/to/page"/>
```

Maintaining and keeping track of those URLs was going to be pain, and so I opted for a more robust solution.

The more eagle-eyed amongst you may have noticed that I set the pathname on the `window.parent.location` object
to `meta.commentoId`. With all our posts written in Markdown, we opted to include an UUID4 identifier in the Front
Matter of each guide, which is explicitly set as the page id. This conveniently decouples the Commento comments from the
page's URL, making future URL changes much simpler.

## Conclusion

Overall, I have found Commento to be a pretty straightforward way to support user commenting on the KiteFrame site. The
$10 / month ($99 / year) pricing is a great value for money given that we don't have to worry about the servers involved
in hosting it, not to mention that we also do not have to compromise our commenter's privacy in the process.

Have you, or are you considering using Commento on your site? Comment with Commento below, and let us know what you
think!



When getting started with the tactical patterns of Domain-Driven Design, you soon come across the concepts of Entities
and Value Objects.

Entities are objects with an identity, and are objects whose state we want to keep track of over time.

A client inside your accounting software would be a good example of an Entity. If a client informed you that they have
changed their name, you wouldn't want the system to lose track of the fact that they are still the same client just
because their name has changed. Indeed, if that were the case, clients would have a very simple way to get out of paying
unpaid invoices!

Value Objects on the other hand are immutable, meaning they never change. They can simply just be created or wholly
replaced.

A client's phone number could very reasonably be modeled as a Value Object. Once the number has changed, you probably no
longer care about the previous number. You would probably just overwrite it.

After a few good examples, you start to feel as if you have a good grasp on what exactly Entities and Value Objects are.

However, you later come across the concept of an Aggregate, and all of a sudden the picture becomes a bit less clear.

If Entities are objects that can change, and Value Objects are objects that can never change, where do Aggregates fit
into all of this? What exactly is an Aggregate?

The answer isn't as clear cut, but I will try and answer this question for you in the remainder of this guide.

The short answer is that Aggregates are neither Entities nor Value Objects, but are instead a cluster of Entities and
Value Objects that form a consistency boundary.

"What is a consistency boundary?", I hear you ask. It is a good question, and one that gets to the heart of the
misunderstanding that many of those new to DDD encounter.

To answer this question, let us first consider why we would cluster Entities and Aggregates together in the first place.

Imagine you are building the aforementioned accounting application, and you are designing the `Client` class. Here is
how an initial attempt may look:

```php
<?php

namespace Accounting\Domain;

class Client
{
    private string $clientId;
    private string $name;
    private string $email;
    private string $phoneNumber;
    
    public function __construct(string $clientId, string $name, string $email, string $phoneNumber)
    {
        $this->clientId = $clientId;
        $this->name = $name;
        $this->email = $email;
        $this->phoneNumber = $phoneNumber;
    }

    public function changeName(string $name)
    {
        $this->name = $name;
    }

    public function changeEmail(string $email)
    {
        $this->email = $email;
    }

    public function changePhoneNumber(string $phoneNumber)
    {
        $this->phoneNumber = $phoneNumber;
    }
}
```

**This guide is about Aggregate design, and deliberately leaves out extraneous details to allow us to focus on the topic
at hand. I also don't work in the domain of accounting, so please forgive any incorrect modelling.**

It is a good start! With not much domain code at all, you have supported four use cases:

1. Creating a client
2. Changing the name of a client
3. Changing the email address of a client
4. Changing the phone number of a client

However, a new requirement has just come in. The business have very reasonably requested that they want to be able to
raise invoices against a client. You take a look at your code, and implement the following changes:

```php
<?php

namespace Accounting\Domain;

class Client
{
    private string $clientId;
    private string $name;
    private string $email;
    private string $phoneNumber;
    private array $invoices;

    public function __construct(string $clientId, string $name, string $email, string $phoneNumber)
    {
        $this->clientId = $clientId;
        $this->name = $name;
        $this->email = $email;
        $this->phoneNumber = $phoneNumber;
        $this->invoices = [];
    }
    
    public function invoice(int $invoiceNumber, float $amount, string $dueDate)
    {
        $this->invoices[$invoiceNumber] = new Invoice($invoiceNumber, $amount, $dueDate);
    }

    ...
}
```

At a glance, this all looks very sensible! After all, if the business says that a client can have multiple invoices, why
wouldn't you put an `$invoices` property on the `Client` class?

However, what is the value of issuing invoices if you can't then later mark them as paid? The business had that thought
too, and now you have got a new requirement on your desk. Following the Law of Demeter, you create a new method on
the `Client` class that allows you to mark an invoice as paid.

```php
<?php

namespace Accounting\Domain;

class Client
{
    ...

    public function invoice(int $invoiceNumber, float $amount, string $dueDate) {
        $this->invoices[$invoiceNumber] = new Invoice($invoiceNumber, $amount, $dueDate);
    }

    public function markInvoiceAsPaid(int $invoiceNumber) {
        $this->invoices[$invoiceNumber]->markAsPaid();
    }

    ...
}
```

Unlike the other methods we have written thus far, `markInvoiceAsPaid()` is the first to reach into the Client Entity,
and mutate the state of an Entity held within it.

We have only focussed on the domain for now, but let's consider how this use case would appear from the application
layer's perspective.

Since the `markInvoiceAsPaid()` method belongs on the `Client` class, we must retrieve the client by its identifier,
allowing us to invoke `markInvoiceAsPaid()` before persisting the client instance back to the repository.

```php
<?php

namespace Accounting\Application;

class MarkInvoiceAsPaidCommandHandler extends TransactionalUseCase
{
    private ClientRepository $clientRepository;

    public function __construct(ClientRepository $clientRepository) {
        $this->clientRepository = $clientRepository;
    }

    public function handle(string $clientId, int $invoiceNumber) {
        $client = $this->clientRepository->clientOfId($clientId);
        
        $client->markInvoiceAsPaid($invoiceNumber);

        $this->clientRepository->save($client);
    }
}
```

But is all that really necessary? We only want to update the state of the invoice itself. Do we really need to go
through the hassle of retrieving the client from the Repository in the first place? Why can't we just retrieve the
invoice from an invoice Repository, and mark the invoice as paid directly?

```php
<?php

namespace Accounting\Application;

class MarkInvoiceAsPaidCommandHandler extends TransactionalUseCase
{
    private InvoiceRepository $invoiceRepository;

    public function __construct(InvoiceRepository $invoiceRepository) {
        $this->invoiceRepository = $invoiceRepository;
    }

    public function handle(int $invoiceNumber) {
        $invoice = $this->invoiceRepository->invoiceOfNumber($invoiceNumber);
        
        $invoice->markAsPaid();

        $this->invoiceRepository->save($invoice);
    }
}
```

Is there a downside to this approach? In this case, it appears not. Despite being contained within the Client Entity,
the Invoice Entities are not bound to the Client Entity by any business rule. It is possible to update them both
independently without having to worry about unwanted side effects or race conditions.

With this in mind, we could change our approach to invoicing clients. Before, the application layer mutated the Client
Entity directly. Instead, we could change the `invoice()` method on `Client` class to be a factory method, remove
the `$invoices` property, and save the invoice in its own separate Repository.

```php
<?php

namespace Accounting\Domain;

class Client
{
    ...

    public function invoice(int $invoiceNumber, float $amount, string $dueDate) {
        return new Invoice($this->clientId, $invoiceNumber, $amount, $dueDate);
    }

    ...
}
```

```php
<?php

namespace Accounting\Application;

class InvoiceClientCommandHandler extends TransactionalUseCase
{
    private ClientRepository $clientRepository;
    private InvoiceRepository $invoiceRepository;

    public function __construct(ClientRepository $clientRepository, InvoiceRepository $invoiceRepository) {
        $this->clientRepository = $clientRepository;				
        $this->invoiceRepository = $invoiceRepository;
    }

    public function handle(float $amount, string $dueDate) {
        $client = $this->clientRepository->clientOfId($clientId);
        
        $invoice = $client->invoice(
                $this->invoiceRepository->nextInvoiceNumberForClient($clientId),
                $amount,
                $dueDate
        );

        $this->invoiceRepository->save($invoice);
    }
}
```

With our new design, an invoice can be created without any state changes required on the client itself. This gives us a
few key benefits:

- Less contention - the independence of the Client and Invoice Entities means that they could both be retrieved and
  updated simultaneously.
- Greater encapsulation - the `markInvoiceAsPaid()` method no longer clutters the `Client` class.
- Improved cache-ability - changes to the client no longer invalidates cached invoices.

**The key take away here is that separating the Entities has not prevented the system from remaining in a consistent
state at all times.**

The bad news is that it is not always possible to make such a separation. What happens when the creation of an invoice
depends on some state held directly on the Client Entity? For argument's sake, suppose there is an outstanding invoice
limit set at the client level that puts a cap on how many outstanding (unpaid) invoices can be raised against the client
at any one time.

```php
<?php

namespace Accounting\Domain;

class Client
{
    private string $clientId;
    private string $name;
    private string $email;
    private string $phoneNumber;
    private array $invoices;
    private int $outstandingInvoiceLimit;

    public function __construct(string $clientId, string $name, string $email, string $phoneNumber)
    {
        $this->clientId = $clientId;
        $this->name = $name;
        $this->email = $email;
        $this->phoneNumber = $phoneNumber;
        $this->invoices = [];
        $this->outstandingInvoiceLimit = 10;
    }
    
    public function invoice(int $invoiceNumber, float $amount, string $dueDate)
    {
        $outstandingInvoiceCount = 0;
        
        foreach($this->invoices as $invoice) {
            if ($invoice->isUnpaid()) {
                $outstandingInvoiceCount++;
            }
        }

        if ($outstandingInvoiceCount === $this->unpaidInvoiceLimit) {
            throw new OutstandingInvoiceLimitReachedException();
        }
				
        $this->invoices[] = new Invoice($invoiceNumber, $amount, $dueDate);
    }

    public function changeOutstandingInvoiceLimit(int $invoiceLimit) {
        $this->oustandingInvoiceLimit = $invoiceLimit;
    }

    ...
}
```

There is now an invariant in place - a business rule that can never be breached: the number of outstanding invoices
raised against a client at any given moment can never be greater than the outstanding invoice limit set for the client.

Let's consider what separating the Client and Invoice Entities would look like under this new constraint.

Since invoices would no longer be part of the Client Entity, the code in the `invoice()` factory method that is
responsible for enforcing the invariant will need to be adjusted.

One such solution would be to hand the invoices for the client in as a dependency. There are arguably a few good
approaches here, but I have opted to retrieve the outstanding invoices ahead of time.

```php
<?php

namespace Accounting\Application;

class InvoiceClientCommandHandler extends TransactionalUseCase
{
    private ClientRepository $clientRepository;
    private InvoiceRepository $invoiceRepository;

    public function __construct(ClientRepository $clientRepository, InvoiceRepository $invoiceRepository)
    {
        $this->clientRepository = $clientRepository;				
        $this->invoiceRepository = $invoiceRepository;
    }

    public function handle(float $amount, string $dueDate) {
        $client = $this->clientRepository->clientOfId($clientId);
        $outstandingInvoices = $this->invoiceRepository->outstandingInvoicesForClient($clientId);
        
        $invoice = $client->invoice(
            $this->invoiceRepository->nextInvoiceNumberForClient($clientId),
            $amount,
            $dueDate,
            $outstandingInvoices
        );

        $this->invoiceRepository->save($invoice);
    }	
}
```

```php
<?php

namespace Accounting\Domain;

class Client
{
    ...
    
    public function invoice(int $invoiceNumber, float $amount, string $dueDate, array $outstandingInvoices) {
        if (count($outstandingInvoices) === $this->outstandingInvoiceLimit) {
                throw new OutstandingInvoiceLimitReachedException();
        }
				
        return new Invoice($this->clientId, $invoiceNumber, $amount, $dueDate);
    }

    ...
}
```

Now that the Invoice Entities are no longer contained within the Client Entity, we have added a parameter for
the `$clientId` to the constructor of the Invoice Entity. If we did not do this, there would be no way of linking a
given invoice back to the client that it relates to.

Nothing inherent about separating the Client and Invoice Entities means that we have to break the invariant. After all,
we can always just wrap the entire operation in one large atomic database transaction and consistency is guaranteed.

However, our need to hold a lock on the Client and the Invoices Entities has diminished our one great advantage of
separating the Entities in the first place. We can no longer update the Entities independently of each other. No matter
what, the consistency of the model must be protected.

We could improve the situation a little by setting the isolation level to allow for non-repeatable reads, which would
reduce the time read locks are held on the Client and Invoice Entities. Nonetheless, concurrent updates would lead to
the transaction being aborted and rolled back.

Unlike before when the invariant did not exist and there were advantages to treating Client and Invoice as disconnected
Entities, it now makes more sense to model them as a coherent whole.

**By placing the Invoice Entities back into the Client Entity, the Client Entity can enforce our business invariant, and
maintain the consistency of the model from within the domain layer. Such a cluster of Entities and Value Objects that
enforces an invariant, in this case the Client Entity and the contained Invoice Entities, is referred to as an
Aggregate.**

If separating Entities to be disjoint is a way to reduce contention, an Aggregate answers the question of "how far do we
go in separating Entities?" Separating Entities reduces contention, and thus improves the availability of your system,
just as long as you don't go so far as to break apart properties that are needed to enforce real business invariants.

If you have correctly identified your Aggregate boundaries, you should be able to retrieve any Aggregate and call any of
its methods without ever leaving the system in an inconsistent state. For this reason, **an Aggregate is often referred
to as a consistency boundary.**

## What's next?

I hope that has helped you to understand what an Aggregate is, and how you can utilize Aggregates to improve the
usability and availability of your systems.

In the next guide I'll be taking a step away from transactional consistency to talk about *eventual consistency* - a
tool that lets us further improve the availability of our systems by taking advantage of business rules that don't need
to be immediately up-to-date at all times.

Blog

Can you imagine your team deploying to production every day?

A note on estimation

Exceptions in Java

What is legacy blindness, and how can I avoid it?

Integrating Commento.io into the new KiteFrame site

Aggregate Design Part 1: Transactional Consistency