The Two Synchronised Arrays Problem

Imagine we have a system for managing users. Say, within the system source code, two separate arrays hold information on users. One array contains unique identifiers for users, represented by integer ids:

user ids:

[ 1, 7, 9, 4, 12 ]

The second array contains the names of the users: 

user names:

[ "Dave", "Carol", "Alice", "Eddie", "Bruce" ]

The elements at a given index correspond to the same user’s information in both arrays. Therefore, user “Alice” at (zero-based) index 2 in the names array has a user id of 9, also at index 2, in the user ids array.

The order of the elements in both arrays must be synchronised. If we remove the user with id = 9 at position 2 within the user ids array, we must remove it from the user names array also at position 2. The resulting arrays would see id = 9 and name = “Alice” spliced from both arrays at position 2:

user ids:

[ 1, 7, 4, 12 ]

user names:

[ "Dave", "Carol", "Eddie", "Bruce" ]

Can you see the problems we might run into with this flawed design?

What will happen when another programmer, unaware of the implicit relationship between the arrays, decides to reorder the user names in alphabetical order? Maybe they want to display the user names in alphabetic order in the UI:  

reordered user names:

[ "Alice", "Bruce", "Carol", "Dave", "Eddie" ]

Yet the user ids array remains unchanged (!):

user ids:

[ 1, 7, 9, 4, 12 ]

Now, when we remove id = 9 at index 2, “Carol”—rather than “Alice”—will be deleted from the user names array. Oops! 

Not only are we removing the wrong user name (“Carol”), but we are also retaining the user name we should have removed (“Alice”).

Why does this problem come about?

Even though the intent for these two arrays is to keep the ordering of the elements synchronised, there exists no mechanism to ensure this.

OK, how do we fix this?

A better way is to house related user ids and names together in an object:

users:

[
 { "id": 1, "name": "Dave" },
 { "id": 7, "name": "Carol" },
 { "id": 9, "name": "Alice" },
 { "id": 4, "name": "Eddie" },
 { "id": 12, "name": "Bruce" }
]

Why is this better? By combining the related user information into objects removes the need for order synchronisation between two arrays. If we want to delete the user with id = 9, we do so, and the entire user object disappears:

users with { “id”: 9, “name”: “Alice” } in position 2 removed:

[
 { "id": 1, "name": "Dave" },
 { "id": 7, "name": "Carol" },
 { "id": 4, "name": "Eddie" },
 { "id": 12, "name": "Bruce" }
]

And if we want to reorder the user objects by name alphabetically, then the user ids get reordered too:

users ordered by name:

[
 { "id": 9, "name": "Alice" },
 { "id": 12, "name": "Bruce" },
 { "id": 7, "name": "Carol" },
 { "id": 1, "name": "Dave" },
 { "id": 4, "name": "Eddie" }
]

Is there a general rule or principle to help us avoid such problems?

Yes, there is: The Single Responsibility Principle (SRP) from The SOLID Principles:

“Gather together those things that change for the same reason, and separate those things that change for different reasons.”

When it comes to the SRP, many of us—myself included—primarily consider the things we should separate—like UI & database. Yet, it’s just as important, if not more so, to place together functions and data structures that change at the same time and for the same reasons—like our user ids and user names.

Name Converters After The Output Type

Photo by Designnn.co on Unsplash

The question came up again. What shall we call a type converting from a source type to a destination type? Say, from an Order to a DbOrder? How about OrderToDbOrderConverter?

Wouldn’t that mean that other source inputs producing the same destination object, DbOrder, required another converter class? Say SalesInvoiceAndPurchaseStatusToDbOrderConverter? That’s a rather long name.

With conversions, we are primarily interested in the resultant type—here DbOrder. That’s the type we need to carry on with our program. 

So, I suggest that we name converters after the output type. If we are converting to DbOrder then the converter type would shorten to DbOrderConverter. For ease of use, all the methods become overloads of Convert() or Map(). The source conversion types become the input parameters.

For example:

  public class DbOrderConverter
  {
     public DbOrder Convert(Order order)
     {
        // Convert from Order to DbOrder 
     }

     public DbOrder Convert(SalesInvoice salesInvoice, PurchaseStatus purchaseStatus)
     {
        // Convert from SalesInvoice & PurchaseStatus to DbOrder 
     }
  }

The only caveat with this approach is that we carefully construct converters to be aware of only one mechanism at a time. For example, if a converter knows how to convert both an ApiOrder, a web type, and a DbOrder, a database persistence type, to an Order, a business logic type, then this is a problem. 

Why?

Consider this: Where would such a converter type be located? Within the database project? Now the database project would have to know about web! What about the web project? Not any better—the web project would need to reference and become coupled to the database project. 

What is required here would be two separate converters, each serving one adjacent transition between architectural layers. 

Clean Architecture Is Wrong

Well, not hugely wrong. But still not entirely correct as I see it. This inconsistency has been bothering me for a little while. It’s not a big deal but something to be aware of.

And this flaw does not take away from the utility of Clean Architecture as a software engineering philosophy in any substantive way. I still firmly believe that Clean Architecture—for all its abstractness and potential flaw—leads to beautifully simple application designs that can be easily modified and extended. What’s not to love?

All right, let’s get into it.

Here is the familiar schematic diagram for Clean Architecture. 

Clean Architecture

The Dependency Rule states that inner circles cannot know about outer ones. On the other hand, outer shells must depend on inner ones. In the end, some circles must know about one another, or it’s not a productive program but merely chunks of unconnected code. 

So, outer rings know about inner ones, and the little arrows depict this one-way relationship:

Use Cases know about Entities—Entities are unaware of Use Cases.

Interface Adapters know about Business Logic—Business Logic is ignorant of Interface Adapters. 

Frameworks & Devices are aware of Interface Adapters, yet Interface Adapters are oblivious to Frameworks & Devices.

I have a problem with the last statement. I believe it to be wrong.

Why?

Let’s assume the statement is correct and that Frameworks really are dependent on Interface Adapters. 

Say, in a system, we use SQL Server as our database technology.

It would mean that our generic SQL Server data access SDK should reference, or depend on, our specific data access code to retrieve data from our SQL Server database! 

Inversely, our specific SQL Server data access could not call generic SQL Server data access functions to fetch or save data since there exists no reference! How is our application-specific data access mean to do its job? 

In my opinion, the dependency should be the other way around between the outermost layers.

Interface Adapters depend on Frameworks & Drivers (red arrow).

The Interface Adapters shell connects interfaces exposed by Business Logic with those of the general code of Frameworks, libraries and SDKs. 

Adapters act as connectors between two dissimilar interfaces. To see as much, take a look at that adapter plug you’re using to connect the toaster/TV/microwave you bought in the UK to your power outlet. It has both a male and female plug interface. The toaster does not need to know about the UK adapter, and neither does your power outlet—neither depends on the adapter. On the other hand, the power adapter depends on both UK and local power outlet interfaces. 

Photo by Call Me Fred on Unsplash

Adapters always depend on both interfaces. Yet, the things that an adapter connects do not, by themselves, depend on the adapter.

Adapters depend on both interfaces.

Therefore, it stands to reason that within the context of Clean Architecture, Interface Adapters depend on Business Logic interfaces and the outermost Frameworks circle.

That’s it. I hope that makes sense.

What do you think? Am I missing something? Feel free to comment or send your opinion to olaf@codecoach.co.nz. I want to learn and see where I am going wrong! :-)

Clean Architecture – Caching With Interface Adapters

Last time we discovered the versatility of Clean Architecture’s Interface Adapters shell and how it acts as a connecting layer between the central Business Logic and our system’s specific technologies—the Frameworks & Devices. 

In the example, we had business logic that wrote to and read from a SQL Server database. The code that lets us save and retrieve data from the specific database schema belongs in the Interface Adapters. Let’s check out the design we ended up with last time:

The advantage of this design is that when the database schema changes, our SQL Customer Repository Adapter will reflect those changes yet leave our Business Logic unaffected. Here we have powerful pluggability.

OK, let’s make things more interesting.

We want to introduce an optimisation—data caching. Instead of every data read running off to the database, we want first to check whether the data exists in a cache. If it does, return the data and do not read from the database. If not, go to the database, read the data, and put it in the cache for subsequent reads. 

Now, where should the logic reading either from the cache or the database live? What about the entirely separate logic connecting us to a specific Redic cache implementation? 

Do these belong to the business logic?

No, our business logic is the wrong place. These are both data concerns. All the business logic is concerned with is a way to read this data—that’s it. How the data is retrieved is not its concern. 

OK, does this logic belong to the general SQL Server and Redis caching code? i.e. in the Frameworks & Devices shell?

No, that would also be incorrect. We don’t want to mix specific and generic data access.  

On the other hand, it makes sense to have the code connecting our specific data retrieval from Redis cache (i.e. construction of cache keys, etc.) in a module at the same level as our specific SQL Server data retrieval code, SQL Customer Repository Adapter. 

Furthermore, the logic switching between cache and database reads must sit in front of, and connect to, both the cache and database modules.

OK, so a picture is forming as to a system design that includes caching:

We now have two layers of logic in Interface Adapters—firstly, a module to switch between reading data from cache or database. Secondly, the adapters to retrieve data from Redis and SQL Server. 

The logic to switch between cache and database is abstract. It does not mention Redis or SQL Server as the given cache or database technologies. Why? We get the flexibility to plug in other caching and database technologies.

Here is an example implementation of a class managing the Customer data retrieval logic, first from a cache and then from a database:  

  public class CachedCustomerRepository : ICustomerRepository
  {
     private ICache<Customer> Cache { get; set; }
     private ICustomerDatabase Database { get; set; }

     public CachedCustomerRepository(ICache<Customer> cache, ICustomerDatabase database)
     {
        Cache = cache;
        Database = database;
     }

     public Customer GetCustomer(string emailAddress)
     {
        var customer = Cache.Get(emailAddress);
        if (customer != null)
           return customer;
        customer = Database.GetCustomer(emailAddress);
        if (customer == null)
           return null;
        // Put the customer into the cache for future calls.
        Cache.Set(customer.EmailAddress, customer);
        return customer;
     }
  }

What we have here is a decent pluggable design. However, we can improve on it further by making a small change. We’ll look into that next time.

Clean Architecture – Interface Adapters

Today we will take a closer look at the Interface Adapter shell of Uncle Bob’s Clean Architecture. 

In my first article on Clean Architecture, we learned about Business Logic but not much about Interface Adapters. Let’s do a quick recap on Business Logic and then dive into Interface Adapters.

Business Logic lives at the centre of our Clean Architecture universe. Everything inside the thin red circle is Business Logic—Entities and Use Cases. It’s what the system does, not how it does it—policy, not mechanism. 

Programming the Business Logic is usually straightforward and should be even a bit boring. It simply deals with the aspects of business workflow that are entirely devoid of mechanism—i.e. no web, mobile, database, cache, external services, email, hardware, etc.. In our world of Clean Architecture and as specified by the Dependency Rule, Business Logic is entirely unaware of these things. It knows about them only through interfaces and other abstractions.

Business Logic communicates with the rest of the system via abstractions (i.e. interfaces) represented by the thin red line. These interfaces belong to the Business Logic. It’s these interfaces that make the system pluggable.

Beyond the red line live the Interface Adapters—here things get more interesting. This ‘shell’ connects the Business Logic to the mechanisms. It’s a conduit or channel layer that calls must pass through to make it to the mechanisms: web, database, external services, etc.. 

Below is a different depiction of the Interface Adapter shell. The adapters are the Interface Adapters from the Clean Architecture diagram.

All incoming calls from Business Logic get converted into a format that the mechanisms can understand.

For example, our Business Logic makes a call—against an interface—to save a Customer. Say, we have a SQL Server database implementation—an adapter—for that interface. When the adapter receives the call to update a Customer, it will convert the Customer model to a CustomerDb model suitable for persisting to the Customers table in our SQL Server database. This adapter will convert the incoming call into one or more appropriate calls to the database. If needed, it will open a database transaction too. And the same thing will happen when the call returns— another conversion will occur, but this time from SQL Server models back to business logic models.

In the Clean Architecture diagram, the Interface Adapters are depicted as a single schematic shell yet may represent multiple shells. Some systems might be fine with a single shell, while other, more sophisticated systems may require further layers. Reasons for multiple shells might be 

• Consolidation of data from various data sources,
• Persisting data to multiple data sinks,
• Cascading data access (e.g. caching)

That’s it for today.

We will discover more about Interface Adapters next time.