When you're working with an application, sometimes it no longer makes sense to try to continue and improve what already exists. Instead, you need to rethink, restructure, and rebuild.

Making the decision to give up all the work you and others have put into the existing system is a difficult choice for many developers. Still, dogged devotion to existing code in the face of disruption is a disservice to developers and users alike.

The effects of any large-scale alterations to a system reach far beyond the development world. Wholesale system replacements are rarely invisible, which also makes life difficult for salespeople and marketers. They're the ones who have to explain to customers why such a drastic change happened.

But this does not make the changes any less necessary.

As with so many other things in life, just because a choice is difficult and painful does not mean it is wrong. Evolution can be a violent process. But failure to adapt leads to extinction.

When fish crawled out of the sea millions of years ago, they didn’t continue to improve on fins and gills. Entirely new systems were necessary for motion and breathing. It doesn’t mean that fins and gills weren’t valuable or that their design was flawed. Indeed, their designs fit perfectly with their intended purposes. But the purpose became irrelevant, and so they were no longer suitable in their current environment.

When the time comes (and it will), you must step back and take an objective look at the situation. Will another tweak to that fin work? Or will it just highlight how poorly adapted it is to current needs?

Intelligent Design Choice or Inevitable Reaction?

Much of the discussion on sacrificial architecture revolves around whether it should be a proactive development process as opposed to a last-ditch reactionary decision.

Should developers intentionally build systems with limited lifetimes? Or should they build for the long run and make large-scale changes only if absolutely necessary?

According to Martin Fowler, who introduced sacrificial architecture seven years ago, building it into the design process can be a good idea:

“So what does it mean to deliberately choose a sacrificial architecture? Essentially it means accepting now that, in a few years’ time, you'll (hopefully) need to throw away what you're currently building.

This can mean accepting limits to the cross-functional needs of what you're putting together. It can mean thinking now about things that can make it easier to replace when the time comes - software designers rarely think about how to design their creation to support its graceful replacement. It also means recognizing that software that's thrown away in a relatively short time can still deliver plenty of value.”

Intentional sacrifice can also be useful when considering new features or applications as a way to limit overall development effort.

Using sacrificial architecture for proof-of-concept systems can move the development process more quickly towards a launchable implementation. As noted in the Open Group Agile Architecture Framework:

“When the goal is to get rapid market feedback experimenting with an MVP, sacrificial architecture is an option to consider as it would not be worth spending too much time designing an architecture that would have to change should the product owner decide to pivot.”

This is not to say that proactively using sacrificial architecture will eliminate the need for reactive sacrifices. There are always going to be changes and disruptions that you and your team will not anticipate. And disruptions often lead to sacrifices and evolutions.

Just consider how the COVID pandemic crisis disrupted so many aspects of everyday life, from how employees work to how schools teach our children.

There are many less drastic examples as well. One side effect of the COVID crisis was the rapid acceleration of e-commerce business and online transactions.

But the industry had to adapt to rising consumer concerns about data privacy. All online businesses rely on software with crucial features such as online invoicing and payments. But application providers and payment processors had to rapidly adapt existing systems to ensure compliance with new standards like the Payment Card Data Security Standard (PCI-DSS) and the European Union General Data Protection Regulation (GDPR).

Image Source

In the same way, code can become obsolete or fail to accomplish its intended purposes. There are times when disruptions in coding practices or programming language capabilities mean that you need to make large-scale changes.

Just consider eBay, which has changed its underlying programming language twice since its founding in 1995. Why? Because the capabilities of the abandoned languages failed to meet eBay’s needs and requirements as the business grew.

How to Anticipate the Sacrifice

Developers cannot possibly build to avoid the need for replacements altogether, and they shouldn’t focus on doing so. There are, however, steps you can take to plan for obsolescence.

Build with replacement in mind

As Fowler stated, you can build code with the idea that it will require replacement in a few years. Outdated code will eventually become susceptible to malicious viruses that could result in browser hijacking or system slowdowns.

This means that you need to consider in advance the code’s limitations, including performance and scalability, and other characteristics.

Minimize sacrifice through modularity

As a general rule, it is easier to replace smaller pieces of code than it is to replace an entire structure.

Just as you don’t need to spend the time and money to replace your entire roof if a shingle gets blown off, there is no need to completely rewrite the code for a system if revising one module will do.

So building modular code results in an architecture that is easier for developers to modify as needed.

But modularity is not always an effective solution, and you should be aware of the limits of your code. Sometimes, replacing too many pieces can weaken a structure or make it unstable.

In the same way, the more modules you replace in your existing code, the more opportunities there are for problems with the operation of the code as a whole. That is the dividing line between continued piece-by-piece updating and wholesale replacement.

Maintain quality standards

Even when you intentionally decide to build code knowing you will sacrifice it in the near future, you should always continjue to strive to meet or exceed company quality standards. After all, the sacrificial architecture will still probably be in production.

Needs may also change, eliminating the reasons that you planned to retire the code in the first place. Poorly designed or implemented code also makes developers’ lives more difficult when modifying the code.

Poor documentation and code structure also hinder your ability to understand the connections between pieces of code, making replacements and updates more challenging.

Poorly designed code can also be a significant security risk, perhaps allowing hackers to access private data that companies have invested so much to protect.

Image Source

Quality is a mantra that must always be front-of-mind, even for disposable code.

Sacrificing for the Greater Good

While it may sound trite to quote this common saying, sacrificing your code may indeed be for the greater good of your systems and your company in the long run.

Judicious, proactive use of sacrificial architectures can help reduce time to market for new features. And, it can minimize how much effort it takes when an unplanned, large-scale replacement inevitably occurs.

Clean Architecture is a term coined by Robert C. Martin. The main idea is that entities and use cases are independent of frameworks, UI, the database, and external services.

A Clean Architecture style has a positive effect on maintainability because:

• We can test domain entities and use cases without a framework, UI, or infrastructure.
• Technology decisions can change without affecting domain code, and vice versa. It is even possible to switch to a new framework with limited effort.

My goal is to flatten the learning curve, and reduce the effort it might take you to implement a Clean Architecture. That’s why I created the Modern Clean Architecture libraries.

In this article, I will show you how to create an application with a modern clean architecture, from a HTML/JavaScript front end to a Spring Boot back end. The focus will be on the back end.

Let’s start with an overview of the sample application – a timeless classic, the TODO app.

Sample TODO List Application

A to do list is a collection of tasks. A task has a name, and is either completed or not. As a user, you can:

• Create a single to do list, and persist it
• Add a task
• Complete a task, or “uncomplete” it
• Delete a task
• List all tasks
• Filter completed/uncompleted tasks

Here’s what a todo list with 1 uncompleted and 2 completed tasks looks like:

We'll start at the core of the application, the domain entities. Then we'll work our way outwards to the front end.

The Domain Entities

The central domain entities are TodoList and Task.

The TodoList entity contains:

• a unique id,
• a list of tasks,
• domain methods for adding, completing, and deleting tasks

The TodoList entity doesn’t contain public setters. Setters would break proper encapsulation.

Here’s part of the TodoList entity. Lombok annotations shorten the code.

public class TodoList implements AggregateRoot<TodoList, TodoListId> {
    private final TodoListId id;
    private final List<Task> tasks;

    @Value(staticConstructor = "of")
    public static class TodoListId implements Identifier {
        @NonNull
        UUID uuid;
    }

    @Override
    public TodoListId getId() {
        return id;
    }
    ...
    public TaskId addTask(String taskName) {
        if (taskName == null || isWhitespaceName(taskName)) {
            throw new IllegalTaskName("Please specify a non-null, non-whitespace task name!");
        }
        TaskId taskId = add(TaskId.of(UUID.randomUUID()), taskName, false);
        return taskId;
    }
      ...
    public void deleteTask(TaskId task) {
        Optional<Task> foundTask = findTask(task);
        foundTask.ifPresent(tasks::remove);
    }
     ...
}

What is the AggregateRoot interface good for? Aggregate root is a term from Domain Driven Design (DDD) by Eric Evans:

An aggregate is a cluster of associated objects that we treat as a unit for the purpose of data changes. Each aggregate has a root and a boundary. The boundary defines what is inside the aggregate. The root is a single, specific entity contained in the aggregate.

We can change the aggregate’s state only through the aggregate root. In our example that means: we always have to use the TodoList to add, remove, or change a task.

That allows the TodoList to enforce constraints. For example, we can’t add a task with a blank name to the list.

The AggregateRoot interface is part of the jMolecules library. This library makes DDD concepts explicit in the domain code. During build, a ByteBuddy plugin maps the annotations to Spring Data annotations.

So we only have a single model, both for representing domain concepts, and persistence. Still, we don’t have any persistence-specific annotations in the domain code. We don’t tie ourselves to any framework.

The Task class is similar, but it implements the jMolecules Entity interface instead:

public class Task implements Entity<TodoList, TaskId> {
    private final TaskId id;
    private final String name;
    private final boolean completed;

    @Value(staticConstructor = "of")
    public static class TaskId implements Identifier {
        @NonNull
        UUID uuid;
    }

    Task(@NonNull TaskId id, @NonNull String name, boolean completed) {
        this.id = id;
        this.name = name;
        this.completed = completed;
    }
}

The constructor of Task is package private. So we can’t create an instance of Task from outside of the domain package. And the Task class is immutable. No changes to its state are possible from outside of the aggregate’s boundary.

We need a repository for storing the TodoList. To stick to domain terms in the domain code, it is called TodoLists:

public interface TodoLists extends Repository<TodoList, TodoListId> {
    TodoList save(TodoList entity);
    Optional<TodoList> findById(TodoListId id);
    Iterable<TodoList> findAll();
}

Again, the code uses a jMolecues annotation: Repository. During build, the ByteBuddy plugin translates it to a Spring Data repository.

We’ll skip the domain exceptions, since there’s nothing special about them. That’s the complete domain package.

The App's Behavior (and Use Cases)

Next, we define the behavior of the application that is visible to the end user. Any interaction of the user with the application happens as follows:

1. The user interface sends a request.
2. The backend reacts by executing a request handler. The request handler does everything necessary to fulfill the request:
3. Access the database
4. Call external services
5. Call domain entity methods
6. The request handler may return a response.

We implement a request handler with a Java 8 functional interface.

A handler that returns a response implements the java.util.Function interface. Here’s the code of the AddTask handler. This handler

• extracts the to do list id and task name from an AddTaskRequest,
• finds the to do list in the repository (or throws an exception),
• adds a task with the name from the request to the list,
• returns an AddTaskResponse with the added task’s id.

@AllArgsConstructor
class AddTask implements Function<AddTaskRequest, AddTaskResponse> {
    @NonNull
    private final TodoLists repository;

    @Override
    public AddTaskResponse apply(@NonNull AddTaskRequest request) {
        final UUID todoListUuid = request.getTodoListUuid();
        final String taskName = request.getTaskName();

        final TodoList todoList = repository.findById(TodoListId.of(todoListUuid))
            .orElseThrow(() -> new TodoListNotFound("Repository doesn't contain a TodoList of id " + todoListUuid));

        TaskId taskId = todoList.addTask(taskName);
        repository.save(todoList);

        return new AddTaskResponse(taskId.getUuid());
    }
}

Lombok creates a constructor with the TodoLists repository interface as constructor argument. We pass in any external dependency as interface to the handler’s constructor.

The requests and responses are immutable objects:

@Value
public class AddTaskRequest {
    @NonNull
    UUID todoListUuid;

    @NonNull
    String taskName;
}

The Modern Clean Architecture libraries (de)serialize them from/to JSON.

Next, an example of a handler that doesn’t return a response. The DeleteTask handler receives a DeleteTaskRequest. Since the handler doesn’t return a response, it implements the Consumer interface.

@AllArgsConstructor
class DeleteTask implements Consumer<DeleteTaskRequest> {
    @NonNull
    private final TodoLists repository;

    @Override
    public void accept(@NonNull DeleteTaskRequest request) {
        final UUID todoListUuid = request.getTodoListUuid();
        final UUID taskUuid = request.getTaskUuid();

        final TodoList todoList = repository.findById(TodoListId.of(todoListUuid))
            .orElseThrow(() -> new TodoListNotFound("Repository doesn't contain a TodoList of id " + todoListUuid));

        todoList.deleteTask(TaskId.of(taskUuid));
        repository.save(todoList);
    }
}

One question remains: who creates these handlers?

The answer: a class implementing the BehaviorModel interface. The behavior model maps each request class to the request handler for this kind of request.

Here’s a part of the TodoListBehaviorModel:

@AllArgsConstructor
public class TodoListBehaviorModel implements BehaviorModel {
    @NonNull
    private final TodoLists todoLists;
    ...
    @Override
    public Model model() {
        return Model.builder()
            .user(FindOrCreateListRequest.class).systemPublish(findOrCreateList())
            .user(AddTaskRequest.class).systemPublish(addTask())
            .user(ToggleTaskCompletionRequest.class).system(toggleTaskCompletion())
            ...
            .build();
    }

    private Function<FindOrCreateListRequest, FindOrCreateListResponse> findOrCreateList() {
        return new FindOrCreateList(todoLists);
    }

    private Function<AddTaskRequest, AddTaskResponse> addTask() {
        return new AddTask(todoLists);
    }

    private Consumer<ToggleTaskCompletionRequest> toggleTaskCompletion() {
        return new ToggleTaskCompletion(todoLists);
    }
    ...
}

The user(...) statements define the request classes. We use systemPublish(...) for handlers that return a response, and system(...) for handlers that don’t.

The behavior model has a constructor with external dependencies passed in as interfaces. And it creates all handlers and injects the appropriate dependencies into them.

By configuring the dependencies of the behavior model, we configure all handlers. That’s exactly what we want: a central place where we can change or switch the dependencies to technology. That’s how technology decisions can change without affecting the domain code.

The Apps' Web Layer (the Adapters)

The web layer in a modern clean architecture can be very thin. In its simplest form, it consists of only 2 classes:

• One class for configuration of dependencies
• One class for exception handling

Here’s the TodoListConfiguration class:

@Configuration
class TodoListConfiguration {
    @Bean
    TodoListBehaviorModel behaviorModel(TodoLists repository) {
        return new TodoListBehaviorModel(repository);
    }
}

Spring injects the implementation of the TodoLists repository interface into the behaviorModel(…) method. That method creates a behavior model implementation as a bean.

If the application uses external services, the configuration class is the place to create the concrete instances as beans. And inject them into the behavior model.

So, where are all the controllers?

Well, there aren’t any that you have to create. At least if you only handle POST requests. (For the handling of GET requests, see the Q&A later.)

The spring-behavior-web library is part of the Modern Clean Architecture libraries. We define a single endpoint for requests. We specify the URL of that endpoint in the application.properties:

behavior.endpoint = /todolist

If that property exists, spring-behavior-web sets up a controller for the endpoint in the background. That controller receives POST requests.

We don’t need to write Spring specific code to add new behavior. And we don’t need to add or change a controller.

Here’s what happens when the endpoint receives a POST request:

1. spring-behavior-web deserializes the request,
2. spring-behavior-web passes the request to a behavior configured by the behavior model,
3. the behavior passes the request to the appropriate request handler (if there is one),
4. spring-behavior-web serializes the response and passes it back to the endpoint (if there is one).

By default, spring-behavior-web wraps every call to a request handler in a transaction.

How to send POST requests

Once we start the Spring Boot application, we can send POST requests to the endpoint.

We include a @type property in the JSON content so that spring-behavior-web can determine the right request class during deserialization.

For example, this is a valid curl command of the To Do List application. It sends a FindOrCreateListRequest to the endpoint.

curl -H "Content-Type: application/json" -X POST -d '{"@type": "FindOrCreateListRequest"}' [http://localhost:8080/todolist](http://localhost:8080/todolist)

And that’s the corresponding syntax to use in Windows PowerShell:

iwr http://localhost:8080/todolist -Method 'POST' -Headers @{'Content-Type' = 'application/json'} -Body '{"@type": "FindOrCreateListRequest"}'

Exception handling

Exception handling with spring-behavior-web is no different than in “normal” Spring applications. We create a class annotated with @ControllerAdvice. And we place methods annotation with @ExceptionHandler in it.

See the TodoListExceptionHandling for example:

@ControllerAdvice
class TodoListExceptionHandling {
    @ExceptionHandler({ Exception.class })
    public ResponseEntity<ExceptionResponse> handle(Exception e) {
        return responseOf(e, BAD_REQUEST);
    }
    ...
}

Note that in a real application, the different exception types need different treatment.

The App's Front End

The front end of the To Do List application consists of:

• a HTML page,
• a CSS file for formatting,
• and a the main.js JavaScript file

We focus on main.js here. It sends requests and updates the web page.

Here’s part of its content:

// URL for posting all requests,
// Must be the same as the one in application.properties
// (See https://github.com/bertilmuth/modern-clean-architecture/blob/main/samples/todolist/src/main/resources/application.properties)
const BEHAVIOR_ENDPOINT = "/todolist";

//variables
var todoListUuid;
...

// functions
function restoreList(){
    const request = {"@type":"FindOrCreateListRequest"};

    post(request, function(response){
        todoListUuid = response.todoListUuid;
        restoreTasksOf(todoListUuid);
    });
}

function restoreTasksOf(todoListUuid) {
    const request = {"@type":"ListTasksRequest", "todoListUuid":todoListUuid};

    post(request, function(response){    
        showTasks(response.tasks);
    });
}
...
function post(jsonObject, responseHandler) {    
    const xhr = new XMLHttpRequest();
    xhr.open("POST", BEHAVIOR_ENDPOINT);

    xhr.setRequestHeader("Accept", "application/json");
    xhr.setRequestHeader("Content-Type", "application/json");

    xhr.onreadystatechange = function() {
        if (xhr.readyState === 4) {
            response = xhr.responseText.length > 0? JSON.parse(xhr.response) : "";
            if(response.error){
                alert('Status ' + response.status + ' "' + response.message + '"');
            } else{
                responseHandler(response);
            }
        }    
    };

    const jsonString = JSON.stringify(jsonObject);
    xhr.send(jsonString);
}

So for example, this is the JSON object for a ListTasksRequest:

const request = {“@type”:”ListTasksRequest”, “todoListUuid”:todoListUuid};

The post(…) method sends the request to the backend, and passes the response to the response handler (the callback function you passed in as second parameter).

That’s all about the To Do List application.

Questions & Answers

What if…

… I want to send GET requests instead of POST requests?

… I want the web layer to evolve separately from the behavior?

… I want to use a different framework than Spring?

… I have a much bigger application than the To Do List sample. How do I structure it?

Here are the answers.

Conclusion

In this article, I presented you a particular way to implement a Clean Architecture. There are many other ways.

My goal is to reduce the effort of building a Clean Architecture and flatten the learning curve.

To achieve this, the Modern Clean Architecture libraries provide the following features:

• Serialization of immutable requests and responses without serialization specific annotations.
• No necessity for DTOs. You can use the same immutable objects for requests/responses in web layer and use cases..
• Generic endpoint that receives and forwards POST requests. New behavior and domain logic can be added and used without the need to write framework specific code.

In my next article, I will describe how to test a Modern Clean Architecture.

I invite you to visit the Modern Clean Architecture GitHub page.

See the To Do List sample application.

And please share any feedback you have with me. What do you think about it?

If you want to keep up with what I’m doing or drop me a note, follow me on LinkedIn or Twitter.

Acknowledgements

Thank you to Surya Shakti for publishing the original front end only to do list code.

Thank you to Oliver Drotbohm for pointing me to the awesome jMolecules library.

Recently I attended a meeting with multiple stakeholders from the business side. When asked to explain a feature, I started explaining them the details of the feature and its implementation. After the meeting one of my colleagues told me even though I explained it in detail, they will be requesting a follow-up meeting to discuss the same thing and it was true — the next day we had a meeting invite for the same thing as a follow-up. He explained to me that the reason was I had provided them more details than necessary which probably confused them. This incident led me to the principle of Occam’s Razor.

Quoted from Wikipedia

Occam’s razor or the law of parsimony is the problem-solving principle that essentially states that “simpler solutions are more likely to be correct than complex ones.” When presented with competing hypotheses to solve a problem, one should select the solution with the fewest assumptions. The idea is attributed to English Franciscan friar William of Ockham (c. 1287–1347), a scholastic philosopher and theologian.

We have all heard the famous quote by Sherlock Holmes

Once you eliminate the impossible, whatever remains, no matter however improbable, must be the truth.

This follows directly from Occam’s Razor. This principle states that given two explanations of a situation, the one in which there is the least number of variables(simpler) however improbable is the most likely explanation. This principle is very helpful and it can be used in a wide variety of situations but it is especially powerful in the hands of software professional.

There are many areas of Software development which can benefit from this principle. A few of them are:

Coding

The first and foremost area is coding. As developers, we make hundreds of decisions every day which directly affects the health of the codebase and in turn the business. Few of the mistakes we make include adding unwanted abstractions, designing for the future, making it “extensible”(whatever that means). These code with unwanted additional complexity slowly rots over time and becomes “that” part of the codebase that no one understands and nobody is willing to touch. These are the things we do either knowingly or unknowingly which can put a dent on our codebase health in the long-run.

To overcome this it would be prudent for us to think in terms of Occam’s Razor. Always do the simplest thing possible at any point in time. Principles like YAGNI and KISS are examples of Occam’s Razor in coding. If you want to combine 3 design patterns to accommodate a feature request you expect in the future, restrain your primal instincts and stick with a single class for now. Using Occam’s razor during the development process would keep the codebase simple and readable and your future peers will really thank you.

A word of caution here is, this principle should not be used as an excuse to write bad code or take shortcuts. If there is a real need to add complexity, by all means, you should do that. Consider this a framework for you to step back and think for a moment and weigh the cost of your decision in the long run.

Debugging

Another interesting application of this principle is while debugging. The hard part about debugging is nobody knows the answer especially when you work in a legacy code base with business critical functionalities. Bigger the codebase, more complex the debugging process and thus the Occam’s Razor comes in really handy. All the good software developers I know trace the root cause of a bug by using this principle without even realising it.

Let's say there you write a program to display a few stats in the dashboard. You observe that each time the dashboard is updated you get 2x instead of x for a particular stat. What would be your first instinct? Is it a double counting issue or some thread level race condition? I am guessing most of you with go with the former. This is Occam’s Razor in action. You picked the choice which provides the simplest explanation for the issue intuitively.

This is not to say that always the simplest explanation is the right one. Instead, you start from the simplest one and eliminate one by one either by theory or experimentation until you arrive at the actual root cause for the problem. This provides a framework for you to tackle problems methodically.

Communication

One of the most under-rated functions of a software developer is communication. Be it with peers/ managers/ stakeholders, communication is as important as coding for any developer. As developers, we are the closest to any given problem and it is natural for people to rely on us for understanding the whole picture of a product/feature. This makes what you communicate and how you communicate extremely crucial from a business standpoint.

As we are closest to a problem, we will have a lot of technical and domain knowledge around it. But it is extremely important to communicate the right things to the right people. Assume you are in a mail thread with Sr. engineer, PM, Manager, and a Business development executive, you need to provide just the right amount of detail so that the Engineer can get the technical challenges and the others can also understand the complexity technically as well as the business justification. You need to achieve the right amount of balance in the technical/business mixture for the audience to understand and not lose interest. This is where Occam’s razor comes in. You need to provide the least level of detail in the mail and schedule a follow up for the people who need to understand more.

Take this as an example “we did a POC on x and we were able to achieve y. Even though we discussed A in the previous mail, we could not achieve A due to the complexities in a library that we were using. There were a lot of assumptions in the threading model in the library and thus it prevented us from achieving A”.

Now, what do you think the different stakeholders will understand?

1. Engineer — Yes I get the issue.
2. PM- So basically we cant achieve A. And what is a threading model?
3. Manager — Did he try enough to achieve A?

Instead, if we write “we did a POC on x and were able to achieve y. A was targetted but not achieved. I’ll schedule a meeting to demo the POC and go into details on the blocker for A.” After that, you have all the time in the world to explain in detail the blockers for the right audience and achieve a consensus.

Now, what is the thought process after the demo?

1. Engineer — Makes sense.
2. PM — The POC is good for now. I guess we can drop A for now and proceed without it.
3. Manager — He has done an in-depth analysis and knows what he is doing.

Conclusion

Occam’s Razor can be employed in a wide variety of scenarios and these are just a few examples. Developers use this principle intuitively without knowing it. But knowing it and using it deliberately in various situations will greatly improve you as a software developer. If you can think of any other area of Software where this principle is being used feel free to leave your thoughts in comments.

If you liked this article, feel free to reach out to me at https://kaizencoder.com/contact.

A hexagonal architecture simplifies deferring or changing technology decisions. You want to change to a different framework? Write a new adapter. You want to use a database, instead of storing data in files? Again, write an adapter for it.

Draw a boundary around the business logic. The hexagon. Anything inside the hexagon must be free from technology concerns.
The outside of the hexagon talks with the inside only by using interfaces, called ports. Same the other way around. By changing the implementation of a port, you change the technology.

Isolating business logic inside the hexagon has another benefit. It enables writing fast, stable tests for the business logic. They do not depend on web technology to drive them, for example.

Here’s an example diagram. It shows Spring MVC technology as boxes with dotted lines, ports and adapters as solid boxes, and the hexagon without its internals:

An adapter translates between a specific technology and a technology free port. The PoemController adapter on the left receives requests and sends commands to the IReactToCommands port. The PoemController is a regular Spring MVC Controller. Because it actively uses the port, it's called a driver adapter.

IReactToCommands is called a driver port. Its implementation is inside the hexagon. It's not shown on the diagram.

On the right side, the SpringMvcPublisher adapter implements the IWriteLines port. This time, the hexagon calls the adapter through the port. That's why SpringMvcPublisher is called a driven adapter. And IWriteLines is called a driven port.

I show you how to implement that application. We go all the way from a user story to a domain model inside the hexagon. We start with a simple version of the application that prints to the console. Then we switch to Spring Boot and Spring MVC.

From a user story to ports & adapters

The company FooBars.io decides to build a Poetry App. The product owner and the developers agree on the following user story:

As a reader
I want to read at least one poem each day
So that I thrive as a human being

As acceptance criteria, the team agrees on:

• When the user asks for a poem in a specific language, the system displays a random poem in that language in the console
• It's ok to "simulate" the user at first, i.e. no real user interaction. (This will change in future versions.)
• Supported languages: English, German

The developers meet and draw the following diagram:

So the SimulatedUser sends commands to the IReactToCommands port. It asks for poems in English and German. Here's the code, it's available on Github.

_poem/simple/driver_adapter/SimulatedUser.java_

public class SimulatedUser {
    private IReactToCommands driverPort;

    public SimulatedUser(IReactToCommands driverPort) {
        this.driverPort = driverPort;
    }

    public void run() {
        driverPort.reactTo(new AskForPoem("en"));
        driverPort.reactTo(new AskForPoem("de"));
    }
}

The IReactToCommands port has only one method to receive any kind of command.

_poem/boundary/driver_port/IReactToCommands.java_

public interface IReactToCommands{
    void reactTo(Object command);
}

AskForPoem is the command. Instances are simple, immutable POJOs. They carry the language of the requested poem.

poem/command/AskForPoem.java

public class AskForPoem {
    private String language;

    public AskForPoem(String language) {
        this.language = language;
    }

    public String getLanguage() {
        return language;
    }
}

And that's it for the left, driver side of the hexagon. On to the right, driven side.

When the SimulatedUser asks the IReactToCommands port for a poem, the hexagon:

1. Contacts the IObtainPoems port for a collection of poems
2. Picks a random poem from the collection
3. Tells the IWriteLines port to write the poem to the output device

You can't see Step 2 yet. It happens inside the hexagon, in the domain model. That's the business logic of the example. So we focus on Step 1 and Step 3 first.

In Step 1, the collection of poems is a language dependent, hard coded array. It's provided by the HardcodedPoemLibrary adapter that implements the IObtainPoems port.

_poem/boundary/driven_port/IObtainPoems.java_

public interface IObtainPoems {
    String[] getMePoems(String language);
}

_poem/simple/driven_adapter/HardcodedPoemLibrary.java_

public class HardcodedPoemLibrary implements IObtainPoems {
    public String[] getMePoems(String language) {
        if ("de".equals(language)) {
            return new String[] { /* Omitted for brevity */ };
        } else { 
            return new String[] { /* Omitted for brevity */ };
        }
    }
}

In Step 3, the ConsoleWriter adapter writes the lines of the poems to the output device, i.e. the console.

_poem/boundary/driven_port/IWriteLines.java_

public interface IWriteLines {
    void writeLines(String[] strings);
}

_poem/simple/driven_adapter/ConsoleWriter.java_

public class ConsoleWriter implements IWriteLines {
    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        for (String line : lines) {
            System.out.println(line);
        }
        System.out.println("");
    }
}

We have created all the ports, and a simple implementation of all the adapters. So far, the inside of the hexagon remained a mystery. It's up next.

Command handlers (inside the hexagon)

When a user asks for a poem, the system displays a random poem.
Similar in the code: when the IReactToCommands port receives an AskForPoemcommand, the hexagon calls a DisplayRandomPoem command handler.

The DisplayRandomPoem command handler obtains a list of poems, picks a random one and writes it to the output device. This is exactly the list of steps we talked about in the last clause.

_poem/boundary/internal/command_handler/DisplayRandomPoem.java_

public class DisplayRandomPoem implements Consumer<AskForPoem> {
        /* Omitted for brevity */

    @Override
    public void accept(AskForPoem askForPoem) {
        List<Poem> poems = obtainPoems(askForPoem);
        Optional<Poem> poem = pickRandomPoem(poems);
        writeLines(poem);   
    }

        /* Rest of class omitted for brevity */
}

It's also the job of the command handler to translate between the domain model data and the data used in the port interfaces.

Tying commands to command handlers

In my implementation of a hexagonal architecture, there is only a single driver port, IReactToCommands. It reacts to all types of commands.

public interface IReactToCommands{
    void reactTo(Object command);
}

The Boundary class is the implementation of the IReactToCommands port. It creates a behavior model using a library. The behavior model maps each command type to a command handler. Then, a behavior dispatches the commands based on the behavior model.

poem/boundary/Boundary.java

public class Boundary implements IReactToCommands, BehaviorModel {
  private final IObtainPoems poemObtainer;
  private final IWriteLines lineWriter;
  private final StatelessBehavior behavior;

  private static final Class<AskForPoem> asksForPoem = AskForPoem.class;

  public Boundary(IObtainPoems poemObtainer, IWriteLines lineWriter) {
    this.poemObtainer = poemObtainer;
    this.lineWriter = lineWriter;
    this.behavior = StatelessBehavior.of(this);
  }

  @Override
  public Model model() {
    return Model.builder()
        .user(asksForPoem).system(displaysRandomPoem())
        .build();
  }

  @Override
  public void reactTo(Object commandObject) {
    behavior.reactTo(commandObject);
  }

  private Consumer<AskForPoem> displaysRandomPoem() {
    return new DisplayRandomPoem(poemObtainer, lineWriter);
  }
}

The domain model

The domain model of the example doesn’t have very interesting functionality. The RandomPoemPicker picks a random poem from a list.

A Poem has a constructor that takes a String containing line separators, and splits it into verses.

The really interesting bit about the example domain model: it doesn’t refer to a database or any other technology, not even by interface!

That means that you can test the domain model with plain unit tests. You don’t need to mock anything.

Such a pure domain model is not a necessary property of an application implementing a hexagonal architecture. But I like the decoupling and testability it provides.

Plug adapters into ports, and that's it

A final step remains to make the application work. The application needs a main class that creates the driven adapters. It injects them into the boundary.
It then creates the driver adapter, for the boundary, and runs it.

poem/simple/Main.java

public class Main {
    public static void main(String[] args) {
        new Main().startApplication();
    }

    private void startApplication() {
        // Instantiate driven, right-side adapters
        HardcodedPoemLibrary poemLibrary = new HardcodedPoemLibrary();
        ConsoleWriter consoleWriter = new ConsoleWriter();

        // Inject driven adapters into boundary
        Boundary boundary = new Boundary(poemLibrary, consoleWriter);

        // Start the driver adapter for the application
        new SimulatedUser(boundary).run();
    }
}

And that's it! The team shows the result to the product owner. And she's happy with the progress. Time for a little celebration.

Switching to Spring

The team decides to turn the poem app into a web application. And to store poems in a real database. They agree to use the Spring framework to implement it.
Before they start coding, the team meets and draws the following diagram:

Instead of a SimulatedUser, there is a PoemController now, that sends commands to the hexagon.

_poem/springboot/driver_adapter/PoemController.java_

@Controller
public class PoemController {
    private SpringMvcBoundary springMvcBoundary;

    @Autowired
    public PoemController(SpringMvcBoundary springMvcBoundary) {
        this.springMvcBoundary = springMvcBoundary;
    }

    @GetMapping("/askForPoem")
    public String askForPoem(@RequestParam(name = "lang", required = false, defaultValue = "en") String language,
            Model webModel) {
        springMvcBoundary.basedOn(webModel).reactTo(new AskForPoem(language));

        return "poemView";
    }
}

When receiving a command, the PoemController calls springMvcBoundary.basedOn(webModel). This creates a new Boundary instance, based on the webModel of the request:

poem/springboot/boundary/SpringMvcBoundary.java

public class SpringMvcBoundary {
    private final IObtainPoems poemObtainer;

    public SpringMvcBoundary(IObtainPoems poemObtainer) {
        this.poemObtainer = poemObtainer;
    }

    public IReactToCommands basedOn(Model webModel) {
        SpringMvcPublisher webPublisher = new SpringMvcPublisher(webModel);
        IReactToCommands boundary = new Boundary(poemObtainer, webPublisher);
        return boundary;
    }
}

The call to reactTo() sends the command to the boundary, as before. On the right side of the hexagon, the SpringMvcPublisher adds an attribute lines to the Spring MVC model. That's the value Thymeleaf uses to insert the lines into the web page.

_poem/springboot/driven_adapter/SpringMvcPublisher.java_

public class SpringMvcPublisher implements IWriteLines {
    static final String LINES_ATTRIBUTE = "lines";

    private Model webModel;

    public SpringMvcPublisher(Model webModel) {
        this.webModel = webModel;
    }

    public void writeLines(String[] lines) {
        Objects.requireNonNull(lines);
        webModel.addAttribute(LINES_ATTRIBUTE, lines);
    }
}

The team also implements a PoemRepositoryAdapter to access the PoemRepository. The adapter gets the Poem objects from the database. It returns the texts of all poems as a String array.

_poem/springboot/driven_adapter/PoemRepositoryAdapter.java_

public class PoemRepositoryAdapter implements IObtainPoems {
    private PoemRepository poemRepository;

    public PoemRepositoryAdapter(PoemRepository poemRepository) {
        this.poemRepository = poemRepository;
    }

    @Override
    public String[] getMePoems(String language) {
        Collection<Poem> poems = poemRepository.findByLanguage(language);
        final String[] poemsArray = poems.stream()
            .map(p -> p.getText())
            .collect(Collectors.toList())
            .toArray(new String[0]);
        return poemsArray;
    }
}

Finally, the team implements the Application class that sets up an example repository and plugs the adapters into the ports.

And that's it. The switch to Spring is complete.

Conclusion

There are many ways to implement a hexagonal architecture. I showed you a straightforward approach that provides an easy to use, command driven API for the hexagon. It reduces the number of interfaces you need to implement. And it leads to a pure domain model.

If you want to get more information on the topic, read Alistair Cockburn’s original article on the subject.

The example in this article is inspired by a three part series of talks by Alistair Cockburn on the subject.

Last updated on 30 July 2021.__. If you want to keep up with what I’m doing or drop me a note, follow me on dev.to, LinkedIn or Twitter. Or visit my GitHub project. To learn about agile software development, visit my online course.

#

Clean Architecture

There are many videos and articles explaining clean architecture. Most of these go over the concepts from a 20,000 foot view. I don’t know about you, but I don’t learn things very well at that elevation. Not a lot of oxygen up there. I learn by jumping in head first and coding. This article and the accompanying code is what I ended up with after such a leap.

Bob’s Your Uncle

The term “Clean Architecture” was made popular by Robert Martin (Uncle Bob) and his book “Clean Architecture: A Craftsman’s Guide to Software Structure and Design.” Now I don’t proclaim to be an expert in this field and I haven’t read his book, though I intend to. But I can completely relate to the problems it is trying to solve.

How do you write a software system that is not dependent on anything other than a primary language ? We were promised this in the past with interfaces and other OO principles, but I had never before seen a “clean”, pun intended, explanation on how to do this regarding the whole system. And yes, I am a bit late to this party, being that Uncle Bob started to talk about these concepts in 2012, which is a century ago in software years.

The Diagram That Baffled Me

Here is the original diagram Uncle Bob and others used in their presentations when explaining Clean Architecture. This simple little diagram became an obsession of mine. I had long ago purged my memory of anything UML related and was struggling with the has-a, and uses-a relationships indicated by the open and close arrow heads. The only way I was going to figure this out was by writing some code.

Image Credit: Uncle Bob

Know Your Onions

One way to look at Clean Architecture is as an onion with layers. All layers can only depend on a layer that is closer to the center. That is, all dependencies point inward and not outward.

_[Image Credit](https://android.jlelse.eu/thoughts-on-clean-architecture-b8449d9d02df" rel="noopener" target="blank" title=")

One of These Days, I’m Gonna Get Organizized

In our example, there are 4 modules that correspond with each layer of this onion. Eventually these could be separate npm modules. For readability’s sake, I tried to name things according to Uncle Bob’s original Clean Architecture diagram at the top of this article. In the real world you would probably preface all names with what ever use case they represented.

Image Credit: Myself

The infrastructure (blue) layer is where all of our outside pluggable systems live. These outside systems such as devices, web, and UIs, shown in the onion diagram, will use our IRequest and IViewModel interfaces to communicate with our Controller and Presenter while the db and external interfaces, shown in the onion diagram, will use the IEntityGateway interface to communicate with our Interactor.

Our example will have one entity called a Widget with three properties. It also uses one use case “create widget” which takes a widget from the UI, saves the widget to some sort of storage, and returns back to the UI a newly created widget with an id and a revision number.

More Visual Aids

Here is the directory structure. Everything gets wired together in each module’s index.ts file. The entry point is demonstrated in a test located in infrastructure/test/TestEntryPoint.spec.ts .

Image Credit: Shift Command 4

Which Way Did He Go?

One of my original hangups was how the outer most layer communicates with the inner layers. I thought all you had to do is call some createWidget() function, for example, on a Controller and you would get a nice shiny new widget returned back to you. Wrong.

What you want to do is send the widget to be created down to the use case (Interactor) on a certain path and have the use case (Interactor) send the new widget back up to you on a different path. This is similar to a callback function or a Promise. I found a good diagram illustrating this in an article titled “Implementing Clean Architecture — Of controllers and presenters” (link below). In our example I have not implemented a RequestModel or a ResponseModel.

_[Image Credit](https://plainionist.github.io/Implementing-Clean-Architecture-Controller-Presenter/" rel="noopener" target="blank" title=")

Step Into, Step Over, and Step Out, the OO Way

So let’s first create a widget with classes and interfaces.

OO Step 1

This is the entry point. This code would be located in the infrastructure (blue) layer. This layer is where your mobile app, web app, API, CLI, etc. lives. Also all of your outside systems like external APIs, frameworks, libraries and databases live here too. Everything is pluggable in this layer and communicates with our system via interfaces we provide.

First you create your ViewModel implementation of the IViewModel interface where a new widget will appear and you can update your UI within the implemented function presentWidget(widget).

You then create a Controller that implements the IRequest interface by passing the EntityGateway and the ViewModel you created above to a constructor. Finally your UI calls createWidget(widget) on the Controller where your new widget begins its journey to the Interactor.

What’s an EntityGateway?

An EntityGateway implements the IEntityGateway interface and is where you implement specific code that persists your widget. It lives in the infrastructure (blue) layer. This could be any type of existing or future external API or persistence system such as a database.

To change out to a different system, you would just simply wire together the new EntityGateway implementation with the IEntityGateway interface. In this example, I use a Promise to simulate some sort of persistence operation.

Wire up What?

The file infrastructure/src/index.ts in the infrastructure module is where you can wire up your different implementations of your IEntityGateway interface. The “from” path of the import statement points to the correct implementation. In this case it is a persistence system named AnyDB.

Uncle Bob also talks about the use of a Main class where you can do this type of wiring up or do other initializing code. The Main class would also live in the infrastructure module and be pluggable. It would also communicate in the same manner as the other systems in the infrastructure module do. For example, you would initiate this class in your UI’s initializing code and pass it down into your more inner layers to be used via some sort of configuration interface.

Our example does not use a Main class and instead is passing the persistence system down into the interactor via the createWidget() function. This is probably not the “pure” way of doing this, but was done to make our example easier to read.

OO Step 2

The Controller is a very busy place. First, the EntityGateway passes through unchanged to our Interactor constructor. Then our ViewModel gets passed to the constructor of our Presenter which in turn also gets passed to our Interactor constructor. This all happens in the createWidget(widget) function of the Controller which was called by our UI in step 1 via the IRequest interface. We will talk about our Presenter in step 4 when the newly created widget travels back up to the UI.

OO Step 3

Finally we are at the most inner layer of our journey, the usecase layer where our Interactor lives. Or better known as our home for all of our app’s use case logic. There is one more inner layer, the domain. This is where all of our business entities and business specific logic lives. In this example, we really don’t have any need to go there except to borrow the WidgetType and IEntityGateway interfaces.

Movin On Up

Here in our Interactor we take the EntityGateway that was passed through from the Controller and call its saveWidget(widget) function via the IEntityGateway interface. This function returns a Promise from the EntityGateway which resolves in .then() with a newly created widget. We then call the Presenter’s presentWidget(widget) function via the IOutputBoundary interface which starts the newly created widget back up to the UI. This all happens in the Interactor’s createWidget(widget) function which was called by our Controller via the IInputBoundary interface in step 2.

OO Step 4

Here in our Presenter, we simply pass the widget to our ViewModel’s presentWidget(widget) function we created in our UI. This all happens in the Presenter’s presentWidget(widget) function via the IOutputBoundary interface which was called in the Interactor’s createWidget(widget) function in step 3. More can happen here, but not in our example.

OO Step 5

Finally our newly created widget is back home ready to be displayed in our UI. This is the exact spot (code) where we started in step 1. Updating the UI happens in the ViewModel’s presentWidget(widget) function via the IViewModel interface which was called in the Presenter’s presentWidget(widget) function in step 4.

OO Supporting Cast Members

Here are all the remaining interfaces and type definitions clumped together in one file.

2 Men Enter 1 Man Leaves

I wrote the class and interface version of this project first. I wanted to try and make it match Uncle Bob’s original diagram as close as I could. When I finished that project, I realized I could have done the same thing with functions and type definitions. So I created an identical project and replaced Classes with Functions and Interfaces with Type definitions.

And here is the difference between a Controller class and a Controller function.

Step Into, Step Over, and Step Out, the Function Way

Now lets give a stab at creating widgets with functions and type definitions.

General Differences

WidgetType is identical as the OO version above and IEntityGateway, IRequest, IViewModel, IInputBoundary, and IOutputBoundary are now type definitions instead of interfaces.

Function Step 1

Every thing is the same as OO step 1 above, other than that we are now importing a function named “controllerConstructor” instead of a class named “Controller.” And importing a function named “entityGateway” instead of a class named EntityGateway. Last but not least, the ViewModel we created is now an object with a presentWidget() function in it instead of a class with a presentWidget() function.

EntityGateway Again?

The EntityGateway does the same task as the OO version above. It is now a function instead of a class. It returns a saveWidget() function wrapped in an object.

More Wiring

Same as OO version above except we are now exporting a function instead of a class.

Function Step 2

Our Controller is still a busy place and does the same tasks as the OO version. We are now importing a function named interactorConstructor instead of a class named Interactor. We are exporting a function named “controllerConstructor” instead of a class named “Controller.” It returns a function named “createWidget wrapped in an object.

Function Step 3

Back in the Iteractor in our usecase module, we are executing the same tasks as the OO version above. We are now exporting a function named “interactorConstructor” instead of a class named “Interactor.” It returns a function named “createWidget wrapped in an object.

Function Step 4

We are now passing the newly created widget back up in our Presenter where we are executing the same tasks as the OO version above. We export a function named “presenterConstructor” instead of a class named “Presenter.” It returns a function named “presentWidget wrapped in an object.

Function Step 5

Again we have come full circle and we are back in the exact spot (code) where we started in step 1. Our UI gets updated with our newly created widget in the ViewModel’s presentWidget() function.

Function Supporting Cast Members

Here are all the remaining type definitions clumped together in one file. These are our interfaces.

All That for a Damn Widget?

Yes, but you also get the promise of a completely decoupled system where you can plug in different implementations of your outside (infrastructure blue layer) systems, including different types of UIs, external APIs, databases, libraries, frameworks and more.

We Don’t Need No Stinkin Profilers

My original hunch was that the class and interface version would be slower than the function version. So I ran both projects through my advance profiling tools of typing “npm test” and pressing enter until my finger cramped up.

My first observation was that the function version was about twice as fast, WOW. Then I decided to refactor the function version to return all of the important functions wrapped in objects so I could enforce the function names. I then ran both versions through my advance profilers and they were about the same speed.

I have no idea why wrapping a function in an object would slow it down that much. Maybe I didn’t actually get Adobe Flash completely uninstalled from my laptop and it decided to interfere. Anyways, it would be interesting to get a more accurate measure of speed using the correct tools against the compiled JavaScript.

The Take Away

The OO version has more code but may be easier to read and follow. The function version has less code but may be harder to read and follow.

Personally I like the function version, being that I have done a lot of programming in Java and I am tired of writing so many classes. One of the things I like the most about TypeScript/JavaScript is the ability to use object literals. And with TypeScript type definitions, you can now apply some safety to using object literals.

Another take away is that you don’t need to rigidly conform to the clean architecture as diagrammed above to achieve a decoupled system. For example, you could just as easily have your UI communicate directly with your use case layer bypassing the delivery layer if it’s not needed. All of these layers may physically live in different places and have different ways of communicating with each other.

Give it a Try

Here are some of the things I intend to enforce in my next project.

1. Dependencies should always go one way.
2. Dependencies should always point from your outside systems (UI, db, etc.) to your business entities and business logic.
3. Your inner layers (delivery, use case, and business entities) need to expose interfaces for the more outer layers to use.
4. You should always start developing from the most inner layer out. Start with the business entities and logic first and test. Create the interfaces that will be used and then test these interfaces. I am guilty of working the other way around. I think we all like to start with the UI, because it immediately lets us visually see how our system will look to a user. Plus the UI is where a lot of the “cool” technologies live.
5. Use TDD (Test Driven Development). Clean architecture allows you to do this much more easily. Everything is more compartmentalized and easier to mock. The implementation of the IEntityGateway above is basically a mock of a database.
6. Last but not least, be flexible. Don’t knock yourself out trying to adhere to clean architecture when that library or framework you want to use just won’t work with it. But be warned that this is probably a good indication that you will eventually have some sort of problems regarding that library or framework, especially if it wants you to extend their classes. Decoupling should be your goal.

But, But, What About…

Please ask questions and give feedback, there is no better way to learn than to get constructive criticism from your peers. And it is highly probable that I missed something somewhere.

Resources:

Code for the OO version is located at:

https://github.com/warrenbell/cleanarch-tsoo

Code for the function version is located at:

https://github.com/warrenbell/cleanarch-tsfun

ts-node

Handy little TypeScript tool.

https://github.com/TypeStrong/ts-node

The Clean Architecture by Uncle Bob

https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html

The Book

https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164

One of Many Videos

They are all basically the same except for the the first 5 minutes where Uncle Bob likes to muse about something loosely related and then makes a hard segue into clean architecture.

https://www.youtube.com/watch?v=Nltqi7ODZTM

Implementing Clean Architecture — Of controllers and presenters

https://plainionist.github.io/Implementing-Clean-Architecture-Controller-Presenter/

Clean Architecture: Standing on the shoulders of giants

https://herbertograca.com/2017/09/28/clean-architecture-standing-on-the-shoulders-of-giants/

Clean Architecture: Use case containing the presenter or returning data?

https://softwareengineering.stackexchange.com/questions/357052/clean-architecture-use-case-containing-the-presenter-or-returning-data

Clean architecture. What are the jobs of presenter?

https://stackoverflow.com/questions/46510550/clean-architecture-what-are-the-jobs-of-presenter