DEV Community: James Eastham

On Choosing Your Complexity

James Eastham — Tue, 17 Dec 2024 08:00:00 +0000

Software is complex. I don't think that's a controversial statement. Building, testing, observing, scaling, failing, evolving. And that's before you try to understand what it is your users want the system to do.

At times, it can be a bit demoralizing can't it? Constantly fighting against this ever changing, ever growing challenge of a system that is getting more and more complex. You think back to the days when you built a "hello world" application to learn a new concept and you wonder where all this complexity came from.

Simple can be harder than complex: You have to work hard to get your thinking clean to make it simple. But it's worth it in the end because once you get there, you can move mountains. - Steve Jobs

Reading Steve Jobs' biography (which is an excellent read by the way) one of my biggest takeaways is simplicity. One of the reasons Apple became so successful is the relentless focus on simplicity.

Take the well-told story of Job's second coming at Apple. On his return, the product lines had grown massively. To the point Apple's own teams couldn't explain which Mac to pick. Internally, teams thought they were meeting a user needs when actually they were confusing customers with so many choices.

When Job's came back, he changed the entire product line to just have 4 products. Yep, just 4. 2 desktop computers and 2 portable devices. An obvious example of simplification, but it had the right effect.

When you're trying to change an entire industry, you are already dealing with lots of complexity. Changing human behaviors, introducing a new way of interacting with technology. This is essential complexity. Introducing 10x more product lines than you actually need, that is a form of accidental complexity.

What does this mean for you dear reader? Many of you will be working on new systems. New systems that will require a change in human behavior. Many of you are likely operating in a highly complex business domain where the problem space itself is highly complex.

Every single software system that exists has a certain level of essential complexity.

Take Plant Based Pizza, the backend for a pizza restaurant. Whilst not the most complex of domains, there is still a decent amount of complexity to think about. Taking orders, managing stock, managing staff, taking payments, refunding payments, preparing orders, organizing delivery drivers and getting the order delivered to the correct address.

And that's just considering the happy path. What if a payment fails? Or an order is ready but there aren't any delivery drivers available.

Think about the systems you are working on, they will inevitably have their own essential complexity.

Unfortunately for us, this complexity can't be removed. Much like Apple trying to change an entire industry, you can't get around this complexity. Trying to "simplify" this complexity can seem like a challenge.

Accidental complexity though, that's something you do have some agency over.

Accidental Complexity

Accidental complexity is the complexity that comes from the choices you make. The complexity that you (or your company) has control over.

Every technology choice you make will change the amount of accidental complexity of your system.

When Plant Based Pizza first started, they focused on delivering value quickly. At that time, there was a team of 5 building the backend. They built a monolithic application with a Postgres database to support all the different business use cases.

A single running process and a simple, flexible and well understood database technology == simplicity!

Of course, once they built the application they needed to run it somewhere. One of the team had been reading about Kubernetes recently and got the rest of the team incredibly excited about building a shiny new Kubernetes cluster.

They created a cluster, deployed some virtual machines instances as the underlying compute and used a managed database service for providing the Postgres functionality. Great, we are live.

This isn't the part of the story where I shit on Kubernetes. It's merely an example of the complexity you've just accidentally introduced into your system. Think about all the things you need to think about running a Kubernetes cluster:

Scaling nodes
Operating nodes
Securing nodes
Dealing with node failures
Upgrading the cluster
Securing the cluster
Dealing with the cluster failing
Scaling your application
Dealing with application failures

That's before you consider the various 3rd party tools you'll need to deploy inside the cluster and keep up to date.

Let's consider an alternative universe where the team made a different decision.

The team still packaged the monolithic backend application as a container image, and still used a Postgres database. They made that decision for simplicity (containers are well understood) and portability (containers can run anywhere, as can Postgres).

Instead of spinning up a Kubernetes cluster though, they used a managed container orchestrator. Something like Amazon ECS (with Fargate), Azure Container Apps or Google Cloud Run. They kept the Postgres database running in a managed cloud database service.

Let's look at the complexity you've just introduced:

Scaling your application
Dealing with application failures

A shorter list, right? Using a managed container orchestrator means you shift a whole bunch of that accidental complexity on to the cloud provider. Operating nodes? Operating clusters? Dealing with node failures? That's the cloud providers responsibility now.

There's a trade off here with cost of course, and I talked about that recently in this post on the factors of modern compute].

Continuing this tale, we fast forward 12 months. Plant Based Pizza has grown, and there are now 50 developers across 5 different teams. All teams are still contributing to that same monolithic code base, and are getting in each others way.

This is a form of accidental complexity! The complexity that comes from the decision to grow teams. Complexity you now need to deal with.

Microservices are a reaction to organization challenges. Microservices are a solution to a socio-technical problem. They aren't a solution to a technology problem.

So the Plant Based Pizza team decides to start to break their application down into microservices. As you might expect, microservices introduce their own complexity. And believe me, microservices introduce a lot of technology complexity.

At this point, there is no good reason to change the complexity of your underlying compute. You are already introducing enough additional complexity by choosing microservices, introducing another layer of infrastructure complexity probably won't help you too much.

Speeding forward in time again, Plant Based Pizza has now been refactored to microservices. These microservices are communicating with asynchronous events to make them as loosely coupled as possible. And you're still running the applications (packaged as containers) on serverless compute. You still don't have a good reason to introduce the complexity of Kubernetes.

What accidental complexity does the system have?

Scaling the applications
Dealing with application failures
Eventual consistency across different microservices
Service to service communication
Observability (it's hard in asynchronous systems)
Governance and evolving the system safely

Slightly more complexity, but still not crazy amounts right? And all this complexity is something you can have direct control over as a developer.

If you choose to run your application on Kubernetes you still have this complexity to deal with, as well as all the complexities that come from Kubernetes.

Again, this isn't a post written to bash Kubernetes. It has a place in the world. But you probably don't need it for your applications.

And if you are building with Kubernetes, you can still apply this lens of accidental complexity. Does every single developer inside your company need to understand Kubernetes? Do they need to understand Helm charts and YAML files. Or can you build your Kubernetes cluster in a way that means developers only care about shipping container images. This is, of course, platform engineering.

When I was at AWS I worked with a company (that I can't name) doing this. They were building an abstraction layer on top of Kubernetes so that developers could just ship container images and not worry about anything else. To add complexity, this abstraction layer also spanned multiple cloud providers.

Whilst it was an interesting project to work on, it wasn't for the business. They had put an insane amount of money, developer time and operational responsibility into building a service that wasn't even nearly as feature complete as Amazon ECS or Azure Container Apps. They even had a side by side comparison chart and the custom built service wasn't anywhere near.

All of that, to deploy business applications... To put it bluntly what a massive waste of time and effort.

You need Kubernetes if your ability to dynamically scale and manage infrastructure is a core differentiator for your business.

The takeaway from this rambling post is to think about the decisions you make and the complexity that introduces.

Focus on building stateless, portable, containerized applications. Focus on structuring your application code to separate infrastructure concerns from business logic (ports and adapters style). Focus on shipping those applications in an operationally light way as possible.

Reduce your operational/infrastructure complexity by adopting managed platforms and shifting that responsibility onto the cloud provider. Cost is of course a consideration here. The line item cost of running Fargate is more than a comparable EC2 instance. But that doesn't take into account the human cost required to run EC2.

You can see this line of thinking in action with the fact all the cloud providers now have some form of 'Kubernetes auto'. Where you can run Kubernetes, and then pay your cloud provider extra to take a chunk of the operational overhead.

If you focus on stateless, portable containers this compute conversation becomes largely irrelevant. Run your application in a place that makes sense right now, and you are ready to deal with future changes.

As a thought exercise, think about the accidental complexity you have in your system today? What complexity are you dealing with that isn't related to the business problem you are trying to solve. And importantly, what could you do to reduce it?

The Essential Art of Sustainable Software Architecture

James Eastham — Thu, 27 Apr 2023 18:44:57 +0000

Sustainability consists of fulfilling the needs of current generations without compromising the needs of future generations, while ensuring a balance between economic growth, environmental care and social well-being.

Sustainability; a word we hear an awful lot and one that means different things to different people. What does it mean to be sustainable? The definition above sums it up for me, fulfil the needs of the present without compromising the future.

When we think about sustainability, our minds jump to climate change, making sure we re-use our shopping bags and making sure we recycle our plastic bottles. These are noble causes, as technologists, we have the potential to make a bigger impact.

Software is taking over the world. Every single organisation on the planet is now considering itself a technology company.

This gives us a huge opportunity to have a tremendous impact. Huge portions of the world are using software every single day. Is it not our responsibility to ensure that the software we architect meets the needs of the present, whilst optimising for the future?

What makes up the art of sustainable software architecture, balanced across the environmental, economic and social pillars?

Environmental Software Architecture

The environmental pillar is imperative, and the most obvious when we think about sustainability. To create a more sustainable planet, and aim to mitigate climate change. There is a single word that springs to mind when I think about the environmental impact of our architectures:

Efficiency

The ability to do more with as few resources as possible. The art of having the right resource, in the right place, at just the right time. With some of the recent innovations in software development, efficiency is a practical thing to implement.

Leveraging the cloud for efficiency

A report by S&P Global Market Intelligence discusses the impact of moving workloads to the cloud.

"Simply moving to using green energy is not going to deliver the desired — or the best — carbon reduction. The best place to go from a carbon reduction perspective is the cloud."

The report estimates that a combination of more up-to-date equipment and a better utilised fleet of hardware amounted to an 85% saving in energy usage. This is before considering the fact that many cloud providers are moving their data centres to use 100% renewable energy.

Architect for Efficiency

Many of you have heard of the cloud, and are likely already running some kind of workload in the cloud. But once in the cloud, how can we architect for efficiency? Thankfully, the architecture patterns that are the most efficient also are the most optimal ways to build modern software.

Serverless-first, event driven architectures are a prevalent architectural pattern when building cloud native systems. Remember, one principle we are looking to optimise our systems is to do more with less. A system that scales to zero when it’s not in use, and reacts to events as they happen... What could’ve more optimised than that?

Let's unpack the two terms:

Serverless first: A mindset when building software that defaults to leveraging serverless compute options like AWS Lambda. Shifting the operational burden on to the cloud provider. This enables the cloud provider to be efficient with the underlying compute as they can shift workloads around to meet demand.
Event Driven Architecture: A pattern in which business events drive functionality, coupled with an asynchronous first approach. A system which reacts to events as they happen, and defaults to running things asynchronously, provides ample opportunity to optimise for sustainability.

Of course, a serverless event driven architecture may not always be the most optimal or even the most practical. I'm looking at all you GPU compute heavy folks out there. That said, it's still possible to architect for efficiency.

Defaulting to a single type of compute everywhere in your system is an anti-pattern. Choose the right compute for your use case and optimise accordingly.

If that means running big GPU intensive EC2 instances, then go for it, but consider how you could be more efficient with the compute that you have.

Think asynchronous first, default to using managed services and take intentional step outs away from this pattern where required.

Code for Efficiency

Code is a fundamental part of any software system. There is so much nuance in an individual business use case that hand written, custom code is inevitable. Many of us (me included) default to familiarity. Debating the merits of a language based on syntax, performance and legibility (I’m looking at you Python).

Something I rarely hear mentioned in programming languages, is the environmental impact. A group of extremely smart people out of various universities in Portugal have ran this analysis for us.

The report linked above analyses 27 well-known software languages and monitors the performance using 10 different programming problems, expressed in each of the languages. An interesting observation from this paper is that:

"Compiled languages tend to be, as expected, the fastest and most energy efficient ones. On average, compiled languages consumed 120J to execute the solutions, while for virtual machine and interpreted languages this value was 576J and 2365J, respectively. This tendency can also be observed for execution time, since compiled languages took 5103ms, virtual machine languages took 20623ms, and interpreted languages took 87614ms (on average)."

I find this even more interesting considering how prevalent interpreted languages like Python and NodeJS are in our modern software world.

Unsurprisingly, the top 5 languages for both energy efficiency and execution time:

C
Rust
C++
Ada
Java

And the bottom 5 for energy:

Perl
Python
Ruby
JRuby
Lua

And execution time:

Lua
Python
Perl
Ruby
Typescript See, my looks at Python weren't completely off the mark

Quick side note, Rust has also ranked as the most beloved programming language in the Stack Overflow developer survey for 7 years running (as of the 2022 survey).

Now I'm not suggesting you all go away to learn Rust (although it's a lot of fun) and re-write your entire applications. We will see more on this when we move on to the social pillar of sustainable architecture. But understand the efficiencies of each language is important.

Maybe you don't re-write your entire application, but you re-write the most commonly used pieces of functionality to use a more efficient language. Taking Rust as a specific example, combined with AWS serverless compute, this is also likely to save you money as well.

The Social Pillar of Software Architecture

When I first looked at the pillars of sustainability, the social one made me stop and think. There is the obvious social impact of software; building software to solve the world's hardest problems. But can be dive a little deeper into that, what about the day to day social impacts of the people building the software?

I'm sure many of us have worked on applications where the code was an unruly big ball of complicated mud. Equally, I'm sure some of of us have worked inside code bases that are a perfectly modularised thing of beauty.

Not all of us can work on software that is 'changing the world', but we can all aim to build software that considers the needs of future generations.

Enjoyable to work on

One of the most important characteristics of social software is a code base that is enjoyable to work on. I want to go to work and have fun solving problems, instead of battling with complexity, un-necessary abstractions and hard to read code.

The boy scout rule is an excellent mantra to use here:

Always leave the code better than you found it.

Simple, easy to remember and forces you to think about continuously improving code. Maybe this is as simple as re-naming a variable to be more expressive. Maybe it's adding additional services and functions to make the code more intentional.

A rule of thumb I try to follow (and often fail at) is to write code that reads like a story. If you’re using a compiled language, using long easy to read variable names is irrelevant because the compiler will compress them down.

for (var x = 0; x < counter; x++)
{
    var currentIterator = list[x];
}

for (var currentProductIndex = 0; x < maxProducts; currentProductIndex++)
{
    var currentProduct = allProducts[currentProductIndex]
}

I know which I prefer.

Reduce cognitive load

Cognitive load is devastating to a software developer. Our brains can only hold so much information in our head at a time. When working on tasks, it functions more like a stick of RAM than an SSD.

Reducing the cognitive load of a system enables your fellow developers to make more informed decisions about functionality. If I can consume a library with a well defined API taht abstracts away a complex task, that reduces my cognitive load. Giving me more mental cycles to focus on the problem at hand.

Defaulting to a modular design, whether that be a modular monolith or microservices, reduces this cognitive burden. Especially when coupled with domain driven design, defined bounded contexts and organising teams around features and not technical domains.

If I'm a developer working on the product microservice, I can become fully embedded in the world of products within the organisation. I need to get some customer information, well the customer team has a well defined API interface with excellent documentation. They even produced an SDK for communication, excellent! Cognitive load removed.

Fast Feedback

Dopamine; the neurochemical responsible for almost all of our modern addictions. That little burst of pleasure you get when you get a new notification... That’s dopamine in action. It’s not all bad though. We can leverage dopamine in positive ways as well.

Fast feedback loops within the application, typically with a well defined set of test cases, help enable this reinforcement. Imagine working within a code base and continuously running the test cases seeing all of them green icons light up. You can feel that dopamine hit already, can’t you?

These fast feedback loops also help enable mastery of the domain and language. A core component of mastering anything is quickly being able to course correct.

Tests light up green = dopamine hit

Tests go red = an opportunity to increase your mastery

Extensible & Observable

The last topic I wanted to touch on around the social impact is that of extensibility and observability. I want to work within a system in which I can easily extend it to add new functionality, and observe/debug it when things go wrong.

Some of the most frustrating times in my career have been through trying to debug a problem that has little to no logs or tracing.

Building with extensibility and observability in mind will impact the needs of future developers, meeting our commitment to the social pillar.

The extensibility angle ties nicely in with our serverless-first, event driven mindset. An event driven system is extensible. If your system behaviour is driven by a set of business events shared between bounded contexts through some kind of central event stream, hooking into that event stream to add new functionality becomes incredibly easy. Coupling that central event stream with a schema registry and you are in a fantastically extensible place.

The observability angle applies to much more than the social component. Observability will help us environmentally and economically (you can’t measure what you can’t improve), as well as socially (understanding what the heck is going on in a system).

The mindset of the sustainable architect is to be serverless-first, asynchronous and event driven by nature with observability as a fundamental tenant.

The Economic Pillar of Sustainable Architecture

If the social pillar made me pause for thought, this one had me stumped for a little whilse. The definition of the economic pillar is:

This pillar is based on companies’ ability to contribute to economic development and growth.

As architects and engineers, we have little say in our organisations’ wider policies on contributing to economic development and growth. So what does economic development and growth mean within the context of software?

Within this pillar, I see the practical patterns & steps you can take as an architect to contribute to the development and growth of your software system sustainably. There are many ties with the environmental pillar here, with efficiency being a fundamental component. So let's consider the economics of the different system components.

Compute

We’ve discussed compute already, defaulting to a serverless-first mindset. But there are several additional patterns and practices to help enable sustainable use of compute.

The first is to optimise for stateless compute. Aim for your application layer to hold little to no state. It helps to enable the event driven, reactive compute we are looking for. If your application requires in-memory state, then you restrict the type of compute you can use, as well as how you and your cloud provider can shift that compute around.

Holding an element of data in memory may be useful from a performance perspective, caching for example, but you should not rely on it.

Second, and related to the earlier point, optimise the actual compute itself. This may mean using more optimised chipsets (x86 vs ARM). Or it may mean optimising the type of compute you have. If you’re within the serverless world, this may mean optimising the memory allocation of your function to get the optimal performance vs memory balance. If you're in the physical server world, this may use the most optimal instance type (compute vs memory vs network optimised) for your specific use case.

There is not a one size fits all in compute, it always depends.

Networking / Data Transfer

The environmental impact of networking and data transfer is difficult to quantify, as there are so many variables. That doesn’t mean we can’t be more economical though.

Ask yourself the question, what is the minimal viable data I need to perform the task I have? The backend for front-end (BFF) pattern is excellent for this, alongside technologies like GraphQL. The aim here - ensure only useful data is transferred.

Compression is another decision point that we will see again when we discuss storage. Many workloads, including almost every single one I have built, default to JSON as the data transfer medium. Understandably so. It’s human readable and relatively succinct. But actually, as we are passing data over the wire, can we not make this even more efficient?

Protobuf and MessagePack are two such technologies specifically targeting efficient binary serialization, whilst still maintaining an element of schema and operability.

Caching and data transfer distance are two concepts that go hand in hand. That is using content delivery networks (CDN) to get the data and compute as close to your users as possible. Caching data at the end, as well as running compute at the edge, reduces the network ‘cost’ of transferring the data.

Caching is also valuable within our backend systems. If you are working within a micro-services architecture, it’s likely you have an element of communication across a network. Consider if you could cache external data within your own service to reduce the network transfer cost and secondarily reducing the compute load on your other systems (a big tick in the social pillar here as well).

Micro-services architectures, coupled with event driven architecture, also bring up an important point of debate around event schema design. There is a probably a separate blog post within this topic, but determining what you include in your event is important. Events that are too sparse result in many calls back to the producer service to retrieve additional data. A ‘fat’ event results in a larger initial cost as it distributes the event to all the subscribers.

That said, if we truly optimising for sustainability, my preference is for a fat event with a combination of JSON & Binary. We compress the main body of the payload into a binary format using a schema-based compression like Protobuf, with additional metadata in readable JSON. That strikes the right balance between a well-known schema, reduced network calls and an optimally sized payload as well as providing the ability for subscribers to filter data.

{
    "metadata": {
        "eventType": "orderCreated"
    },
    "filters": {
        "orderValue": 256.82,
        "geo": "EN",
        "customerAccountId": "123456",
        "deliveryType": "PREMIUM"
    },
    "payload": "<BINARY_DATA_GOES_HERE>"
}

Storage & Analytics

Many of the concepts around compression discussed above apply equally to storage. The most important architectural consideration here is to understand your data access patterns. Regardless of the storage technology you are using, understanding how the data is going to be accessed is vital in understanding how you can optimise.

For example, let’s consider the use of DynamoDB as a primary data store. Used in the most efficient way, access to DynamoDB uses a combination of partition and sort keys. Any other data stored against an item isn’t available to query.

In this scenario, leverage technologies like Protobuf to serialize the main bulk record to binary and store that in a more efficient way. An additional benefit here, you’ll probably reduce your costs as well.

Considering your access patterns will also enable you to optimise the performance of your queries, having the knock on effect of optimising your compute. It’s a wonderful sustainability flywheel we are getting ourselves into, isn’t it?

The other consideration around the data itself is what you store and how long you store it for. Continuously ask yourself the question about the data being stored and if all of it is necessary. And if it is, how long do you need to keep it around for?

And finally, think about your recovery point objective and recovery time objective. Do you really need to be taking full database backups of your product review database every 5 minutes and storing them for up to 3 years? Probably not. Much like the compute option, fit the technology to the use case. There is no such thing as a one size fits all storage solution.

Now some of these ideas become less useful when considering analytics. A nicely compressed piece of binary data is excellent for our storage costs and retrieval efficiency, not so useful for running custom analytics queries. How can we be pro-active about our analytics workloads?

Unlike the compute recommendation of being reactive, only running applications when required, for analytics I would suggest being much more pro-active. Specifically, transform your data into a format that is suited for custom queries. Extract, transform, load (ETL) jobs have been around for a long time. One of my first jobs was developing ETL jobs. Using these pro-active mechanisms for pre-formatting data ensures that when these complex, custom queries come in, they are working in data sorted in the most efficient way.

If you combine this with scheduling your ETL jobs to run during low-carbon intensive periods, you can really push up the sustainability of your analytics workloads.

Charachterize. Observe. Improve

I wanted to close out with a very specific section on architectural thinking. All architectures comprise the architectural ‘-ilities’. These ilities are often at odds with each other and are at the core of the often heard phrase ‘it depends’.

Performance
Scalability
Availability
Reliability
Security
Maintainability
Flexibility
Configurability
Personalizability
Usability
Portability
Conformance to standards
Efficiency
Responsiveness
Interoperability
Upgradability
Auditability
Transactionality
Adminstrability
Sustainability (my addition)

For example, it's difficult to combine performance and security. Increasing security typically means slower performance. If we consider sustainability to be a non-negotiable, that naturally makes some of the other ‘-ilities’ fall become clear as well. This is very much my opinion, but these are what I would consider the most important ilities for sustainability.

Scalability
Security (it's job zero, it makes it on to every list)
Flexibility
Usability
Efficiency
Interoperability
Upgradability
Auditability

Once we have defined the charachterisitics we want our system to have, we can use fitness functions to ensure we have continual feedback for conformance to the core tenets of our system.

For example, if scalability and efficiency are our core tenets to enable sustainability, we may write fitness functions to:

Monitor resource usage and how optimally we are consuming the resources we have allocated to a task
Monitor how often we are using compute when there is no work to be done
Ensure no individual piece of compute runs for longer than 100ms, and uses more than 128mb of memory
Monitor scaling behaviour, and how quickly our system adapts to demand

Fitness functions should run both as triggers, as part of CICD, and continually as part of ongoing system monitoring.

For all of that to work, observability is another non-negotiable '-ility' in all of our sustainable architectures. Generating trace and metrics data to understand our systems enables us to be data driven about how we optimise and gives our fitness functions something to work with.

Wrapping Up

If you’ve stuck with it this far, thanks for reading. If I’ve lost you, well, you’ve probably not got this far anyway, so this sentence is becoming irrelevant.

Frankly, this post has been a bit of a brain dump. A coming together of my technical skills and my values to want to inspire change in the world.

I truly believe that as software practitioners, we have immense potential to bring about genuine change in the world.

Let that carry into everything you do.

James

Learning Software Architecture? Start With Why!

James Eastham — Fri, 07 Apr 2023 11:29:22 +0000

61,698,933!

That's the number of views (at the time of writing) Simon Sinek's TED talk on 'How great leaders inspire action' has. A fundamental idea from the talk is the idea of a golden circle, and how we default to approaching things in the complete opposite way.

Many of us approach things with an outside in approach. We start with what, take steps to work out how, and rarely worry too much about the why. This is a flawed approach. Starting with why, at least in business, explains your purpose and why you are doing the thing you are doing. People buy your why, not your what. Yet many businesses start with the what, and completely lose the sense of purpose. Your why drives the relationship with your customers.

You might wonder how this short piece of business advice relates to how we teach software. But let's take this same golden circle, and apply it to how many of us try to learn about software architecture.

People interested in software architecture often ask me which AWS service to learn first. Or which certification to take. Do I learn about serverless or containers? Event driven architecture or microservices? These areas are inevitably ones you will need to learn about at some point, but they are unlikely to be the best the place to start.

You are starting with what! Instead, start with why.

Starting with Why

Build your knowledge from first principles. Technology iterates on itself quickly, and every iteration takes a problem seen previously and makes it better. These iterations stack on top of each other to give us the technology choices we have today.

On-Premise servers -> Elastic Cloud Servers -> Containers -> Container Orchestrators -> Serverless

The most famous saying in software architecture is it depends. Taking a specific technology driven approach, to learning software architecture limits your 'it depends' to the specific niche of technology you are learning. If you have a hammer, everything looks like a nail. If you have a Lambda function, everything looks like it's event driven.

Instead of asking why exactly are we trying to hang this thing from the wall?

Let's take databases as an example. DynamoDB is a popular, fast and flexible NoSQL database service provided by AWS. It's actually my second favourite AWS service (just beaten by Step Functions if you're interested). DynamoDB is largely schemaless. The schema of the items you write is determined at runtime.

What this means is that you can store almost anything in DynamoDB, in any format. It's an incredibly flexible database that could probably fit almost any application use case.

That flexibility is one of DynamoDB's biggest strengths, and also it's greatest downfall if misused. If you spend all of your time learning about the specific API's of DynamoDB, you understand single-table design, global secondary indexes, sparse indexes, read and write capacity units but never understand the why... Well then there is every possibility you may choose to use DynamoDB in a scenario where it doesn't actually fit.

Traditional relational databases still have a perfectly valid use case in modern technology. As do graph and time series databases. There is a reason AWS (currently) has 15 different database services. Yet if you are stuck in your little DynamoDB bubble you never even look up to see what else is out there.

I'm not suggesting everyone needs to go deep on every single different type of database, but understanding the history of why we got to where we are is important. Designing Data-Intensive Applications by Martin Klepmann is an absolute goldmine for this content. Even reading the first 3 chapters of what is an admittedly dense technical book, would give you a huge architectural advantage because you understand enough to make an informed decision.

A Generalist Growth Mindset

In the excellent book Range David Epstein discusses how being a generalist is a fantastic skill to have. The cross-pollination of different ideas, from different domains, leads to better decision making and more creative thinking.

Having a general idea of the use cases for the different database options, a set of first principles that guide your decision making, forces you to start from the problem you are solving and work outwards to what database you are going to use. Suddenly, the decision between 16 different AWS database services becomes less challenging. You're making your decision based on the specific problem domain, applying your general knowledge of all databases to work out to the best technology choice.

Once you've gone through the why and reached the what, it's time to double down on a growth mindset. Professor Carol Dweck proposed the idea of fixed and growth mindsets. A person holding a fixed mindset assumes that their abilities are immutable, whereas a person with a growth mindset acknowledges that they can acquire and develop any new skill with sufficient time and effort.

Fixed = I don't know
Growth = I don't know, yet

Baseline your thinking as a generalist and start from first principles, before doubling down on your growth mindset to pickup a new technology as and when the time arises.

Starting from why; a skill all architects, aspiring or otherwise, should cultivate at all times.

As always, thanks for reading.
James

Essentialism in Software

James Eastham — Fri, 31 Mar 2023 06:41:40 +0000

"The Way of the Essentialist involves doing less, but better, so you can make the highest possible contribution. The Way of the Essentialist isn’t about getting more done in less time. It’s not about getting less done. It’s about getting only the right things done."

Greg McKeown

Essentialism is a book that I frequently revisit, typically at least once or twice per year. The core idea is to focus all of your energy on one thing and do it well, rather than spreading yourself thin across multiple tasks. This approach differs from the norm, where many of us tend to work on multiple things simultaneously, leading to a dissipation of our energy in different directions.

This might be multi-tasking in the well known sense. Focused work, whilst checking email every couple of minutes and being distracted by constant Slack notifications. Or it might be the multi-tasking that sits slightly under the surface. The kind that has us working on multiple different projects, in multiple different disciplines at the same time.

Having interests in multiple different areas is a great strategy, it allows us to cross-polinate ideas and solve problems in innovative ways. This is discussed at length in the excellent book Range by David Epstein. But a clear seperation helps our brains focus.

I've been particularly guilty of this myself. In the past, I would sign up for any and everything that even remotely related to my interests. Learning to say no or delegate has been a tough lesson that I've had to learn in the last 18 months. While it may work for a little while, and you may achieve some success, it's not a sustainable strategy. Saying yes to everything and attempting to advance multiple projects simultaneously inevitably results in little progress anywhere.

Have one focus, commit fully, then move on to the next thing. The next idea. The next area of interest.

Essentialism in software

You're probably wondering how this relates to software. But there are some interesting ideas we can take from essentialism and apply it to the way we think about software.

This isn't a new idea. In Domain Driven Design, Eric Evans discusses core, generic, and supporting subdomains:

Core: The unique selling point (USP) of your business, the thing that sets you out from your competitors and delights your custoemrs.
Supporting: Areas of the system that are required for your core domain, but aren't differentiating with the competition and there aren't any off the shelf solutions available.
Generic: Areas of the system that are completely undifferentiating.

Already, you can start to see how essentialism fits. As much as possible, the focus of a software organisation should be in the core domain. Improvement in this area, will have the most impact on your customers.

Yet, even with this in mind I see many companies getting lost in supporting and generic subdomains forgetting the value they actually want to deliver to customers. They are expending energy in every possible direction, instead of a single minded focus.

Undifferentiated Heavy Lifting

Werner Vogels, CTO of Amazon, is well known for talking about undifferentiated heavy lifting. The cloud enables you to shovel this work on to the cloud provider leaving you to focus on adding value. This is a big step towards essentilism. Gone are the days of racking servers and crossing your fingers that the backup generator kicks in quickly during a power cut.

But even in the modern, 'cloud native' world, there still seems to be an obsession with continuing to focus on this lifting. On these supporting and generic subdomains that your customers don't care about. Yes, your customers care that your application is always accessible. They don't care if you're doing that with serverless compute or with a container orchestrator.

Let's stick with the container orchestrator idea for a moment. I don't want this next section to feel like I'm shitting on Kubernetes and I fully appreciate there are valid use cases for a container orchestrator. But let's compare and contrast with something like AWS Lambda, or if containers float your boat then AWS AppRunner.

Let's consider this for a startup or early stage organisation trying to launch a new idea.

Even when levearging managed services like Amazon Elastic Kubernetes Service (EKS), there is an awful lot of infrastructure management and configuration needed. This is before you even get the first MVP of your product in front of a customer.

Comparing that with a service like AWS Lambda, where I can write a piece of code that focuses only on my business logic, deploy that to the cloud and be confident it will scale when required. No infrastructure management, no setup beforehand. An unparalleled time to value.

Low Code Applications

There is a step even a beyond Lambda and serverless compute. A step that enables applications to be built without a single line of application code. What application code requires the least amount of heavy lifting? Code that is never written.

AWS Step Functions is my favorite AWS service. It offers direct integration with almost any AWS service through its SDK integrations. By leveraging this capability, you can potentially build out large parts of your supporting and generic subdomains without writing a single line of application code. With no need for infrastructure management, configuration, or even updates to libraries and changes to code, your non-core subdomains become about as low lift as they could possibly be.

If you're interested, I have a repository on GitHub that implements a review translation and sentiment analysis service without a single line of application code. Or if video is your thing, my talk at the AWS Community Summit 2022 where I discuss this repository.

The Essentilist Spectrum

I'm not a purist, and appreciate there are absoloutely scenarios where greater control is required. GPU heavy workloads, developer familiarity, longer running workloads. This isn't a debate about Kubernetes vs Lambda vs native service integrations. That was meant purely as an example.

However, all of these ideas sit along a spectrum of essentialism. At each stage, you choose to introduce an additional pressure on the energy your organisation has to move forwards. To implement features. To delight your customers.

This spectrum fits nicely with a 'serverless first' mindset. My view on serverless first is quite simple. Default to as little undifferentiated heavy lifting as possible and increase as required. I would typically couple this with a view on core vs non-core subdomain.

For example, if I am designing a new feature for a service that exists as a supporting sub domain I would go through:

Step Functions with native service integrations
Lambda
AppRunner
Fargte on ECS
EC2

You can apply similar heuristics to areas outside of compute (DynamoDB vs RDS for example).

I realise many decisions are a lot more nuanced, and jumping straight into the implementation details is not typically where I would begin. But once we are down in the weeds, I find this an excellent way to add business value whilst reducing operational overhead.

Our software is essentialist.

Thanks for reading,
James

Thinking in Patterns; The Importance of Language in Software Architecture

James Eastham — Sun, 26 Mar 2023 20:16:20 +0000

Language is the foundation upon which all communication is built. It's how we share our thoughts, feelings and ideas with one another. And in the world of software, language is just as critical. How we talk about and describe the structures and patterns we use to build software can have a significant impact on the success of our projects.

This becomes even more important when building serverless, event driven applications built up of small, loosely joined pieces of functionality. It's like playing with LEGO bricks, but instead of creating a colorful spaceship, you're constructing a well-oiled software machine. And we've all been there when we can't quite understand how two pieces fit together. In this blog post, we'll explore the importance of language in software architecture and how the words we use can shape the way we think.

Patterns Aren't a New Thing

Software patterns aren’t a new concept. The famous ‘gang of four’ published Design Patterns back in October 1994. Whilst focused on object-oriented programming languages like C# and Java, it provided terminology to help developers communicate with each other.

If someone mentions the builder pattern to me, I understand what they are trying to achieve.

It also aids the readability of code. If I jump into a new code base and see classes named OrderFactory or ConfigurationBuilder I have a rough idea of what the intended functionality of that object is without needing to work through multiple code files.

Patterns reduce cognitive load, providing helpful guidance to our brains when processing new information

There is a part of our brain (the neocortex for any fellow neuroscience nerds) that recognises patterns. The pattern recognition process involves matching information new information with information already stored in the brain. Using a common language aids that matching process, much like a memory pointer in programming.

Following on from the Gang of Four book, Patterns of Enterprise Application Architecture and Enterprise Integration Patterns were both published in 2012. Both are brilliant books to have as a reference if you don’t have them sat on your bookshelf already.

These books are a reference guide to help us talk about the systems we build. To give us a common language, a set of patterns that describe the systems we are building. Somehow, this got lost along the way.

Lost in a sea of implementation details

When was the last time you saw an architecture diagram or design that mentioned a channel adapter? Or using scatter-gather to meet our business use case. Instead, as architects, we default (and I’m guilty of this as much as anyone) to the implementation details. To the services sat underneath.

I pulled this diagram straight from a repository on my GitHub. For someone unfamiliar with AWS services, how would you understand what is going on here? You could establish there are 5 separate components, each made up of 2 or more individual pieces. Yes, you could deep dive into the code and try to work it out. But this diagram tells me nothing about my architecture, and everything about my implementation details.

Both are important, of course. But we are missing a step. We are jumping straight to the implementation without considering what patterns we want to use.I have a particular liking for Amazon Event Bridge. If I need to communicate between 2 systems asynchronously, that’s my default. This is a bias I’m trying to break. So let’s explore this requirement in a little more detail.

There are 2 systems that need to communicate asynchronously, which might seem like a pretty straightforward ask. Depending on biases you hold from systems you’ve worked on in the past, or what you're most familiar with, you’ll probably end up with one of:

Amazon EventBridge
Amazon SNS
Amazon SQS
Amazon Kinesis
Kafka
RabbitMQ
Other message broker/streaming/queuing system that allows components to be decoupled

The question then becomes, which one do we pick? Comparing service to service at an implementation detail level will lead to a lot of confusion. It’s the most common question I get asked when talking about event driven architectures. What’s the difference between SNS & EventBridge? It’s confusing, right?

There’s an easier way than getting lost in the features of a specific service, though. That’s through good communication and the use of patterns.

A Better Way

This is where communication is a vital tool in the toolbox of any architect. The answer to the question of ‘I need to communicate between 2 systems asynchronously, which service do I use?’ is, of course, another set of questions:

Do you need to guarantee that only one receiver processes the message?
Do you need to distribute the message to an unknown number of receivers?
Do you want to keep each type of message on it's own individual channel?

There are a bunch more questions we could ask here. But what began as a simple question that my bias told it could answer with Event Bridge turned out to not quite be that simple. And, in my hypothetical scenario, the business requirement is for strict ordering and a guarantee that only one receiver ever processes the message. My first decision was one that future James would not have thanked me for.

Taking that same list of questions, we can apply a pattern which then leads to the right implementation detail falling out:

Do you need to guarantee that only one receiver processes the message?
- Point to point channel / Amazon SQS
Do you need to distribute the message to an unknown number of receivers?
- Publish Subscribe / Amazon Event Bridge
Do you want to keep each type of message on it's own individual channel?
- Message Channels / Amazon SNS

Describing our architectures through the lens of patterns & requirements, as opposed to services, simplifies the communication between both existing and new developers. If I join a new team, and I’m told we have a point-to-point integration between these two services that guarantees only one receiver processes the message, I have learned an awful lot about the system function. If I’m shown an architecture diagram that contains a map of service icons, I’m up the creek of implementation details without a paddle.

Knock on Affects

There’s a more subtle benefit to thinking about systems in this way, and that’s one of bias. I might work for weeks on a well-architected system using specific AWS services only to be told that ‘You can’t use Event Bridge because the security team said so’. My architecture diagram falls to pieces. I might push back, or spend hours with the security team discussing what we can do to make Event Bridge available. This might be the right approach, but there’s also a pretty good chance it’s sunk cost bias at play.

If I built my architecture diagram using patterns, instead of an Event Bridge service icon, there would be a ‘publish subscribe’ channel. Event Bridge isn’t usable, ok then let’s use SNS. The CTO mandates we must use non-AWS managed services, ok let’s substitute in Kafka or RabbitMQ.

One might look prettier, but the second much more clearly demonstrates my intentions as an architect.

Think in Patterns, not in services

The risk here, is a re-introduction of the ivory tower architect. An architect who thinks in patterns and abstract concepts but never spends any time building. That is an important point to close this post. Think in patterns, design in patterns, but never lose that builder mindset. The balance is key in the world of software architecture.

Thanks for reading,
James

Event Modeling By Example

James Eastham — Wed, 21 Jul 2021 20:19:13 +0000

Good design is a fundamental thing for me when it comes to building applications. Yes, there is a time in a place for a quick functional program that does a simple job ala scheduled batch file. But in almost all cases, committing even a small amount of time to thoughtful design has huge ramifications on the long-term success of a project.

Design for where you want your application to be, not where it is now

An element of this is the principles of Domain-Driven Design (DDD). For those who aren't aware, DDD is the name of a book written by Eric Evans in 2003 detailing a methodology for designing software. At its core, it maps business domain concepts into software artifacts.

Whilst I can heartily recommend the big blue book, I did find it difficult to take practical steps that I can use when working with clients in the real world. That is where event modeling comes in.

Introduction to event modeling

Event Modeling is a term coined by Adam Dymitruk. It builds upon a lot of the concepts set out in DDD. The main focus is on the events that happen in a business, as all software is at the core is a series of events happening one after another.

If the software focuses on things that the business can understand, the system can be easily understood by anybody looking at it. That includes everyone from C suite execs through the development team and even to customer service representatives with no background in IT.

There are some fantastic resources on Adam's website https://eventmodeling.org, but what I wanted to-do today was walk through my process for implementing event modeling in a 'real' application.

Step by Step

Before I dive into the step-by-step, I want to identify a couple of tools and resources I use for this process.

The first is the article on Adam's website on 'What is event modeling'. It adds a lot of context to the steps I'm going to follow in this article. I can recommend going to read that article before continuing with this one.

The second is Miro. Miro is a virtual whiteboard that allows multiple people to collaborate on the same board. Given more and more of the world is moving to a completely remote way of working, it's an invaluable tool when it is simply impossible to all stand at a physical whiteboard.

Even if you do use a physical whiteboard initially, it's a great idea to move that to a digital tool for future developments. Online, backed up, and accessible anywhere - what's not to love.

So now, on to the steps.

Brainstorming

The first step of the process is to brainstorm ALL of the events that affect within the business domain being modeled. It's important to have stakeholders from all parts of the business in this session as each may have a valuable piece of insight into the workflows.

What you are looking for here is just a brain dump of all the things happening in the business. There is no need to organize or categorize at this stage, just get it all out there. Remember, an event is always in the past tense. SubmitOrder is not an event but OrderSubmitted is.

Timeline

The second step is the first layer of organisation. All of the events should be added to a timeline that shows the journey through the system.

For anyone who has ever ordered food online, this series of events should be familiar.

OrderSubmitted
StockChecked
PaymentProcessed
OrderCooked
OrderDispatched
OrderDelivered

The other thing you'll notice on this diagram is that I've identified a couple of important events. These events are the ones that are fundamental to the business. In this example, taking payments and delivering orders are the two things needed for the restaurant to succeed.

Storyline

The third phase is to begin thinking about user interactions and the different people taking part in the process. Wireframe mockups are a great tool. These mock-ups don't need to be concrete though they are just to give a rough idea of the interactions with the system.

I find it helpful to split these down into swimlanes for the different people/systems who affect the system. It would also include any external systems (payment processors, CRM systems) that change state, albeit without direct human intervention.

In this example, I'm more concerned about the backend application than the look of the frontend. For that reason, I've just included some icons to indicate there will be interactions from either a UI or an external system.

Notice how I've included the cog icons for the stock checker and payment processor. It shows that there is a process that happens to cause a change in the system state. The interaction may not be driven by a human, but it is an interaction all the same.

Interactions

Phase four is where things start to get interesting. It is where I begin to link the UI/UX to the events via commands.

Taking the first workflow as a specific example:

A customer interacts with a UX screen that allows them to make an order
The UX sends a SubmitNewOrder command
A OrderSubmitted event is raised

Taking a look at the whiteboard now, there is a clear flow from left to right. This interaction submits this command then this event happens.

It can be beneficial at this point to talk about the command contents. Thinking about what makes up a SubmitStockCheckResults command can help to identify any missing data from earlier in the process.

Informing the users

Phase five is where I start to look at the information users need to make decisions.

I do this using bespoke read models that project the event information into a useful format for users. You can see these below on the green post-it notes.

For the stock checker to reliably check the stock of orders, it needs a view of all the orders that are currently waiting to have their stock checked. For the kitchen to cook the orders, they need to see a list of all the orders that have been paid and are awaiting production.

Again, it's important to not get bogged down in details here. It doesn't matter if you're using a queue, an event stream, or a relational database.

What matters is that the data needs to be exposed in a friendly format that can be used to make informed decisions about the system.

Adam refers to these read models as to-do lists, and I quite like that idea. A to-do list is a concept that almost everybody can understand. If I were to start talking about queues or a messages bus I would likely alienate the non-technical folk.

The system is saying here are some data items that need to have an action performed on them.

I find it's at this stage that any holes start to become apparent. For example, in the above screenshot, a SubmitPaymentResult command happens results in a PaymentProcessed event. This event has a PaymentSuccess field that looks like it should be conditional in the workflow.

When a PaymentProcessed event happens the order is placed on the OrdersAwaitingCook to-do list. But what if the payment fails?

And this is where the value of event modeling becomes apparent. You have got a room full of people, both technical and not, who can talk the same language and rationalize about the behavior of the system.

Architect: "So, what happens when the payment is processed but it fails for some reason?"

Mark in Order Processing: "Oh, if that happens I would just notify the customer to inform them that their payment has failed."

Architect: "Ok, so how would that interaction happen?"

Barbara in Customer Service: "Well, if the customer was stood in-front of me in the restaurant I could ask them to change their payment method. If they are ordering online, then I need them to know about the failure instantly so they can change their order, or at least know that they aren't going to be getting a pizza delivered."

In a matter of moments, I have learned something about our domain and can amend the flow of events on the fly. In the first iteration of the timeline, I processed payments and then added all orders to the OrdersAwaitingCook to-do list. Now, I have a small branch at this point in the case of an order failing.

Service grouping

Almost there now.

The penultimate stage is to group the events into their service layers. Hopefully by this stage, you should start to see some pretty logical boundaries between the different events in your system.

An important note here, these service layers should be based on the business domain and NOT on a perceived microservices architecture. Remember, you are trying to keep everybody interested and on the same page.

It can be good at this stage to think about the make-up of teams. A team of people, technical and non-technical, can now begin work on an individual service layer. These service layers can then develop independently, but the shared vision is also well understood.

Yep, it sounds a lot like microservices. Resist the temptation, don't say the word!

Scenarios

The final stage is to build specific scenarios out of the workflows. A scenario is a user story that is built from this set of events, commands, and views.

Now what I have is a list of very specific functional requirements that when pieced together form the basis of the entire system. Each of these individual workflows can be assigned to a specific team and that is the workflow they own.

From here, a more developer-specific specification may be created in the form of a more traditional user story. What is important however, is that this event model is treated as the source of truth that the ENTIRE ORGANISATION can understand.

The development teams may have epics in Jira or cards on a Trello board. It's largely irrelevant. The importance is the common language the entire system shares and can be used to rationalize different scenarios.

Additional Notes

There are a couple of additional bits of information that I just wanted to tack on at the end to answer some questions I know I had when I first encountered this model.

Implementation is irrelevant

If there is one I would take away from this, it is that the implementation is irrelevant. Whether that's database providers, to-list implementations, programming languages. Don't worry about any of it.

The end goal should be for somebody non-technical and unfamiliar with the business to be able to understand what happens within the organisation very quickly.

Imagine starting work at a new company. In your first day, you understand the entire system at a high level and begin to ask questions of both domain experts and developers in a language everybody understands. It wouldn't matter if you were working in a technical or non-technical role.!

SLA's can be important

Whilst the implementation is irrelevant it can be useful to note on the diagram any time-sensitive operations.

You can see I've marked very explicitly there is a business-specific rule that a stock check must complete in 10 seconds. This is to provide feedback to a user in real-time when they are using the application.

Remember the detail of 'real-time' information isn't important (SignalR, websockets, emails, etc), it is just that there is some form of service level agreement that the system needs to adhere to.

Wireframing

The wireframes on all of my screenshots are icons taken from Miro's built-in icon sets. My intention with this document is to show the backend architecture of a system using event modeling. I didn't want to get too bogged down in front-end appearance. At least at this stage.

In a normal working session, these wireframes would be drawn up to look like how you'd actually want the UI to look. If the UI was going to have three inputs, a dropdown, and a button go ahead and create a wireframe in Miro that looks like that.

Wrapping Up

I hope you've found this step-by-step useful and that it has given you a good introduction to the concept of event modeling.

I know it's something I'll be using in future architecture discussions as another tool to bridge the gap between business domain and technical details.

A huge thanks to Adam Dymitruk for sharing so much information about this process. There is an abundance of YouTube videos out there containing real-world scenarios that Adam works through with businesses.

Resources

Miro Board used in this example

https://eventmodeling.org/posts/what-is-event-modeling/

https://eventmodeling.org/posts/event-modeling-cheatsheet/

Event Modeling with Adam Dymitruk at the DDD Greece Meetup

A redefinition of serverless applications

James Eastham — Mon, 12 Jul 2021 19:15:35 +0000

"Serverless is a way to describe the services, practices, and strategies that enable you to build more agile applications so you can innovate and respond to change faster. With serverless computing, infrastructure management tasks like capacity provisioning and patching are handled by AWS, so you can focus on only writing code that serves your customers."

Definition of serverless, taken from AWS

For a long time, I had quite a close-minded view of Serverless. I made heavy use of AWS Lambda and DynamoDB and stitched it all together using an API Gateway. Development productivity was through the roof, life was great.

Until it wasn't.

I was working on a new project which had an extremely variable load (it could go for weeks without being used) but still needed really low latency when it was accessed.

Lambda is great and with provisioned concurrency enabled it was ok from a latency perspective, but the business wanted more. I was out of ideas.

My close-minded view of Serverless kept me banging my head against a wall of cold starts and application tracing to try and eek out as much performance as possible. It was a frustrating time. I knew Lambda was fantastic but couldn't quite meet the requirements of the customer.my def

Initial simplified architecture

A change in approach

That changed when I listed to an AWS podcast episode, specifically episode #448 talking about AWS Copilot. It struck me for two reasons:

I've always been a big fan of ECS, but the cluster configuration, networking and general management was always a blocker. I'll openly admit networking and server management is a weak part of my skillset, and I've never learnt. Deploying from a CLI to an AWS best practice environment removes that blocker completely.
There is more to Serverless than AWS Lambda.

And it's the second point that really struck me, there is more than one way to deploy an application in a serverless environment. I'm looking at you Fargate, and you App Runner.

Taking a line of text directly from the Copilot documentation - Request-Driven Web Service An AWS App Runner service that auto scales your instances based on incoming traffic and scales down to a baseline instance when there's no traffic. This option is more cost-effective for HTTP services with sudden bursts in request volumes or low request volumes.

Sudden bursts in request volumes or low request volumes - Doesn't that just sound like exactly what I am looking for?

So what does that give me? It provides a way for me to easily deploy an application that is 'always-on' from an easy-to-use CLI, without the need to worry too much about the underlying infrastructure.

This is when my definition of Serverless changed, and when the opening AWS quote made a lot more sense. Now I'd define Serverless as

"Any managed service that abstracts away operational complexity and allows developers and architects to focus on business value"

From AWS Lambda to Azure Functions to Heroku. All of these services provide a platform that removes a barrier for developers and allows them to just get their code out into the wild.

At a higher scale, there may be an argument for more fine-grained control. But for early startups and small companies, I cannot think of a better and more streamlined way of getting your product out there.

A change in architecture

Whilst there isn't anything different at first glance, there is one really important distinction.

That distinction is AWS App Runner replacing the Lambda function that is handling client requests.

For people unfamilar with AWS App Runner, it's a fully managed way of running containers in AWS without the need for managing underlying servers. You simply configure the required amount of CPU and memory and off you go.

The rest of the architecture is identical. Any asynchronous event-driven tasks are still handled by Lambda. This feels like the use case for which Lambda was originally intended. A set of decoupled event handlers that sit doing nothing (and costing little money) until an event happens they are interested in that they react to accordingly.

What this means for the system, is that end users get a low latency API response no matter when they access the app. An App Runner task is 'always on' in the same way that running a server would be.

The trade-off here is an increase in cost, in that App Runner is charged per hour. The cost differs slightly when your application is actually processing requests vs sitting and waiting for a request to arrive. For a REST API, that is 24 hours a day 365 days a year. Slightly different than the Lambda model.
And what it comes down to is the age-old response of 'it depends'. Everything depends on the use case.

Lambda is a completely viable way to run an entire application, as long as a higher latency on the initial startup is ok. For high-volume API's, this is probably not an issue as the functions will always be warm.

However, for my specific use case of a low usage low latency application, the cost trade-off is something we are willing to accept to ensure the end-users have the best possible experience.

The customer always comes first.

For future applications, especially applications built in an event-driven fashion, this is becoming my de-facto architecture. Fargate / AWS App Runner for the client-facing applications, Lambda for the backend services that are less latency driven and more event-driven.

In Practice

Now for a quick example of just how easy it is to get started with AWS Copilot and AppRunner. For that, I'm going to use the order management service in my node-restaurant repository.

Originally, this application was built entirely from lambda functions. The REST API now runs as an express.js application, with any background event handlers running in Lambda. I already had a Dockerfile that I used for some local testing, so I can wire copilot up using that as well. So to get started with copilot, I simply run.


copilot init

The CLI gives a really great step by step walkthrogh, for reference I selected:

Request Driven Web Service
Name the application (order-api) Important note, AppRunner has a max length on the name field which is the application name plus the service name
Select the Dockerfile (helpfully, copilot defaults as it's the only one I have)
Yes to the test environment

After a minute or two you should start to see the output from the Docker build command and then the beginning of the deployment. A note here, the first time you push out to AppRunner it does take quite a while to provision the infrastructure. Go grab a coffee or something and come back later.


✔ Proposing infrastructure changes for stack node-restaurant-test-order-api
- Creating the infrastructure for stack node-restaurant-test-order-api            [create complete]  [317.2s]
  - An IAM Role for App Runner to use on your behalf to pull your image from ECR  [create complete]  [17.9s]
  - An Addons CloudFormation Stack for your additional AWS resources              [create complete]  [28.7s]
  - An IAM role to control permissions for the containers in your service         [create complete]  [17.9s]
  - An App Runner service to run and manage your containers                       [create complete]  [285.9s]

Once complete, head off to the App Runner UI, and voila the API is ready to serve requests.

To come back around to my earlier point, everything always depends! There are benefits and trade-offs to every service, both AWS Lambda and App Runner are suitable for hosting an application. It just depends on the customer use case.

The Importance of Resetting to Zero

James Eastham — Mon, 16 Mar 2020 19:55:51 +0000

I'm sure everybody reading this post has experienced this at some point. You close down your computer on a Friday, excited for the weekend. You then proceed to spend the entire weekend thinking about the week you've just had and pre-empting all of the things that you want to get done the following week.

Before you know it Monday has come around again and you haven't reaped the benefits of having time away from your desk.

I spend a lot of my time mulling over these kinds of situations, as I believe work/life balance is one of the most fundamental problems with society today. We are all expected to be always on, and spend our lives never truly disconnecting from the working world.

Nothing you're about to read in this post is revolutionary, I'm instead regurgitating common tools and tricks I use, without fail, every single week to ensure my time away from the office is well spent.

Reset to Zero

I'm sure I'm not the person to coin the phrase reset to zero, but I certainly find it's the most accurate way to describe the system I employ.

Every week, I ensure that my working life is reset to a state of tranquility. I use these same methods in both my personal and professional life, but I'm confident nobody here wants to read about how I reset my house to zero (FYI, there's house-work involved).

What is involved

I use it as a way to make sure that there are no loose ends, no un-sent emails, and no un-committed changes.

My email inboxes are down to zero, my to-do list is updated and my next week is planned.

All my time is logged and my clients are aware of my plans for the next week so that I can be sure they will be available if I need to ask questions of them.

It can take me up to 2 hours to go through everything I need to, which may seem like two hours of wasted time. But the spare mental capacity managing your workload in this way provides, massively offsets the lost time. At least in my book anyway.

I can honestly say since fully committing to this practice every week my mental stress has dropped massively. No matter what the situation, being able to come back to the feeling of calm and control cannot be understated.

Especially with the dynamic nature of the industry, we all choose to work in, the power of a clear mind is invaluable.

Getting started

If your interest has been piqued, I'm glad to hear it. If not, well why don't you keep reading anyway just to see what you might find out?

It's a reasonably straight forward process I follow:

1. Email Inboxes

I view my emails as my community to-do list. The world has access to it, and almost everything that comes in gives me a task to do.

So my first task is always getting an empty inbox.

I strictly follow Get Things Done principles when it comes to my email inbox.

Anything I need to work on is moved to @action
Anything I am waiting on somebody else for is moved to @waiting
Anything else is deleted (with a copy stored in CRM for anything I feel could be useful in the future)

I'm pretty brutal about the above three rules, especially when it comes to deletion. I've found, after doing this consistently for 18 months, there is almost never a case where it is worth keeping an email cluttering up your mailbox.

These GTD principles are followed on a day by day basis. When it comes to my weekly review, I process all tasks in the @action, @waiting or Inbox folders out into my second brain.

Which leads me quite nicely on to

2. Project/Development Reviews

A nice short section here, but I run through each and every 'project' I'm working on and check to see what the current state is.

That would include outstanding commits from my laptop, work still to be done on the project, new feature requests or outstanding issues.

Basically anything at all that needs my direct input.

Sometimes this part of the review can take the longest, sometimes it's over and done within a matter of minutes.

Inevitably there are things that get forgotten here, but knowing that 98% of the things in my head are stored somewhere that isn't my sieve-like brain is a huge plus.

3. Todo lists (my second brain)

There are a billion and one articles around the internet on the correct way to manage a to-do list. A lot of which are filled with fantastic tips and tricks.

However, I think the best way to manage your to-do list is the way that works best for you.

Maybe you prefer one big long list of all the things you need to do. Maybe you prefer big overarching tasks with sub-tasks within them. The practical side of it is largely irrelevant.

What I always try to achieve with my to-do list, is to remove every single potential thought/thing to remember from my brain and instead ask a piece of technology to remember for me.

Again, I stick with GTD methods here. Anything that pops into my head during the week, gets added to an Inbox section of my to-do list. Similarly, when I process my emails anything that is important goes into the Inbox.

Step two of my weekly review is going through this inbox and organizing it into relevant places. This normally entails:

New client requests
Support issues (inc. time-sensitive ones)
Emails I need to send
Documents I need to read/review
Interesting articles to read
Phone calls to make

The list goes on.

These inbox items are organized into folders that follow and assigned times/dates based on the sensitivity of the thing:

Professional - Day job
Professional - Freelance
Personal - Out and about
Personal - Home
Personal - Computer

Once done, I almost instantly feel like there is a weight off my shoulders.

And that's my professional life reset to zero. I apply these same principles to my personal life to ensure my entire world is in as calm a state as possible.

The Benefits

I can't rave enough about the benefits of spending the time doing this kind of thing.

Yes, it's time-consuming.

Yes, things will still get forgotten and you'll end up with an unexpected client call.

But once you've spent your first weekend not thinking about your working life because you are absolutely confident everything is in perfect order, you'll be thinking why you didn't start doing it earlier.

I'm intrigued to hear other people's best practices when it comes to managing your task list. Let me know in the comments...

Front End for the .NET Developer with Blazor Web Assembly

James Eastham — Sun, 01 Mar 2020 18:10:08 +0000

Throughout my entire development career, I've always found web to be the best way of deploying an interface to any software I've written.

Desktop never really appealed to me, maybe that comes from growing up almost entirely in an age where everything was web-based.

However, coming from a .NET background, there are some downsides to this web-first approach.

ASP Web Forms were ok, and MVC built upon that a little bit. But nothing ever really came close to the magic of the big Javascript frameworks.

That lead me down a rabbit hole I never truly got to grips with, the magical world of Angular and React.

I've toyed with both, completed tutorials and written production apps. Still, neither of them really clicked fully (I did massively prefer React, but that's a personal preference thing).

Typescript improved upon this pain slightly, bringing strong typing and a more C#-esque way of development.

And then, along came Blazor...

Blazor

I'm not going to dive into too much detail around Blazor, there is plenty of other articles around the web regarding that (the official docs are a great place to start).

To quickly summarise though, Blazor is Microsoft's challenge to the big JS-based front end frameworks. It allows rich and interactive front end apps to be written entirely in C#. Not a line of Javascript insight.

And with that, let's dive into some code.

Getting Started

To get started with Blazor, I'm going to add a front end to the team-service I've been building throughout this series of articles. It's a learning process for me as well, so stay with me!

Running the below commands is all it takes to get started with a new Blazor app.

dotnet new -i Microsoft.AspNetCore.Blazor.Templates::3.2.0-preview1.20073.1 -o LeagueManager
dotnet new blazorwasm -o LeagueManager

The first install's the latest Blazor Web Assembly project template (at the time of writing, it's 3.2.0 Preview 1). The second command creates a new project.

Following the two commands with the below, gets the sample app up and running.

cd .\LeagueManager\
dotnet run

Out of the box, Blazor applications use Bootstrap and are created with some great examples of the key functionality (namely two-way model binding and making external requests).

First things first, let's add our own color scheme and font. I'll also remove a lot of the standard Blazor code leaving a much more basic project structure.

I'm also going to apply one of the principles I learned from React, which is to keep stateful components to an absolute minimum and make the majority of the application dumb.

For that, I'm going to add two additional folders on top of the pre-configured 'Pages' folder with two new folders:

Components - Dumb, layout components
Services - Stateful components

Initially, I considered disposing of the Pages folder as well. But keeping actual pages (with routes) in one place seemed more logical.

For this initial piece of front end of development, I need to be able to:

View a list of teams
Create a new team
View details about a specific team
Add players to a team

In my head, that gives me two pages.

A list of all teams and the ability to create a new team
A page to view a specific team containing a list of the team's players and corresponding data entry form for adding new players

Handling State

Before I get into much detail about the page structure, I first wanted to see how HTTP data access works in Blazor.

Turns out, the answer is extremely simple.

The answer is a huge +1 already for using Blazor as a front end framework. The code written to manage to retrieve data from an external HTTP service is almost identical to code that would run in any kind of .NET application.

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using LeagueManager.Models;
using Microsoft.AspNetCore.Components;
using Microsoft.Extensions.Logging;

namespace LeagueManager.Services
{
    public class TeamState
    {
        private string LastSearch = "";

        public IReadOnlyList<Team> TeamSearchResults { get; private set; }
        public bool SearchInProgress { get; private set; }
        public event Action OnChange;

        private readonly HttpClient _httpClient;
        private readonly ILogger<TeamState> _logger;

        public TeamState(
            HttpClient httpClient,
            ILogger<TeamState> logger)
        {
            this._httpClient = httpClient;
            this._logger = logger;
        }

        public async Task DeletePlayer(Player player)
        {
            try
            {
                this._logger.LogInformation($"{player.TeamId} - {player.Name} - {player.Position}");

                var httpContent = new StringContent(JsonSerializer.Serialize(player), Encoding.UTF8, "application/json");

                var postResult = await this._httpClient.DeleteAsync($"http://localhost:8080/team/{player.TeamId}/players");

                this._logger.LogInformation(postResult.StatusCode.ToString());

                if (postResult.IsSuccessStatusCode)
                {
                    NotifyStateChanged();
                }
                else
                {
                    throw new Exception(await postResult.Content.ReadAsStringAsync());
                }
            }
            catch (Exception ex)
            {
                this._logger.LogError(ex.Message);
                this._logger.LogError("Failure adding player");
            }
        }
        public async Task AddPlayer(Player player)
        {
            try
            {
                this._logger.LogInformation($"{player.TeamId} - {player.Name} - {player.Position}");

                var httpContent = new StringContent(JsonSerializer.Serialize(player), Encoding.UTF8, "application/json");

                var postResult = await this._httpClient.PostAsync($"http://localhost:8080/team/{player.TeamId}/players", httpContent);

                this._logger.LogInformation(postResult.StatusCode.ToString());

                if (postResult.IsSuccessStatusCode)
                {
                    NotifyStateChanged();
                }
                else
                {
                    throw new Exception(await postResult.Content.ReadAsStringAsync());
                }
            }
            catch (Exception ex)
            {
                this._logger.LogError(ex.Message);
                this._logger.LogError("Failure adding player");
            }
        }
        public async Task<Team> GetSpecific(string teamId)
        {
            this._logger.LogInformation("Running HTTP search");

            var team = await this._httpClient.GetJsonAsync<TeamSearchResponse>($"http://localhost:8080/team/{teamId}");

            return team.Team;
        }
        public async Task ReRunSearch()
        {
            await this.Search(LastSearch);
        }
        public async Task Search(string searchTerm)
        {
            try
            {
                this.LastSearch = searchTerm;

                this._logger.LogWarning("Running search");
                this.SearchInProgress = true;

                NotifyStateChanged();

                var searchResult = await this._httpClient.GetJsonAsync<TeamSearchResponse>($"http://localhost:8080/team?search={searchTerm}");

                if (string.IsNullOrEmpty(searchResult.Err))
                {
                    this.TeamSearchResults = searchResult.Teams;
                }

                this.SearchInProgress = false;

                NotifyStateChanged();
            }
            catch (Exception ex)
            {
                this._logger.LogError(ex, ex.Message);
                this._logger.LogError(ex, "Failure running search");
            }
        }
        public async Task CreateTeam(Team team)
        {
            try
            {
                this._logger.LogInformation($"{team.Name}");

                var httpContent = new StringContent(JsonSerializer.Serialize(team), Encoding.UTF8, "application/json");

                var postResult = await this._httpClient.PostAsync($"http://localhost:8080/team", httpContent);

                this._logger.LogInformation(postResult.StatusCode.ToString());

                if (postResult.IsSuccessStatusCode)
                {
                    NotifyStateChanged();
                }
                else
                {
                    throw new Exception(await postResult.Content.ReadAsStringAsync());
                }
            }
            catch (Exception ex)
            {
                this._logger.LogError(ex.Message);
                this._logger.LogError("Failure adding team");
            }
        }

        private void NotifyStateChanged() => OnChange?.Invoke();
    }
}

A reasonably straightforward class that uses Dependency Injection to add a HttpClient and an ILogger. From there, it is mostly just a set of different methods handling the various different CRUD operations.

** Note the terrible hardcoded URL, this is a work in progress :) **

There are a couple of front-end/Blazor specific parts that I do just want to point out, however.

public IReadOnlyList<Team> TeamSearchResults { get; private set; }
public bool SearchInProgress { get; private set; }
public event Action OnChange;

These three properties are all relevant to HTTP in Blazor.

The Blazor application runs completely in a web browser. Therefore this TeamState object is specific to the client accessing the site.

Therefore, whenever search runs we can hold a copy of the returned data in a property for easy retrieval if the search needs to happen again.

SearchInProcess holds a value indicating that the search method is running. Imagine a front end in which a loading bar appears during a search, that could be bound to this property.

The OnChange property is probably the most important of the three. It's linked directly to this line of code here:

private void NotifyStateChanged() => OnChange?.Invoke();

So, the OnChange property can be subscribed to by an external method. NotifyStateChanged then invokes that external method.

Let's dive into a real example. Here is the code for the Team List page.

@page "/teams"

@using LeagueManager.Services
@using LeagueManager.Components.Teams

@inject TeamState state

<div id="team-search">
    <div id="new-team">
        <CreateTeam OnSave="this.CreateTeam" />
    </div>
    <div id="search-area">
        <Search OnSearch="state.Search" />
    </div>
    <div id="search-results">
        <SearchResults Teams="state.TeamSearchResults" />
    </div>
</div>

@code { 

    protected override async Task OnInitializedAsync()
    {
        state.OnChange += StateHasChanged;

        await state.Search(string.Empty);
    }

    public async Task CreateTeam(Team team)
    {
        await this.state.CreateTeam(team);

        await state.ReRunSearch();
    }
}

An instance of the TeamState object is injected into the page, and on PageLoad (OnInitializedAsync is Blazor's PageLoad event) the state Blazor page StateHasChanged event is subscribed to the OnChange event of the state injected state class.

So, when a search runs within the TeamState object the OnChange event is triggered. In this instance, the StateHasChanged event of the Blazor page will execute. Taking wording straight from the Microsoft docs:

"StateHasChanged notifies the component that its state has changed. When applicable, calling StateHasChanged causes the component to be rerendered."

Binding any page to the OnChange event of the state will, therefore, cause the page to be re-rendered whenever our state components notify that something has changed. Cool!

Model Binding

Now that we can retrieve data from the server and give that to the front end, it'd be fantastic to actually get it to display on the page.

Displaying data

Sticking with the best front end practices I've taken from JS, my Teams.razor page handles all of the state management. It then passes the data down to components to manage the display.

A good example of this is the SearchResults component.

<div class="col">
    <div class="row py-1">
        @if (Teams == null || Teams.Count == 0)
        {
            <p>No results found.</p>
        }
        else
        {
            <table class="table">
                <thead>
                    <tr>
                        <th scope="col">#</th>
                        <th scope="col">Name</th>
                    </tr>
                </thead>
                <tbody>
                    @foreach (Team team in Teams)
                    {
                        <tr @key="team.Id">
                            <th scope="row">
                                <a href="/teams/@team.Id">@team.Id</a>
                            </th>
                            <td>@team.Name</td>
                        </tr>
                    }
                </tbody>
            </table>
        }
    </div>
</div>

@code
{
    [Parameter]
    public IReadOnlyList<Team> Teams { get; set; }
}

The above snippet raises one of the key parts of Blazor functionality. That being, the Parameter attribute.

The parameter attribute indicates that a value can be passed into the component by way of an HTML element.

In this case, there is a parameter that holds a list of Team objects.

This component can certainly be classified as dumb.

It takes a list of objects and either shows 'no results found', or creates an HTML table and loops through each Team object to create the table rows.

C#. In the browser. It's a magical time to be a .NET developer.

Creating a new record

The final piece of this front end puzzle is creating new records.

My absolute favourite feature of both Angular and React is the ability to be able to initialize a new instance of an object and bind that straight to an input in the HTML.

Luckily, Blazor has taken notes from the JS big boys and offers a similar kind of function.

For that, let's have a look at the CreatePlayer component.

<EditForm Model=@newPlayer>
    <div class="col">
        <div class="input-group mb-3">
            <input type="text" class="form-control" placeholder="Name" aria-label="Search Term" @bind="newPlayer.Name">
        </div>
        <div class="input-group mb-3">
            <InputSelect @bind-Value=newPlayer.Position class="custom-select">
                <option value="GK">Goalkeeper</option>
                <option value="DEF">Defender</option>
                <option value="MID">Midfielder</option>
                <option value="ST">Striker</option>
            </InputSelect>
        </div>
        <div class="row py-1">
            <div class="ml-auto">
                <button @onclick="() => OnSave.InvokeAsync(newPlayer)" type="button" class="btn btn-danger px-5">
                    Add +
                </button>
            </div>
        </div>
    </div>
</EditForm>
@code
{
    [Parameter]
    public EventCallback<Player> OnSave { get; set; }

    [Parameter]
    public string TeamId { get; set; }

    private Player newPlayer = new Player();

    protected override Task OnInitializedAsync()
    {
        newPlayer.TeamId = this.TeamId;
        return base.OnInitializedAsync();
    }
}

When the page is loaded, a new Player object is created. OnInitialization, the TeamId of the newly created player object is assigned from an input value.

A TeamId is a requirement for a player object, so it probably makes sense to implement some kind of null check on the TeamId property just in case. But that's a job for another day.

From there, an EditForm component is added to the HTML. An EditForm parses out to a standard HTML form. However, it enables model binding between the DOM and the C# object.

Using the @bind element, the HTML becomes reasonably straightforward. An input is bound to the player name property and a select dropdown is bound to the position property.

When the form is submitted, the OnSave event callback is invoked.

What the hell is an EventCallback?

For that to make a little more sense, let's take a quick look at a component that consumes this CreatePlayer component.

TeamMetadata.razor

@if (TeamData == null)
{
    <p>Loading...</p>
}
else
{
    <h1>@TeamData.Name</h1>
    <h2>Current Players</h2>
    <CreatePlayer OnSave="OnAddPlayer" TeamId="@TeamId" />
    <div>
        <PlayerList Players="@TeamData.Players" OnDelete="OnDeletePlayer" />
    </div>
}

@code {
    [Parameter]
    public Team TeamData { get; set; }

    [Parameter]
    public string TeamId { get; set; }

    [Parameter]
    public EventCallback<Player> OnAddPlayer { get; set; }

    [Parameter]
    public EventCallback<Player> OnDeletePlayer { get; set; }
}

ViewTeam.razor

@page "/teams/{TeamId}"

@using Microsoft.Extensions.Logging
@using LeagueManager.Components.Teams

@inject TeamState state

<TeamMetadata TeamData="@teamData" TeamId="@TeamId" OnAddPlayer="state.AddPlayer" OnDeletePlayer="state.DeletePlayer" />


@code {
    [Parameter]
    public string TeamId { get; set; }

    private Team teamData { get; set; }

    protected override async Task OnInitializedAsync()
    {
        state.OnChange += StateHasChanged;

        teamData = await state.GetSpecific(this.TeamId).ConfigureAwait(false);
    }

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        teamData = await state.GetSpecific(this.TeamId).ConfigureAwait(false);
    }
}

The two code snippets above are for the View Team page, and the corresponding TeamMetadata component within it.

Sticking with the practice of having as little components managing state as possible, the ViewTeam page holds all the logic for loading the players and the creation of a new player.

The state.AddPlayer method is passed down into the OnAddPlayer parameter of the TeamMetadata component, and from there into the OnSave parameter of the CreatePlayer component.

So when the save button is clicked in the CreatePlayer component that event bubbles all the way up to state.AddPlayer method. The newly created and data-bound Player object goes along for the ride and is sent off to our backend server for creation.

I will say it again...

C#. In the browser. It's a magical time to be a .NET developer.

In Summary

Sometimes I can waffle a little bit with these summary sections. This time, not so much.

Blazor is one of the best web technologies I have ever worked with. I'm probably biased, being a .NET developer. But I no longer need to stumble my way through the world of Javascript.

And that my friends is a magical place to be.

Refactoring with Clean Architecture - The magic of well-designed software

James Eastham — Sun, 16 Feb 2020 21:31:34 +0000

This week has been a pretty crazy one, with an AWS exam and two weddings in three days (one of which I was the best man) there hasn't been much mental capacity for Golang.

So this post takes on a slightly shorter and more high-level discussion around software architecture and the huge benefits that come from doing it 'right'.

Don't worry, there are still some lines of code.

Doing it right

Much like a lot of things in life, I'm not the kind of person who believes his opinion is the only one and everyone should do the same way.

Part of the fun in life is understanding other people's points of view, and putting together the best of different viewpoints.

That's not to say I don't have opinions on software design though. Far from it.

I'm a huge advocate of Uncle Bob Martin 'Clean Architecture' style of coding. Loosely related to Jeffrey Palermo's Onion Architecture.

The basic rule being, that each layer of a software system should have no dependency on a layer outside of it.

The core of the onion would be pure business entities. Coupled with Domain Driven Design, this gives you a central code base that is extremely well matched to the domain itself.

No mention of SqlConnection's or HTTP calls. Pure, well-structured code.

Outside of that, there are domain services or interactors. These are objects that have the sole responsibility of managing your domain objects. Business logic is likely to sit in this layer.

Taking an example from the team-service repository in my football league manager app git repo.

// CreateTeamRequest holds a reference to new team data.
type CreateTeamRequest struct {
    Name string
}

// CreateTeamResponse holds a reference to new team data.
type CreateTeamResponse struct {
    ID     string
    Name   string
    Errors []string
}

// CreateTeam creates a new team in the database.
func (interactor *TeamInteractor) CreateTeam(team *CreateTeamRequest) (*CreateTeamResponse, error) {
    if len(team.Name) == 0 {
        interactor.Logger.Log("Team name cannot be empty")
        var response = &CreateTeamResponse{
            ID:     "",
            Name:   team.Name,
            Errors: make([]string, 1),
        }

        response.Errors[0] = "Team name cannot be empty"

        return response, errors.New("Team name cannot be empty")
    }

    newTeam := &domain.Team{
        Name: team.Name,
    }

    createdTeamID := interactor.TeamRepository.Store(newTeam)

    interactor.EventHandler.Publish("leaguemanager-info-newteamcreated", TeamCreatedEvent{
        TeamID:   createdTeamID,
        TeamName: team.Name,
    })

    return &CreateTeamResponse{
        ID:   createdTeamID,
        Name: newTeam.Name,
    }, nil
}

The CreateTeam method of the team interactor holds all the logic for creating a new team in the database. It takes a CreateTeamRequest as it's input, and returns a CreateTeamResponse.

You'll notice the code references interactor.EventHandler and interactor.TeamRepository. These are interfaces that will, at some stage, be implemented with actual event handling and data storage code.

As far as the business logic is concerned though, nothing changes.

Going back to the title of the article, refactoring is made so much easier following this model.

Any changes to the data storage provider have no effect AT ALL on the business logic itself. Conversely, business logic can be changed freely with ease.

If I wanted to change exactly when the data was persisted to the repository, I could move the call to TeamRepository.Store and not worry about the details about how it actually happens.

One of the best takeaways from Bob Martin's book on Clean Architecture is regarding the detail. The details (Database provider, event bus etc.) should be left to as late in the development process as possible.

Often, people want to jump in with the database, then spend 2 months getting bogged down with schema.

The alternative, write your code first abstracting the storage layer. Then add your database once you know more about the data you will be stored in it.

Event handling - An example

Currently, the code for the event handler of the team service uses Amazon SNS and looks something like the below.

package infrastructure

import (
    "errors"
    "fmt"
    "strings"
    "team-service/domain"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/sns"
)

// ErrTopicNotFound is returned when the requested topic is not found.
var ErrTopicNotFound = errors.New("Specified topic not found")

// AmazonSnsEventBus is an event bus implementation using Amaazon SQS.
type AmazonSnsEventBus struct {
    svc       *sns.SNS
    availableTopics []string
}

// NewAmazonSnsEventBus creates a instance of the AmazonSnsEventBus.
func NewAmazonSnsEventBus() *AmazonSnsEventBus {
    // Initialize a session that the SDK will use to load
    // credentials from the shared credentials file ~/.aws/credentials
    // and region from the shared configuration file ~/.aws/config.
    sess := session.Must(session.NewSession(&aws.Config{
        Region:      aws.String("eu-west-1"),
        Credentials: credentials.NewSharedCredentials("", "league-manager-sqs"),
    }))

    svc := sns.New(sess)

    availableTopics, _ := svc.ListTopics(nil)

    availableTopicArns := make([]string, len(availableTopics.Topics))

    for i, t := range availableTopics.Topics {
        availableTopicArns[i] = *t.TopicArn
    }

    return &AmazonSnsEventBus{
        svc:       svc,
        availableTopics: availableTopicArns,
    }
}

// Publish sends a new message to the event bus.
func (ev AmazonSnsEventBus) Publish(publishTo string, evt domain.Event) error {
    requiredTopicArn := ""

    for _, t := range ev.availableTopics {
        if strings.Contains(t, publishTo) {
            requiredTopicArn = t
        }
    }

    if len(requiredTopicArn) > 0 {

        result, err := ev.svc.Publish(&sns.PublishInput{
            Message: aws.String(string(evt.AsEvent())),
            TopicArn:    aws.String(requiredTopicArn),
        })

        if err != nil {
            fmt.Println("Error", err)
        }

        fmt.Println("Event published: ", *result.MessageId)

        return err
    }

    return ErrTopicNotFound
}

Since learning more about AWS services, I've actually discovered that Amazon Kinesis is a better tool than SNS for my exact use case.

Instead of needing to pick my way through the entire code base looking for references to Amazon SNS. I just need to write a new implementation of the event handler interface that uses Kinesis.

On application startup, I just decide which event handler to use.

// teamInteractor.EventHandler = new(infrastructure.MockEventBus)
// teamInteractor.EventHandler = infrastructure.NewAmazonSnsEventBus()
teamInteractor.EventHandler = infrastructure.NewAmazonKinesisEventBus()

No changes to business logic. No changes to domain objects.

One single line of code changed, and all that's changed is the infrastructure.

The chances of a bug being introduced are almost non-existent (granted there may be bugs in the new code that gets written).

So whilst I'm not saying this is the only way to build well-designed software, and it certainly does have flaws. I hope it has shown that putting time into the design pays out massive dividends in the future.

How do you monitor the usage of your API endpoints?

James Eastham — Wed, 12 Feb 2020 09:56:43 +0000

EDIT: so I'm now thinking of releasing a cloud app that can be used to monitor API usage. Any interested beta testers drop me a message below :-)

Day to day I develop a reasonably large web API used by quite a few different clients. It was put together almost 2 years ago now when I had very little consideration of monitoring or auditing.

My current focus is on the usage of certain API endpoints. What is your practice for auditing the usage of a certain endpoint?

For context, I'ts a .NET API and the API is distributed across multiple non-related clients systems. Ideally I'd like to push the results to ElasticSearch.

I feel like a custom piece of middleware is the best option, but am a little concerned about performance.

Thoughts?

CI/CD in GoLang with Azure Dev Ops and AWS Elastic Beanstalk

James Eastham — Sun, 09 Feb 2020 18:32:46 +0000

This post follows a series of articles I've been writing about designing a distributed system. I'd highly recommend at least ready part 1 before this one just to get a little bit of context.

Now that the team-service application is as feature-rich as it needs to be for the moment, it feels like a great time to get it running somewhere more useful to the world. http://localhost:8000 is fantastic for me, not so great for anybody else who wants to use the app.

With the tooling we have available as developers today, I see no reason at all that software should ever be manually deployed.

For that reason, the team-service application is going to be deployed using CI/CD pipelines that require 0 user interaction. All releases should be triggered using a developer-friendly interaction (git commit, pull request etc).

There are a couple of different tools I'm going to be using to achieve this:

Azure Dev Ops Services - Azure Dev Ops is by far my favourite build and release pipeline provider. It can also include built-in git repos for those private projects you want to keep away from prying eyes.
AWS Elastic Beanstalk - AWS Elastic Beanstalk is a fantastic offering for quickly getting source code running in a public domain.

Some of you may be questioning why I'm using a Microsoft provided CI/CD service with Amazon provided infrastructure.

My biggest reason is the simplicity of using build pipelines in Azure Dev Ops. I've experimented with AWS Code Build and don't find the interface anywhere near as intuitive.

Deploying to AWS from Azure Dev Ops is extremely easy with the install of an extension from the marketplace.

There is no clear cut reason why I prefer AWS over Azure for app hosting. They are both fantastic cloud providers.

I work with AWS a lot more in my day to day work, and I find their costs for playing around to be a lot more reasonable. Hence the reasoning for pushing to AWS.

Build Pipelines in Azure Dev Ops

Build pipelines in Azure Dev Ops use yaml. You can either manually type out the yaml files, are use the editor within the UI (which is fantastic by the way).

To get started though, I need to link a new project to my GitHub repo.

When creating the new project, it's important to create it as public. You can only link to a public GitHub repo from a public Azure Dev Ops project.

The Dev Ops UI makes it extremely easy to link up a GitHub project. On creation of a new pipeline, just step through the wizard to create a link to the GitHub repo.

For the moment, I'm going to create a new pipeline and save the standard layout. It'll look something like this.

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml

trigger:
- master

pool:
  vmImage: 'ubuntu-latest'

steps:
- script: echo Hello, world!
  displayName: 'Run a one-line script'

- script: |
    echo Add other tasks to build, test, and deploy your project.
    echo See https://aka.ms/yaml
  displayName: 'Run a multi-line script'

This will commit a new file named azure-pipelines.yml to my git repo. Before I go any further, I'm going to do a little bit of housekeeping and move that file into the src folder for the team-service.

Manually starting a build gives the following output.

Fantastic, we have a working build pipeline.

Required deployment steps

Before adding any steps to the pipeline, it's important to think about exactly what the steps would be to deploy the code. In this instance:

Run unit tests
Package application in a runnable format (Zip file containing Dockerfile)
Deploy to Elastic beanstalk environment

Simple, right.

The Build Pipeline

As much as I love writing code, the build pipeline UI really is too good to not use.

You can search for the required component on the right-hand side using the assistant, fill in the variables and add it to the yaml. Once finished, saving the pipeline commits it directly back to the Git repo. Magical!

An important note at this point, I had already installed the AWS Azure Dev Ops Extensions. It's a fantastic set of tools that makes deploying to AWS a piece of cake.

So, back to that pesky YAML file. Here it is in its entirety, you'll find some explanation after the code block.

# 1. Triggers
trigger:
  branches:
    include:
    - master
    - releases/*
  paths:
    include:
    - src/team-service/*

# 2. Jobs
jobs:
- job: run_unit_tests
  displayName: 'Run Unit Test'
  pool:
    vmImage: 'ubuntu-latest'
# 3. Steps
  steps:
  # Run domain level tests
  - task: Go@0
    inputs:
      command: 'test'
      workingDirectory: 'src/team-service/domain'
  # Run use case level tests
  - task: Go@0
    inputs:
      command: 'test'
      workingDirectory: 'src/team-service/usecases'
  # Ensure application can build
  - task: Go@0
    inputs:
      command: 'build'
      workingDirectory: 'src/team-service/'


- job: package_application_files
  displayName: 'Package application files'
# 4. Dependent jobs
  dependsOn: [ run_unit_tests ]
  condition: and(succeeded(), startsWith(variables['Build.SourceBranch'], 'refs/heads/release/'))
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  # Create zip file of team-service
  - task: ArchiveFiles@2
    inputs:
      rootFolderOrFile: 'src/team-service'
      includeRootFolder: false
      archiveType: 'zip'
      archiveFile: '$(Build.ArtifactStagingDirectory)/app.zip'
      replaceExistingArchive: true
  - task: PublishBuildArtifacts@1
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'
      publishLocation: 'Container'
      replaceExistingArchive: true

I've added four numbered points within the YAML for ease of explanation.

1. Triggers

Triggers allow control of when the pipeline should be triggered. In this case, I'm going to run it on any changes to master, or to any changes to a branch that begins with release/.

The pipeline will also only run if the changes are made to any files under the src folder. This stops un-necessary builds when non-relevant changes are made (documentation, other services etc).

2. Jobs

Jobs are a way of organizing a pipeline into logical steps. Each pipeline will have at least one job, and each job can have any number of steps.

In this case, there are two jobs. One to run the unit tests and one to package up and deploy the application files.

3. Steps

Steps make up the meat of the pipeline functionality. They are the individual tasks that will happen, one by one, against your source code. In this case, we:

Run the domain level unit tests
Run the usecase level unit tests
Ensure the entire go application can build
ZIP the application files inc. Dockerfile
Publish the build artifact

No mention of AWS just yet, more on that in just a second.

4. Dependent jobs

One of the most powerful features of the pipelines is controlling which jobs run conditionally.

Here, I'm only running the second job if the source branch begins with release and if the run_unit_tests job completes successfully.

And there we have it, 53 lines of code to test, build and package a Go application. Now for the deployment part:

Deploy from Azure Dev Ops to AWS

Azure Dev Ops splits it's pipelines functionality into two seperate distinct parts.

Builds The generation of 'artifacts' containing packaged versions of the source code
Release Uses build artifacts and deploys them

In this section, I'll run through the extremely simple setup of a release pipeline to push to AWS. First though, some quick AWS admin.

Create an Elastic Beanstalk Application

For the release to work, we first need an elastic beanstalk application and environment to deploy to.

For that, log in to the AWS management console and head over to the elastic beanstalk section.

From there, create a new application with a descriptive name.

Once within the created application, you will want to provision a new environment. I tend to run with two separate environments for most applications; dev and prod.

For this application here, I'm going to create a new dev environment using Docker as the runtime. For the time being, I also want to create the environment using sample application code.

Following the same steps to create another environment named production, after a few minutes I end up with the following in the Elastic Beanstalk application interface.

One final AWS console step, create a publically accessible Amazon S3 bucket. For that, head off to the S3 interface and create a new bucket. Ensuring the block public access options are disabled.

Azure Dev Ops Release Pipeline

There are a million and one different ways to manage release pipelines. Push direct to production. Push all builds to development but only certain builds to production. The list is endless.

I'm going to start with the following flow:

The developer creates a new branch from a master named release/
Build pipeline triggered from the release branch
Release pipelines push to development, and waits for a specified number of minutes before pushing to production.

This gives the opportunity for a quick test of the development environment before the change gets automatically sent to production.

I also considered having an approval gate to allow a specific user to approve the release, but given I'm the only developer right now that seemed useless.

I'm going to head into the Releases section of the Azure Dev Ops UI and create a new release pipeline. Initially, I want to configure from an empty pipeline.

All release pipelines need to be linked up to a build artifact, for that, I'm going to add a new artifact and link it to the build pipeline created earlier.

I then need 3 distinct steps:

Push to development
Wait for X minutes
Push to production

Luckily, all that is nice and simple.

The two push tasks are almost identical, so here is the detail from the development one:

First, I take the ZIP file generated from the build pipeline and upload that to the S3 bucket created at the start of this section.

For the moment, I standardize the zip file to always be named app.zip, but in the future, I would like to upload a zip file named with the release number.

From there, I create a new Elastic Beanstalk deployment using the zip file uploaded to S3.

Elastic beanstalk is smart enough to know, because I set the platform to be Docker, that it needs to unpack the ZIP file and look for a Dockerfile. Using that Dockerfile, EB can generate an image and run it right away.

Cloud computing... it's a magical place.

There is my complete release pipeline. A push to development, a nice simple wait task and then a push to production.

Summary

There we have it, a complete end to end deployment pipeline from development machine through to a live application running in AWS.

As a test, I've run the following commands from my local machine.

git checkout -b release/1.0.0
git push --set-upstream origin release/1.0.0

Sure enough, my build pipeline runs to completion before starting my release pipeline.

A few minutes later, the application is running in production.

I've said it once, and I'll say it again, cloud computing is truly a magical place.

This is by no means a production-ready guide right now, the main reason being that both development and production are running using the same underlying infrastructure (Dynamo DB and SQS queues).

Application configuration, now there's a conversation for another day.

As always, feedback is greatly appreciated.