On a Sandy Beach: DDD

Showing posts with label DDD. Show all posts

Transforming Primary Care: a Case Study in Evolving from Start-Up to Scale-Up

Mike's Notes

A useful shared experience by Leander Vanderbijl at an InfoQ conference. The original InfoQ video presentation includes the slides. and is well worth watching (52:26).

Resources

References

Reference

Repository

Home > Ajabbi Research > Library > Subscriptions > InfoQ
Home > Handbook >

Last Updated

29/01/2026

Transforming Primary Care: a Case Study in Evolving from Start-Up to Scale-Up

By: Leander Vanderbijl

InfoQ: 22/10/2025

Leander Vanderbijl is an engineer and architect that has worked across the entire stack and has been working at Kry/Livi for the past number of years. He has developed large enterprise applications, migrated cloud platforms, designed data query frameworks, architected integration systems and built lots and lots of APIs. Having worked in large enterprises, small companies and, most recently, in healthcare, he has built the monolith, torn it apart and then rebuilt it again.

Transcript

Leander Vanderbijl: Have you ever built the perfect application? Beautifully crafted your models so that everything fits the real-world objects that you think you're going to have in your system? Only to wake up one morning and your PM comes to you and says, yes, that's great, but what if it just did this a little bit differently? With that one sentence, your entire premise is thrown out the window. All of your assumptions are proven false and your beautiful system is impossible to work with. What about that perfect architecture you've developed? Very clean, you've got onions and layers and all of that fun stuff, and it works perfectly. You don't know when and you don't know why particularly, but over time you suddenly come back to it and this beautiful application has become a spiderweb's nest of impossible dependencies. I've been there. We've had that problem.

In this talk, we're going to talk about how our company, Kry, has evolved through startup and scaleup phases, and particularly how our systems have evolved while we were trying to find our product market fit, and how our systems became that spaghetti spiderweb's nest of dependencies.

Particularly, we'll look at how we're now applying domain-driven principles to gain back control of our architecture, to try to make sense of the mess that we built. Again, not intentionally did we build that mess. We're also going to look at how we're changing our mindset from looking at the product and taking a feature endpoint. Our frontend needs this so I'm going to build one endpoint for that. Instead of doing that, we're starting to think about, what functionality do we need to provide for any client or for any other part of the system? We're going to look at how we're moving from an organic approach to our software evolution where people just do what they need to, when they need to, to a much more deliberate and targeted approach to our evolution where everybody knows where we're going.

Marshall Goldsmith says, what got you here, won't get you there. Which is a great quote as long as you know where there is. Throughout this talk I'd like you to remember my golden rule, my guiding principle, working software is better than the promise of working software. We're not Google or Microsoft. I can't go and tell a team to rewrite the OS every four years. We have to find some other way of making our systems better in situ.

Roadmap

For the structure of this talk I'm going to borrow heavily from Simon Brown's C4 model. We're going to look at this problem at four different levels. We're going to start at the company profile. We'll talk a little bit about what our company does and what its purpose is. Then we'll move on to go a little bit deeper to the container level and look at our product history and our requirements and how those have evolved over time. Then we'll get a bit deeper still and get to that component layer and look at how our architecture and our services have grown and adapted over time. Lastly, we'll look at domain modeling, sort of a code level. We won't look at code but that code level of the C4 model. We'll look at how our domain modeling has changed over time and how it's evolved when we started to realize that our initial attempts at it weren't fitting the bill.

Tech in Hardware

Did you know that in the UK there are 353 million GP patient appointments every year? There are 28,000 full-time GPs. Is anybody good at math? I do that for you. That average is somewhere in the neighborhood of 30 patients a day, or 3 to 4 patients an hour. At Kry, we've found that by applying technological solutions in a process that we call digital offloading that we can increase this throughput from 3 to 4 meetings an hour to somewhere in the neighborhood of 7 or 8 meetings an hour, so nearly double, and still provide the same levels of clinical excellence. We do this through a series of things.

A large part of that is moving the meetings online, and that has proven that we can improve throughput just by doing that alone. A lot of it is really around all the rest of the provision of services that go around meeting a patient. That's things like being able to get data in a timely and efficient manner to the GP before they look at a patient. That's mastering the workflows after the patient has been seen by the GP. All the data input, we can standardize that. We also can vastly improve the workflows for continuing care, things like prescriptions or providing referrals and things like that. With all of that that's how we can really drastically improve the speed and the quality in which our GPs can manage the patients.

Company Profile (Context)

We were started in 2015 in Sweden. As we grew, we started to expand into other parts of Europe. Primarily, our biggest markets are France and the UK. We've also recently gone into Norway as well. Again, our focus is the digital transformation of primary care.

Product History (Containers)

Let's go into how our products have evolved over time. When we started in 2015 it was simple. All we wanted to do was hold meetings digitally online. The requirements were again pretty straightforward. Obviously, I'm simplifying this a little bit. Really all we had to do was we had to allow clinicians to be able to meet with patients. We had to be able to get reimbursed, that's the important part, from the national healthcare system particularly in Sweden. We had to be able to share data with the national healthcare services. That's both getting data and being able to write data back to them.

As we grew, we added more requirements and more functionality. Things became naturally more complicated. We added prescriptions. When we moved into other parts of Europe we started having to deal with more complexity. We had to deal with regional differences. Things like in the UK the reimbursement model is based on a fee per action, so we get paid for every patient appointment we have. Whereas when we built the system in Sweden the Swedish model is based on capitation, which means that the patient has to be registered with your clinic in order for us to be reimbursed. They were very different models of getting reimbursed. We also had to deal with a lot of different security and regulatory differences.

Things like age of consent, dealing with children and things like that. We started adding new clinical types, so new health services. Things like mental health, nursing services. These services had very different workflows to the original GP workflows. We started opening our own physical branches and we started having to deal with different scheduling models.

Particularly, we started to have to deal with separated schedule books. Each physical practice would have their own separated schedule that had to be maintained and managed differently from all the other schedules. This was something that was a big difference because originally when we were just digitally online, we just had one big pool of doctors who would serve us a queue. Most recently, we've added insurance companies and private companies who want to provide our services to their employees as a benefit. This has added more workflows that we had to manage. With insurance workflows we have to be able to make decisions on the fly as to whether or not we can see that patient. That means we have to be talking in real time to insurance third-party APIs and be able to make complex decisions on the go. We also came across issues with data sharing.

In the UK, for example, if we see a patient through an NHS contract, we're allowed to use NHS APIs and NHS data. If we see that same patient through an insurance workflow, we're not allowed to use any of the APIs. We're not allowed to use that data either. Suddenly, we had to start understanding, who is paying for this appointment, and be able to make decisions rapidly as to what data we could use, what APIs we could use and the like. That's a plotted history of our product.

Architecture and Services (Components)

When we started, life was simple. We made this ourselves, maybe you can tell. Again, life was easy. We had clinicians and we had users, and they could have meetings. We could store their data in what we called, and I still don't understand this joke, the fax machine. It was ok. It worked. In fact, it worked really well. We could scale quite easily with this service in terms of the volume, and life was good. We started having patients and we started increasing the number of patients we were seeing. We started adding more functionality. We added the ability to manage prescriptions. As we grew, sometimes it was quite easy for us to add new services because you could fit it in or you could do things. Sometimes, for example, when we had to add new payment models when we moved into the rest of Europe, things became more complicated. We had made assumptions about our payment systems and our payment models when we started in Sweden.

Suddenly, when those models changed, we had to work out how to fit them in. Sometimes we could fit that in just beside the code we'd already written. Other times that would be too difficult and so we'd have to create a new service. The same thing happened across the board when we added mental health services, for example. Mental health services are a very different workflow. They don't necessarily revolve around one meeting with a patient like we had with a GP. You might have a dozen meetings or more meetings, all part of one service as you were. We had to build another service to manage that, and the trend continued. When we moved into physical, we started dealing with queues and scheduling. We already could do queues and scheduling in our meeting service, but we couldn't separate them nicely so we had to refactor parts of that. We had to build a service to go with it to manage some of that complexity.

It was at this time that we really started to see that maybe what we had initially thought, wasn't as perfect as we had initially thought. Things were starting to change. When we started having physical meetings we realized, yes, we've got patients as well. When we started, users were patients and patients were users, and it was simple. Who's a user in a physical sense? We also at this stage started being able to see children. Somebody worked out that children might have parents, we didn't really think about that.

Then, some really clever guy, real person, realized that actually a child might have two parents and they might have two separate accounts. How do we deal with those relationships? We made this work but it wasn't pretty. Remember, this is all through our startup phase. We didn't have the luxury of stopping, pausing everything, and refactoring a bunch of code, refactoring some of our main assumptions. Our primary goal was to get customers in the door. Our primary goal was to try to get profitable, and so we were doing everything we could to make that happen. I must stress this, that wasn't the wrong decision. We absolutely had to do that. If we hadn't have done that, I probably wouldn't be here today. These are decisions that are made because of the situation that you're in, and that's fine.

At some stage, you are going to have to deal with the technical debt you've built. Our insurance workflows were so drastically different to what we had built before that we actually built pretty much a stand-beside service to handle a good chunk of our insurance workflow. We started having duplicate code because we couldn't make it work otherwise. We started complicating the systems that we had.

This was a very organic approach. When we started, we didn't really know where we were going to go. People just did what they needed to do. At the beginning, again, remember this was easy. Our dependencies were very straightforward. You could see which service needed to talk to which service and how things should go. Over time, as we added more services and we added more complexity, those dependencies grew. We didn't have any rules about who could talk to what or when.

Basically, if you needed it, you could build it. We started to realize that our services were no longer really fit for purpose. Many of them grew so bloated through just constant addition of different functionality that they hardly resembled the purpose for which they'd been started in the first place. We had also the opposite problem where people couldn't be bothered or didn't want to wreck what was already there, so they'd create a standalone service often for a very tiny bit of functionality. What was even better was that people didn't necessarily talk as well as perhaps we should have, and so we started to duplicate. Sometimes we had multiple services doing very similar things, but one very similar thing. Again, this is natural. You've got a company that's growing very quickly and we're trying to get as many customers through the door. We lived with it and it worked. We did get customers through the door. Our architecture grew very flat.

Everything could talk to everything else and there were no rules around it. We knew that our services were no longer becoming a cohesive API that anybody could use. Instead, they just became really a big collection of endpoints. Things were starting to become problematic. It was difficult for us to extend. It was difficult for us to change anything. We spent probably two years knowing that this was a problem. It's very easy to identify that you've got a problem. It's a lot harder to actually work out how to fix it. We tried all sorts of things. We went to the bosses and said, can we just stop doing everything for a couple of years and rewrite this? You can guess what their response was. We thought, what if we just decided to do a version 2 of our APIs? Maybe we can just fix the problems with that API.

That failed too, not because they didn't do good work but because we didn't really know what we were building. We were just trying to fix our perceived problems with a very small part of the API without taking the entire picture into view. Remember my golden rule, working systems are better than the promise of working systems. We knew we weren't going to start from scratch, and we knew we had to do it in situ. We realized, the most important thing we had to do was we had to agree on where we were going. We had to stop all pulling in different directions and work out what it was that we wanted to do, and then move in that direction all together. It didn't matter if people took little deviations here and there, as long as they weren't going backwards or southwest.

This is where domain-driven design came to the rescue. We had all of these services and all of these systems that we knew about and we listed them. There's some of them here. This is where we took the decision to flip what we were doing from looking at the product down and look from the functionality up instead. We'd gotten to a stage now that we were mature enough that we did start to understand our systems reasonably well or at least what the functionality needed to be. We didn't have to kowtow to the product team and build a brand-new thing every time because by this stage we'd built most of the functionality. We could start thinking about it in the opposite way. We sat down and we started to think about, what is it that we actually do? What's our core business? We didn't do this in a big team. We tried to do it in big teams. We tried to crowdsource this, and we just had too much whataboutery. There was just too much, what about this edge case? That's not going to fit that. It became counterproductive.

In the end, we had to make a decision. We had to try to decide where to go. We just made a small team and said, we're going to make this broad and we're going to start somewhere so that we can get going in one direction. We sat together and we said, what is it that we do? We do healthcare. That hasn't really gotten us that far, has it? At least we know we don't do bananas. This is what we have now, one big domain of healthcare. We knew we had to dig deeper, and this is where we actually got really pleasantly surprised because actually when we looked at our services it wasn't that hard to start grouping things in big buckets.

In fact, we went right back to the beginning and said, what were we trying to do? We were trying to have meetings online. We looked and we saw we had meetings, we had users, we had a queue service, schedule. That's a bucket. That's really easy. I don't need a PhD in rocket science to work that one out. We put that into a bucket and that became our first domain. Again, things seemed very simple. We looked at what was left, and again we started to realize that actually some of this was quite straightforward. We had patients. We had prescriptions. We had different service types. We were storing their data. We had ways to do referrals. We had all of these services that were really around providing that medical service to a patient. That became a domain called medical. We had two great pillars there ready to go, and that felt really good.

Then we went, we're forgetting probably the most important part of this, how do we get paid? We realized that the payment systems and our reimbursement models and all of that stuff, our contracts, that those things were definitely a domain on their own because they changed for all sorts of reasons, a new government, a new payment model. That became a third domain where we could isolate all of that, let's call it crazy, on its own.

We had three brilliant pillars and that felt right, but we still had a bunch of services left over. We had no idea where these would fit. We had a bunch of services around messaging. Messaging was used by parts of systems in all of those domains. It was used to communicate with patients. It was used to communicate with our contract with the NHS or with GP surgeries. It was used between clinicians to communicate. Where does that go? We also had a bunch of services around EMRs, medical record systems. That's where your patient data is stored. We had a bunch of services that were connecting to different medical record systems.

Again, these were used by all of the domains. What were we going to do with those? We didn't really know. We didn't want to have a handful of separate domains standing on their own, so we did what any sane person would do and we fudged it. We created a domain that isn't a domain, really. We created something that we just called support systems, and whatever didn't really fit or was used by multiple domains we put into that. We were left with a very simple model of what we did. This reduced our cognitive load when we had to start dealing with new functionality or new systems. It meant that our developers didn't have to worry about 50 services when they were adding functionality, but they could just deal with the one or two that were relevant to their domain.

We got here. We know what we're going to do. How do we go from there? Domain-driven design to me is a journey, it is not a destination. I never expect us to get to what that domain looked like. We might but I doubt it. As we go, as we develop, as we work towards that domain, things will inevitably change. Requirements change. Our understanding of the problem changes. We have to expect that that's going to happen. The beauty of that was that it wasn't super specific. It wasn't like anything was going to trip us up, but it all gave us a unified idea of where we wanted to go. It was something that everybody could get behind. What got you here, won't get you there. At least we now know where there is. Let's take a look at a few of the approaches that we used, not to get us to domain driven, but to move us in that direction.

The first one I call the take that approach. The take that approach is where we have a bunch of singers who are all right on their own, but we put them together and they become greater than the sum of their parts. You remember I was talking about those medical record systems. We had a good dozen or so different services that managed our connections to medical record systems. They were used in different ways by different parts of the code at different times. We started to have a couple of duplications. We'd have code in two different areas calling the same EMR in a different way because they needed a slightly different outcome or a slightly different result. All of the different connections to those EMRs were implemented totally differently. All of the code that used those systems couldn't just talk to a different EMR if we wanted to change, they had to rewrite or reorder how they were using them.

One thing about all of these EMRs is that they weren't consistent at all. The way that you had to get data from each of them was different. They all had different models for the data. They all had different ways of connecting to them. For some of the systems, or a lot of the systems even, you could connect over HTTP. There are some systems that you can only connect to locally through a TCP port. We actually had to have a VPN into some of these systems. That complexity, coupled with the fact that we were just duplicating all of this logic all over the place, seemed ripe for simplification.

Again, nothing fantastic here, but this was perfect for an adapter proxy pattern. We created a single proxy at the top where all of our clients could connect to if they wanted medical record data. They could connect to a single consistent API and get a single set of domain models back. If they wanted to connect to a different medical record system, they'd just call the same one and just say, I want it from a different system. In one swoop, it standardized all of this complexity. We hid all of that complexity in the EMR connectors. The EMR connectors would be responsible for translating from the medical record system to our domain models, and we'd have one connector for every external EMR. It became very easy for us to now just talk to a different medical record system, because all we had to do was add another connector. We didn't have to rewrite all of the code from top to bottom. That was the take that approach.

The next approach is the opposite of the take that approach, the Robbie Williams. The Robbie Williams approach is where you take the one singer in the band who's actually any good, and you get rid of the rest. I apologize to all of you take that fans. We had a REST Entity called care facility, and there were over 40 endpoints dealing with a care facility. Thirty-one, I think, when we counted last, of those endpoints, were just one variation or another of getting a care facility. You can see we got creative with the naming. We've got with a hyphen, without a hyphen. We've got a plural. We've put physical in there. We had a second version. Again, this is obvious, but we came to this and went, that's a bit mad, isn't it? Most of these endpoints, the only difference between them was they would call by a different column, they'd filter by a different column. We had all these endpoints. We had two versions of our APIs.

In behind all of that, in our code, we had 15 different service classes, all basically just querying a care facility. We had five different data access objects, all for a care facility. We realized we could just take this and make this simple. We could just have one query endpoint. The way we did this, we'd already tried this, and you can see that with the V2. We didn't want to go down that road again. What we decided to do was that we'd start off with our brand-new single query endpoint, we'd go through each of those 31 endpoints one at a time, and we'd make sure that we could match the functionality in our new query endpoint. We'd go from top to bottom on our systems and get all the calling code, point it to the new endpoint, and then we deleted the old endpoint, so that every time we went through a new endpoint, we knew we'd gotten rid of it. It was never going to stay around anymore. That allowed us to take our 40 endpoints and get one endpoint, one version, one service, and one data access object.

Domain Modelling (Code)

Let's move on to our domain modeling. This was what we started with. Again, it was simple. We designed this ourselves, and it matched what we knew about the world when we started. We had users who could have a meeting. We had clinicians who could join that meeting. We knew who was paying for it. We would store some data. The way that we were able to really dramatically speed up the way that clinicians would handle our meetings was that we standardized using forms, and that made it really quick and easy for clinicians to go through a meeting, fill out the information they had, and move on. It was also great for us to be able to review those meetings to ensure that we were still providing the same levels of clinical excellence because we were standardized. The forms were hugely important for us, but when we stored the data, we stored the data in the format of that form because that's what made sense at the time.

As we grew, that started to show its age. Forms would change over time. If we want to look at an old meeting that was written in an old form, and we've got the data, how do we render that form again? We had to be able to match those things, and that became difficult, especially with more iterations. We had to support UX that was old and things like that. Because the data wasn't stored semantically, we had no way of being able to ask the kinds of questions you would expect to be able to ask of a system like this. How many people have we seen for COVID-19? We could answer those questions, but it was really difficult.

One of the other aspects we had was that you can see that everything was revolving around the meeting object. The meeting was really our central pillar for understanding our system. As we started adding new workflows, that assumption started to become invalid. When we had mental health services, we had to be able to manage a service over multiple meetings, and so things were starting to get strained. We talked about users being patients, and patients being users, and them not being the same thing. Again, we realized that our model was starting to strain at the seams. It was starting to become difficult to use. It was starting to show some of the frailties.

We had a look, and this was different from our approach to services. We decided here, this is a healthcare model. This is a popular industry in the world, I think. Maybe somebody has done this before. Turns out they have. FHIR stands for Fast Healthcare Interoperability Resources. It is a full schema and model for healthcare objects. It's used around the globe. We were like, "I don't know why we didn't find this a couple of years ago, but excellent. We've got it now. This will solve all of our problems". No, that was bad timing. It's great. It is fantastic. It's a beautiful set of resources and models that have been really well thought out. Anything you could possibly want in the healthcare space is catered for.

The fact that they've been able to manage all of the complexity that occurs around the world with a model like this is amazing. Some of the things you might notice here is that in order to support all of that variability, they've had to make it fairly abstract. Things like the patient name isn't a name, it's a human name. Inside the human name, object, or a bunch of smaller objects. If you look in the contact relationship, you've got a codable concept. You'll see that codable concept in the communication language. You'll see it in the marital status. Codable concept is basically a namespace key-value pair. That's fantastic because it allows us to model all of these things or allows them to model all these things without being too specific. Can you imagine your frontend developer who wants to get the first name on a screen shouting at you when he's like, what do you mean I have to go through eight different objects to get the first name?

It was great for telling us how things should look, but it wasn't necessarily great for every implementation that we would need. When we took this model into our medical domain, it was like the lights came on. It made sense because everything was specific to the much more narrow domain in which we were working. We had patients. We don't have users. We had appointments instead of meetings. We had clinicians. Clinicians are clinicians. Instead of this random set of forms and data that we had, we had observations which were strongly typed, so we could now start asking questions like, how many people have we seen for COVID-19? What was fantastic about doing this exercise was that when we started looking at the other domains that we had, it started to make a lot of sense. We could see where the objects in the different domains met. We could see how they related to each other. We could also see why they weren't the same thing anymore. This was a massive step forward for us.

Let's move to my last approach that we used around how we dealt with domain models. That's the approach formerly known as Prince. This is where we take a system that works and that is useful and that we quite like, but we realized that there was actually another service, a hidden service that we hadn't identified at first that would better suit part of our requirements. That we'd had one service that was actually trying to do multiple things, and it did both of them badly. It would be better to leave the service as-is for the things that it was useful for, but to build a new service for the things that it didn't do well.

This is what we did for our medical data. We took the FHIR model and we built a new data service from it using FHIR, not directly, but as an inspiration. We did think about using it directly, but then we got to that, how are we going to tell the frontend developer that he's got to learn FHIR and learn these complex models? We didn't. We used it for what it was good for. We took the best bits, particularly the objects and the relationships between the objects, and then we modeled the properties as made sense for us and for our systems. Now we can very easily query our data. We've got a given name there, so our frontend developer is happy.

This drastically improved our understanding of the system because we no longer were tightly coupling our patient data to how it was inputted. It allowed us to be able to make changes in the input forms without having to worry about the backend. Things become simple in small doses. There are three approaches, the take that, where we can get a bunch of things that seem similar, maybe they're not rockstars in their own, but we can put them together and they'll be greater than the sum of their parts. We can have the Robbie Williams approach, where we take the one good thing that you have and then delete all the rest. We have the approach formerly known as Prince, where we rebrand or rework some of the functionality that we've discovered we needed at the time, but we still can use the old stuff because the old stuff is still good.

Summary

Remember, you are never going to be in a situation where things don't change. People are always going to be coming to you and asking you to make new things, to build new things, to change how they work. You have to lean into it and you have to accept it. We've used domain-driven design very successfully to reorganize how we think about our systems, even the ones that are already running. Lastly, I'd really recommend that you organize around the functionality that you have, not around what the product says they need, because, remember, domain-driven design is a journey, not a destination.

Questions and Answers

Dr. Kreindler: How do you think larger health systems can get to 11 out of 10 in terms of their whole architectural strategy? Because right now it feels like most of us are at 1 or 2 out of 10 in large health systems.

Leander Vanderbijl: There's a lot at play. There's a lot of perceived complexity, I think, in the healthcare industry. I think a lot of that complexity isn't necessarily complexity, but it's just different ways of working. Trying to convince people to move towards a standardized approach to things, which isn't necessarily a be-all and end-all in and of itself, but has proven very successful for us, can be difficult. We go to practices and we say, if you do things this way, we can really improve your throughput, we can really improve your services.

A lot of people go, yes, but I can't do it that way because we use a fax machine or whatever. A lot of that is changing people's minds. There's a lot of vested interests in terms of how systems work, and maybe not even necessarily vested interests, but medical data is very protected, rightly so. That makes it very difficult if you want to start doing novel things with it. It makes it very hard to get around some of those hurdles and to be able to convince large organizations like the NHS or other things to be able to allow you to get into data, to do things that maybe are slightly off the beaten track.

Dr. Kreindler: You talked about domain-driven design. By that, I'm assuming you're talking about the different components of the business, are you, or domain as in the healthcare domain?

Leander Vanderbijl: It's more in a software perspective. It's how we group our functionality together to be able to make it easier to understand and to develop.

Participant 1: With the increasing role of tech companies in the government sphere, do you think we'd ever get to a point where governments themselves are agreeing on data models or other interfaces, like the FHIR one, that could make just business on the international scale easier?

Leander Vanderbijl: Yes. In fact, the NHS has adopted this wholesale. In fact, their latest set of GP Connect APIs are all FHIR-based and they are brilliant. There's a lot that people complain about the NHS, but their GP Connect APIs are absolutely brilliant. They're very well thought out, they're very well modeled. If you can get access to them, they're amazing. It is difficult because they're under a lot of pressure. There is a lot of governance you need to go through to be able to get access to them, but they are fantastic. It would be nice if the private companies that had medical record systems would support FHIR as beautifully as the NHS does, and that's actually been almost more of a problem than the national healthcare systems.

Participant 2: Domain-driven design is obviously very good for informing your software, but to what extent, when you've drawn your models, you've mapped out domain, you understand what your software currently does. Can those models maybe inform back on the product side of things, go, actually, what you're suggesting here, we're moving into a new domain? Are we losing the purity of the focus? Are we maybe changing direction a bit? Can it shake back and affect the product as much as it affects the software that comes out of it?

Leander Vanderbijl: Absolutely, it can. The way you model things can absolutely impact how well you can do certain things. We had the instance with the way that our data was stored, we couldn't answer a lot of the questions that we wanted to ask. Once we started storing it in a model that made sense, in a domain that made sense, we suddenly could ask those questions, but we could also ask a lot more that came up, because they were like, "You can do this. Yes, I hadn't thought about that kind of question". Absolutely, it's a two-way street there. Definitely.

Participant 3: To paraphrase, "We drive down costs and increase efficiency by standardizing the business workflow of medical care, domain-driven design being a great way of standardizing IT systems". I totally agree. I'm a big fan. Have you thought about the next step, so, for example, 4C analysis in the business workflow to further drive optimization? Given the data you now have or the personnel you have, how you could use something more like 4C to drive the actual outcomes in the medical business, because it's a different approach to try to drive different medical outcomes through process change.

Leander Vanderbijl: Absolutely. The trick there is around governance. How long can you keep data like this? Are you allowed to use it for other purposes, like training data models or that sort of thing? That's a bit of a minefield at the moment. I think there are still a lot of people trying to work out the ins and outs of that. We are starting to do things like automated triage, so being able to say, given a set of complaints, do they need to be seen tomorrow, yesterday, or whatever?

Participant 3: After domain-driven design, have you thought about what would be the next thing that you would implement, like a 4C analysis or something else?

Leander Vanderbijl: No is probably the shortest answer. Again, this is a journey. What we want to do is see where it takes us, really, and try not to be too prescriptive of where we're going to go. Once we start getting the initial domains starting to make sense, then we have the time to start looking deeper and fixing some of the other problems. At the first hurdles, we're really fixing the top layer of problems. We do need to go deeper into some of the way that some of our other code is written and some of the problems that are there. That's natural.

Micro frontend

Mike's Notes

Today, I learned this new term from Neo Kim's newsletter. Pipi 9's frontend can be described as a "Micro frontend."

Pipi 6 was designed in 2017 with hundreds of self-contained, domain-driven micro apps.

Pipi 8 refactoring broke the frontend and self-documentation.

Pipi 9 refactoring is slowly restoring self-documentation and the front end.

The Render Engine (rnd) pre-assembles each webpage without needing any JavaScript.
Using micro-apps greatly simplifies automatic production by the server.
The file size of each web page is about 1% of the size of the JavaScript equivalent.

Below is an article from 2019 I found on Martin Fowler's Bliki.

Resources

References

Reference

Repository

Home > Ajabbi Research > Library > Subscriptions > System Design Newsletter
Home > Handbook >

Last Updated

21/05/2025

Micro frontends

By: Cam Jackson

Martinfowler.com: 19/06/2019

Good frontend development is hard. Scaling frontend development so that many teams can work simultaneously on a large and complex product is even harder. In this article we'll describe a recent trend of breaking up frontend monoliths into many smaller, more manageable pieces, and how this architecture can increase the effectiveness and efficiency of teams working on frontend code. As well as talking about the various benefits and costs, we'll cover some of the implementation options that are available, and we'll dive deep into a full example application that demonstrates the technique.

In recent years, microservices have exploded in popularity, with many organisations using this architectural style to avoid the limitations of large, monolithic backends. While much has been written about this style of building server-side software, many companies continue to struggle with monolithic frontend codebases.

Perhaps you want to build a progressive or responsive web application, but can't find an easy place to start integrating these features into the existing code. Perhaps you want to start using new JavaScript language features (or one of the myriad languages that can compile to JavaScript), but you can't fit the necessary build tools into your existing build process. Or maybe you just want to scale your development so that multiple teams can work on a single product simultaneously, but the coupling and complexity in the existing monolith means that everyone is stepping on each other's toes. These are all real problems that can all negatively affect your ability to efficiently deliver high quality experiences to your customers.

Lately we are seeing more and more attention being paid to the overall architecture and organisational structures that are necessary for complex, modern web development. In particular, we're seeing patterns emerge for decomposing frontend monoliths into smaller, simpler chunks that can be developed, tested and deployed independently, while still appearing to customers as a single cohesive product. We call this technique micro frontends, which we define as:

“An architectural style where independently deliverable frontend applications are composed into a greater whole”

In the November 2016 issue of the Thoughtworks technology radar, we listed micro frontends as a technique that organisations should Assess. We later promoted it into Trial, and finally into Adopt, which means that we see it as a proven approach that you should be using when it makes sense to do so.

A screenshot of micro frontends on the Thoughtworks tech radar

Figure 1: Micro frontends has appeared on the tech radar several times.

Some of the key benefits that we've seen from micro frontends are:
smaller, more cohesive and maintainable codebases
more scalable organisations with decoupled, autonomous teams
the ability to upgrade, update, or even rewrite parts of the frontend in a more incremental fashion than was previously possible
It is no coincidence that these headlining advantages are some of the same ones that microservices can provide.

Of course, there are no free lunches when it comes to software architecture - everything comes with a cost. Some micro frontend implementations can lead to duplication of dependencies, increasing the number of bytes our users must download. In addition, the dramatic increase in team autonomy can cause fragmentation in the way your teams work. Nonetheless, we believe that these risks can be managed, and that the benefits of micro frontends often outweigh the costs.

Benefits

Rather than defining micro frontends in terms of specific technical approaches or implementation details, we instead place emphasis on the attributes that emerge and the benefits they give.

Incremental upgrades

For many organisations this is the beginning of their micro frontends journey. The old, large, frontend monolith is being held back by yesteryear's tech stack, or by code written under delivery pressure, and it's getting to the point where a total rewrite is tempting. In order to avoid the perils of a full rewrite, we'd much prefer to strangle the old application piece by piece, and in the meantime continue to deliver new features to our customers without being weighed down by the monolith.

This often leads towards a micro frontends architecture. Once one team has had the experience of getting a feature all the way to production with little modification to the old world, other teams will want to join the new world as well. The existing code still needs to be maintained, and in some cases it may make sense to continue to add new features to it, but now the choice is available.

The endgame here is that we're afforded more freedom to make case-by-case decisions on individual parts of our product, and to make incremental upgrades to our architecture, our dependencies, and our user experience. If there is a major breaking change in our main framework, each micro frontend can be upgraded whenever it makes sense, rather than being forced to stop the world and upgrade everything at once. If we want to experiment with new technology, or new modes of interaction, we can do it in a more isolated fashion than we could before.

Simple, decoupled codebases

The source code for each individual micro frontend will by definition be much smaller than the source code of a single monolithic frontend. These smaller codebases tend to be simpler and easier for developers to work with. In particular, we avoid the complexity arising from unintentional and inappropriate coupling between components that should not know about each other. By drawing thicker lines around the bounded contexts of the application, we make it harder for such accidental coupling to arise.

Of course, a single, high-level architectural decision (i.e. “let's do micro frontends”), is not a substitute for good old fashioned clean code. We're not trying to exempt ourselves from thinking about our code and putting effort into its quality. Instead, we're trying to set ourselves up to fall into the pit of success by making bad decisions hard, and good ones easy. For example, sharing domain models across bounded contexts becomes more difficult, so developers are less likely to do so. Similarly, micro frontends push you to be explicit and deliberate about how data and events flow between different parts of the application, which is something that we should have been doing anyway!

Independent deployment

Just as with microservices, independent deployability of micro frontends is key. This reduces the scope of any given deployment, which in turn reduces the associated risk. Regardless of how or where your frontend code is hosted, each micro frontend should have its own continuous delivery pipeline, which builds, tests and deploys it all the way to production. We should be able to deploy each micro frontend with very little thought given to the current state of other codebases or pipelines. It shouldn't matter if the old monolith is on a fixed, manual, quarterly release cycle, or if the team next door has pushed a half-finished or broken feature into their master branch. If a given micro frontend is ready to go to production, it should be able to do so, and that decision should be up to the team who build and maintain it.

A diagram showing 3 applications independently going from source control, through build, test and deployment to production

Figure 2: Each micro frontend is deployed to production independently

Autonomous teams

As a higher-order benefit of decoupling both our codebases and our release cycles, we get a long way towards having fully independent teams, who can own a section of a product from ideation through to production and beyond. Teams can have full ownership of everything they need to deliver value to customers, which enables them to move quickly and effectively. For this to work, our teams need to be formed around vertical slices of business functionality, rather than around technical capabilities. An easy way to do this is to carve up the product based on what end users will see, so each micro frontend encapsulates a single page of the application, and is owned end-to-end by a single team. This brings higher cohesiveness of the teams' work than if teams were formed around technical or “horizontal” concerns like styling, forms, or validation.

A diagram showing teams formed around 3 applications, and warning against forming a 'styling' team

Figure 3: Each application should be owned by a single team

In a nutshell

In short, micro frontends are all about slicing up big and scary things into smaller, more manageable pieces, and then being explicit about the dependencies between them. Our technology choices, our codebases, our teams, and our release processes should all be able to operate and evolve independently of each other, without excessive coordination.

The example

Imagine a website where customers can order food for delivery. On the surface it's a fairly simple concept, but there's a surprising amount of detail if you want to do it well:

There should be a landing page where customers can browse and search for restaurants. The restaurants should be searchable and filterable by any number of attributes including price, cuisine, or what a customer has ordered previously
Each restaurant needs its own page that shows its menu items, and allows a customer to choose what they want to eat, with discounts, meal deals, and special requests
Customers should have a profile page where they can see their order history, track delivery, and customise their payment options

A wireframe of a food delivery website

Figure 4: A food delivery website may have several reasonably complex pages

There is enough complexity in each page that we could easily justify a dedicated team for each one, and each of those teams should be able to work on their page independently of all the other teams. They should be able to develop, test, deploy, and maintain their code without worrying about conflicts or coordination with other teams. Our customers, however, should still see a single, seamless website.

Throughout the rest of this article, we'll be using this example application wherever we need example code or scenarios.

Integration approaches

Given the fairly loose definition above, there are many approaches that could reasonably be called micro frontends. In this section we'll show some examples and discuss their tradeoffs. There is a fairly natural architecture that emerges across all of the approaches - generally there is a micro frontend for each page in the application, and there is a single container application, which:

renders common page elements such as headers and footers
addresses cross-cutting concerns like authentication and navigation
brings the various micro frontends together onto the page, and tells each micro frontend when and where to render itself

A web page with boxes drawn around different sections. One box wraps the whole page, labelling it as the 'container application'. Another box wraps the main content (but not the global page title and navigation), labelling it as the 'browse micro frontend'

Figure 5: You can usually derive your architecture from the visual structure of the page

Server-side template composition

We start with a decidedly un-novel approach to frontend development - rendering HTML on the server out of multiple templates or fragments. We have an index.html which contains any common page elements, and then uses server-side includes to plug in page-specific content from fragment HTML files:

We serve this file using Nginx, configuring the $PAGE variable by matching against the URL that is being requested:

server {
listen 8080;
server_name localhost;
root /usr/share/nginx/html;
index index.html;
ssi on;
# Redirect / to /browse
rewrite ^/$ http://localhost:8080/browse redirect;
# Decide which HTML fragment to insert based on the URL
location /browse {
set $PAGE 'browse';
}
location /order {
set $PAGE 'order';
}
location /profile {
set $PAGE 'profile'
}
# All locations should render through index.html
error_page 404 /index.html;
}

This is fairly standard server-side composition. The reason we could justifiably call this micro frontends is that we've split up our code in such a way that each piece represents a self-contained domain concept that can be delivered by an independent team. What's not shown here is how those various HTML files end up on the web server, but the assumption is that they each have their own deployment pipeline, which allows us to deploy changes to one page without affecting or thinking about any other page.

For even greater independence, there could be a separate server responsible for rendering and serving each micro frontend, with one server out the front that makes requests to the others. With careful caching of responses, this could be done without impacting latency.

A flow diagram showing a browser making a request to a 'container app server', which then makes requests to one of either a 'browse micro frontend server' or a 'order micro frontend server'

Figure 6: Each of these servers can be built and deployed to independently

This example shows how micro frontends is not necessarily a new technique, and does not have to be complicated. As long as we're careful about how our design decisions affect the autonomy of our codebases and our teams, we can achieve many of the same benefits regardless of our tech stack.

Build-time integration

One approach that we sometimes see is to publish each micro frontend as a package, and have the container application include them all as library dependencies. Here is how the container's package.json might look for our example app:

{
"name": "@feed-me/container",
"version": "1.0.0",
"description": "A food delivery web app",
"dependencies": {
"@feed-me/browse-restaurants": "^1.2.3",
"@feed-me/order-food": "^4.5.6",
"@feed-me/user-profile": "^7.8.9"
}
}

At first this seems to make sense. It produces a single deployable Javascript bundle, as is usual, allowing us to de-duplicate common dependencies from our various applications. However, this approach means that we have to re-compile and release every single micro frontend in order to release a change to any individual part of the product. Just as with microservices, we've seen enough pain caused by such a lockstep release process that we would recommend strongly against this kind of approach to micro frontends.

Having gone to all of the trouble of dividing our application into discrete codebases that can be developed and tested independently, let's not re-introduce all of that coupling at the release stage. We should find a way to integrate our micro frontends at run-time, rather than at build-time.

Run-time integration via iframes

One of the simplest approaches to composing applications together in the browser is the humble iframe. By their nature, iframes make it easy to build a page out of independent sub-pages. They also offer a good degree of isolation in terms of styling and global variables not interfering with each other.

<html>
<head>
<title>Feed me!</title>
</head>
<body>
<h1>Welcome to Feed me!</h1>
<iframe id="micro-frontend-container"></iframe>
<script type="text/javascript">
const microFrontendsByRoute = {
'/': 'https://browse.example.com/index.html',
'/order-food': 'https://order.example.com/index.html',
'/user-profile': 'https://profile.example.com/index.html',
};
const iframe = document.getElementById('micro-frontend-container');
iframe.src = microFrontendsByRoute[window.location.pathname];
</script>
</body>
</html>

Just as with the server-side includes option, building a page out of iframes is not a new technique and perhaps does not seem that exciting. But if we revisit the chief benefits of micro frontends listed earlier, iframes mostly fit the bill, as long as we're careful about how we slice up the application and structure our teams.

We often see a lot of reluctance to choose iframes. While some of that reluctance does seem to be driven by a gut feel that iframes are a bit “yuck”, there are some good reasons that people avoid them. The easy isolation mentioned above does tend to make them less flexible than other options. It can be difficult to build integrations between different parts of the application, so they make routing, history, and deep-linking more complicated, and they present some extra challenges to making your page fully responsive.

Run-time integration via JavaScript

The next approach that we'll describe is probably the most flexible one, and the one that we see teams adopting most frequently. Each micro frontend is included onto the page using a <script> tag, and upon load exposes a global function as its entry-point. The container application then determines which micro frontend should be mounted, and calls the relevant function to tell a micro frontend when and where to render itself.

<html>
<head>
<title>Feed me!</title>
</head>
<body>
<h1>Welcome to Feed me!</h1>


<script src="https://browse.example.com/bundle.js"></script>
<script src="https://order.example.com/bundle.js"></script>
<script src="https://profile.example.com/bundle.js"></script>
<div id="micro-frontend-root"></div>
<script type="text/javascript">
// These global functions are attached to window by the above scripts
const microFrontendsByRoute = {
'/': window.renderBrowseRestaurants,
'/order-food': window.renderOrderFood,
'/user-profile': window.renderUserProfile,
};
const renderFunction = microFrontendsByRoute[window.location.pathname];
// Having determined the entry-point function, we now call it,
// giving it the ID of the element where it should render itself
renderFunction('micro-frontend-root');
</script>
</body>
</html>

The above is obviously a primitive example, but it demonstrates the basic technique. Unlike with build-time integration, we can deploy each of the bundle.js files independently. And unlike with iframes, we have full flexibility to build integrations between our micro frontends however we like. We could extend the above code in many ways, for example to only download each JavaScript bundle as needed, or to pass data in and out when rendering a micro frontend.

The flexibility of this approach, combined with the independent deployability, makes it our default choice, and the one that we've seen in the wild most often. We'll explore it in more detail when we get into the full example.

Run-time integration via Web Components

One variation to the previous approach is for each micro frontend to define an HTML custom element for the container to instantiate, instead of defining a global function for the container to call.

<html>
<head>
<title>Feed me!</title>
</head>
<body>
<h1>Welcome to Feed me!</h1>


<script src="https://browse.example.com/bundle.js"></script>
<script src="https://order.example.com/bundle.js"></script>
<script src="https://profile.example.com/bundle.js"></script>
<div id="micro-frontend-root"></div>
<script type="text/javascript">
// These element types are defined by the above scripts
const webComponentsByRoute = {
'/': 'micro-frontend-browse-restaurants',
'/order-food': 'micro-frontend-order-food',
'/user-profile': 'micro-frontend-user-profile',
};
const webComponentType = webComponentsByRoute[window.location.pathname];
// Having determined the right web component custom element type,
// we now create an instance of it and attach it to the document
const root = document.getElementById('micro-frontend-root');
const webComponent = document.createElement(webComponentType);
root.appendChild(webComponent);
</script>
</body>
</html>

The end result here is quite similar to the previous example, the main difference being that you are opting in to doing things 'the web component way'. If you like the web component spec, and you like the idea of using capabilities that the browser provides, then this is a good option. If you prefer to define your own interface between the container application and micro frontends, then you might prefer the previous example instead.

Styling

CSS as a language is inherently global, inheriting, and cascading, traditionally with no module system, namespacing or encapsulation. Some of those features do exist now, but browser support is often lacking. In a micro frontends landscape, many of these problems are exacerbated. For example, if one team's micro frontend has a stylesheet that says h2 { color: black; }, and another one says h2 { color: blue; }, and both these selectors are attached to the same page, then someone is going to be disappointed! This is not a new problem, but it's made worse by the fact that these selectors were written by different teams at different times, and the code is probably split across separate repositories, making it more difficult to discover.

Over the years, many approaches have been invented to make CSS more manageable. Some choose to use a strict naming convention, such as BEM, to ensure selectors only apply where intended. Others, preferring not to rely on developer discipline alone, use a pre-processor such as SASS, whose selector nesting can be used as a form of namespacing. A newer approach is to apply all styles programatically with CSS modules or one of the various CSS-in-JS libraries, which ensures that styles are directly applied only in the places the developer intends. Or for a more platform-based approach, shadow DOM also offers style isolation.

The approach that you pick does not matter all that much, as long as you find a way to ensure that developers can write their styles independently of each other, and have confidence that their code will behave predictably when composed together into a single application.

Shared component libraries

We mentioned above that visual consistency across micro frontends is important, and one approach to this is to develop a library of shared, re-usable UI components. In general we believe that this a good idea, although it is difficult to do well. The main benefits of creating such a library are reduced effort through re-use of code, and visual consistency. In addition, your component library can serve as a living styleguide, and it can be a great point of collaboration between developers and designers.

One of the easiest things to get wrong is to create too many of these components, too early. It is tempting to create a Foundation Platform, with all of the common visuals that will be needed across all applications. However, experience tells us that it's difficult, if not impossible, to guess what the components' APIs should be before you have real-world usage of them, which results in a lot of churn in the early life of a component. For that reason, we prefer to let teams create their own components within their codebases as they need them, even if that causes some duplication initially. Allow the patterns to emerge naturally, and once the component's API has become obvious, you can harvest the duplicate code into a shared library and be confident that you have something proven.

The most obvious candidates for sharing are “dumb” visual primitives such as icons, labels, and buttons. We can also share more complex components which might contain a significant amount of UI logic, such as an auto-completing, drop-down search field. Or a sortable, filterable, paginated table. However, be careful to ensure that your shared components contain only UI logic, and no business or domain logic. When domain logic is put into a shared library it creates a high degree of coupling across applications, and increases the difficulty of change. So, for example, you usually should not try to share a ProductTable, which would contain all sorts of assumptions about what exactly a “product” is and how one should behave. Such domain modelling and business logic belongs in the application code of the micro frontends, rather than in a shared library.

As with any shared internal library, there are some tricky questions around its ownership and governance. One model is to say that as a shared asset, “everyone” owns it, though in practice this usually means that no one owns it. It can quickly become a hodge-podge of inconsistent code with no clear conventions or technical vision. At the other extreme, if development of the shared library is completely centralised, there will be a big disconnect between the people who create the components and the people who consume them. The best models that we've seen are ones where anyone can contribute to the library, but there is a custodian (a person or a team) who is responsible for ensuring the quality, consistency, and validity of those contributions. The job of maintaining the shared library requires strong technical skills, but also the people skills necessary to cultivate collaboration across many teams.

Cross-application communication

One of the most common questions regarding micro frontends is how to let them talk to each other. In general, we recommend having them communicate as little as possible, as it often reintroduces the sort of inappropriate coupling that we're seeking to avoid in the first place.

That said, some level of cross-app communication is often needed. Custom events allow micro frontends to communicate indirectly, which is a good way to minimise direct coupling, though it does make it harder to determine and enforce the contract that exists between micro frontends. Alternatively, the React model of passing callbacks and data downwards (in this case downwards from the container application to the micro frontends) is also a good solution that makes the contract more explicit. A third alternative is to use the address bar as a communication mechanism, which we'll explore in more detail later.

If you are using redux, the usual approach is to have a single, global, shared store for the entire application. However, if each micro frontend is supposed to be its own self-contained application, then it makes sense for each one to have its own redux store. The redux docs even mention “isolating a Redux app as a component in a bigger application” as a valid reason to have multiple stores.

Whatever approach we choose, we want our micro frontends to communicate by sending messages or events to each other, and avoid having any shared state. Just like sharing a database across microservices, as soon as we share our data structures and domain models, we create massive amounts of coupling, and it becomes extremely difficult to make changes.

As with styling, there are several different approaches that can work well here. The most important thing is to think long and hard about what sort of coupling you're introducing, and how you'll maintain that contract over time. Just as with integration between microservices, you won't be able to make breaking changes to your integrations without having a coordinated upgrade process across different applications and teams.

You should also think about how you'll automatically verify that the integration does not break. Functional testing is one approach, but we prefer to limit the number of functional tests we write due to the cost of implementing and maintaining them. Alternatively you could implement some form of consumer-driven contracts, so that each micro frontend can specify what it requires of other micro frontends, without needing to actually integrate and run them all in a browser together.

Backend communication

If we have separate teams working independently on frontend applications, what about backend development? We believe strongly in the value of full-stack teams, who own their application's development from visual code all the way through to API development, and database and infrastructure code. One pattern that helps here is the BFF pattern, where each frontend application has a corresponding backend whose purpose is solely to serve the needs of that frontend. While the BFF pattern might originally have meant dedicated backends for each frontend channel (web, mobile, etc), it can easily be extended to mean a backend for each micro frontend.

There are a lot of variables to account for here. The BFF might be self contained with its own business logic and database, or it might just be an aggregator of downstream services. If there are downstream services, it may or may not make sense for the team that owns the micro frontend and its BFF, to also own some of those services. If the micro frontend has only one API that it talks to, and that API is fairly stable, then there may not be much value in building a BFF at all. The guiding principle here is that the team building a particular micro frontend shouldn't have to wait for other teams to build things for them. So if every new feature added to a micro frontend also requires backend changes, that's a strong case for a BFF, owned by the same team.

A diagram showing three pairs of frontends / backends. The first backend talks only to its own database. The other two backends talk to shared downstream services. Both approaches are valid.

Figure 7: There are many different ways to structure your frontend/backend relationships

Another common question is, how should the user of a micro frontend application be authenticated and authorised with the server? Obviously our customers should only have to authenticate themselves once, so auth usually falls firmly in the category of cross-cutting concerns that should be owned by the container application. The container probably has some sort of login form, through which we obtain some sort of token. That token would be owned by the container, and can be injected into each micro frontend on initialisation. Finally, the micro frontend can send the token with any request that it makes to the server, and the server can do whatever validation is required.

Testing

We don't see much difference between monolithic frontends and micro frontends when it comes to testing. In general, whatever strategies you are using to test a monolithic frontend can be reproduced across each individual micro frontend. That is, each micro frontend should have its own comprehensive suite of automated tests that ensure the quality and correctness of the code.

The obvious gap would then be integration testing of the various micro frontends with the container application. This can be done using your preferred choice of functional/end-to-end testing tool (such as Selenium or Cypress), but don't take things too far; functional tests should only cover aspects that cannot be tested at a lower level of the Test Pyramid. By that we mean, use unit tests to cover your low-level business logic and rendering logic, and then use functional tests just to validate that the page is assembled correctly. For example, you might load up the fully-integrated application at a particular URL, and assert that the hard-coded title of the relevant micro frontend is present on the page.

If there are user journeys that span across micro frontends, then you could use functional testing to cover those, but keep the functional tests focussed on validating the integration of the frontends, and not the internal business logic of each micro frontend, which should have already been covered by unit tests. As mentioned above, consumer-driven contracts can help to directly specify the interactions that occur between micro frontends without the flakiness of integration environments and functional testing.

The example in detail

Most of the rest of this article will be a detailed explanation of just one way that our example application can be implemented. We'll focus mostly on how the container application and the micro frontends integrate together using JavaScript, as that's probably the most interesting and complex part. You can see the end result deployed live at https://demo.microfrontends.com, and the full source code can be seen on Github.

A screenshot of the 'browse' landing page of the full micro frontends demo application

Figure 8: The 'browse' landing page of the full micro frontends demo application

The demo is all built using React.js, so it's worth calling out that React does not have a monopoly on this architecture. Micro frontends can be implemented with many different tools or frameworks. We chose React here because of its popularity and because of our own familiarity with it.

The container

We'll start with the container, as it's the entry point for our customers. Let's see what we can learn about it from its package.json:

{
"name": "@micro-frontends-demo/container",
"description": "Entry point and container for a micro frontends demo",
"scripts": {
"start": "PORT=3000 react-app-rewired start",
"build": "react-app-rewired build",
"test": "react-app-rewired test"
},
"dependencies": {
"react": "^16.4.0",
"react-dom": "^16.4.0",
"react-router-dom": "^4.2.2",
"react-scripts": "^2.1.8"
},
"devDependencies": {
"enzyme": "^3.3.0",
"enzyme-adapter-react-16": "^1.1.1",
"jest-enzyme": "^6.0.2",
"react-app-rewire-micro-frontends": "^0.0.1",
"react-app-rewired": "^2.1.1"
},
"config-overrides-path": "node_modules/react-app-rewire-micro-frontends"
}

In version 1 of react-scripts it was possible to have multiple applications coexist on a single page without conflicts, but version 2 uses some webpack features that cause errors when two or more apps try to render themselves on the one page. For this reason we use react-app-rewired to override some of the internal webpack config of react-scripts. This fixes those errors, and lets us keep relying on react-scripts to manage our build tooling for us.

From the dependencies on react and react-scripts, we can conclude that it's a React.js application created with create-react-app. More interesting is what's not there: any mention of the micro frontends that we're going to compose together to form our final application. If we were to specify them here as library dependencies, we'd be heading down the path of build-time integration, which as mentioned previously tends to cause problematic coupling in our release cycles.

To see how we select and display a micro frontend, let's look at App.js. We use React Router to match the current URL against a predefined list of routes, and render a corresponding component:

<Switch>
<Route exact path="/" component={Browse} />
<Route exact path="/restaurant/:id" component={Restaurant} />
<Route exact path="/random" render={Random} />
</Switch>

The Random component is not that interesting - it just redirects the page to a randomly selected restaurant URL. The Browse and Restaurant components look like this:

const Browse = ({ history }) => (
<MicroFrontend history={history} name="Browse" host={browseHost} />
);
const Restaurant = ({ history }) => (
<MicroFrontend history={history} name="Restaurant" host={restaurantHost} />
);

In both cases, we render a MicroFrontend component. Aside from the history object (which will become important later), we specify the unique name of the application, and the host from which its bundle can be downloaded. This config-driven URL will be something like http://localhost:3001 when running locally, or https://browse.demo.microfrontends.com in production.

Having selected a micro frontend in App.js, now we'll render it in MicroFrontend.js, which is just another React component:

class MicroFrontend extends React.Component {
render() {
return <main id={`${this.props.name}-container`} />;
}
}

This is not the entire class, we'll be seeing more of its methods soon.

When rendering, all we do is put a container element on the page, with an ID that's unique to the micro frontend. This is where we'll tell our micro frontend to render itself. We use React's componentDidMount as the trigger for downloading and mounting the micro frontend:

componentDidMount is a lifecycle method of React components, which is called by the framework just after an instance of our component has been 'mounted' into the DOM for the first time.

class MicroFrontend…
componentDidMount() {
const { name, host } = this.props;
const scriptId = `micro-frontend-script-${name}`;
if (document.getElementById(scriptId)) {
this.renderMicroFrontend();
return;
}
fetch(`${host}/asset-manifest.json`)
.then(res => res.json())
.then(manifest => {
const script = document.createElement('script');
script.id = scriptId;
script.src = `${host}${manifest['main.js']}`;
script.onload = this.renderMicroFrontend;
document.head.appendChild(script);
});
}

We have to fetch the script's URL from an asset manifest file, because react-scripts outputs compiled JavaScript files that have hashes in their filename to facilitate caching.

First we check if the relevant script, which has a unique ID, has already been downloaded, in which case we can just render it immediately. If not, we fetch the asset-manifest.json file from the appropriate host, in order to look up the full URL of the main script asset. Once we've set the script's URL, all that's left is to attach it to the document, with an onload handler that renders the micro frontend:

class MicroFrontend…
renderMicroFrontend = () => {
const { name, history } = this.props;
window[`render${name}`](`${name}-container`, history);
// E.g.: window.renderBrowse('browse-container', history);
};

In the above code we're calling a global function called something like window.renderBrowse, which was put there by the script that we just downloaded. We pass it the ID of the <main> element where the micro frontend should render itself, and a history object, which we'll explain soon. The signature of this global function is the key contract between the container application and the micro frontends. This is where any communication or integration should happen, so keeping it fairly lightweight makes it easy to maintain, and to add new micro frontends in the future. Whenever we want to do something that would require a change to this code, we should think long and hard about what it means for the coupling of our codebases, and the maintenance of the contract.

There's one final piece, which is handling clean-up. When our MicroFrontend component un-mounts (is removed from the DOM), we want to un-mount the relevant micro frontend too. There is a corresponding global function defined by each micro frontend for this purpose, which we call from the appropriate React lifecycle method:

class MicroFrontend…
componentWillUnmount() {
const { name } = this.props;
window[`unmount${name}`](`${name}-container`);
}

In terms of its own content, all that the container renders directly is the top-level header and navigation bar of the site, as those are constant across all pages. The CSS for those elements has been written carefully to ensure that it will only style elements within the header, so it shouldn't conflict with any styling code within the micro frontends.

And that's the end of the container application! It's fairly rudimentary, but this gives us a shell that can dynamically download our micro frontends at runtime, and glue them together into something cohesive on a single page. Those micro frontends can be independently deployed all the way to production, without ever making a change to any other micro frontend, or to the container itself.

The micro frontends

The logical place to continue this story is with the global render function we keep referring to. The home page of our application is a filterable list of restaurants, whose entry point looks like this:

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import registerServiceWorker from './registerServiceWorker';
window.renderBrowse = (containerId, history) => {
ReactDOM.render(<App history={history} />, document.getElementById(containerId));
registerServiceWorker();
};
window.unmountBrowse = containerId => {
ReactDOM.unmountComponentAtNode(document.getElementById(containerId));
};

Usually in React.js applications, the call to ReactDOM.render would be at the top-level scope, meaning that as soon as this script file is loaded, it immediately begins rendering into a hard-coded DOM element. For this application, we need to be able control both when and where the rendering happens, so we wrap it in a function that receives the DOM element's ID as a parameter, and we attach that function to the global window object. We can also see the corresponding un-mounting function that is used for clean-up.

While we've already seen how this function is called when the micro frontend is integrated into the whole container application, one of the biggest criteria for success here is that we can develop and run the micro frontends independently. So each micro frontend also has its own index.html with an inline script to render the application in a “standalone” mode, outside of the container:

<html lang="en">
<head>
<title>Restaurant order</title>
</head>
<body>
<main id="container"></main>
<script type="text/javascript">
window.onload = () => {
window.renderRestaurant('container');
};
</script>
</body>
</html>

A screenshot of the 'order' page running as a standalone application outside of the container

Figure 9: Each micro frontend can be run as a standalone application outside of the container.

From this point onwards, the micro frontends are mostly just plain old React apps. The 'browse' application fetches the list of restaurants from the backend, provides <input> elements for searching and filtering the restaurants, and renders React Router <Link> elements, which navigate to a specific restaurant. At that point we would switch over to the second, 'order' micro frontend, which renders a single restaurant with its menu.

An architecture diagram that shows the sequence of steps for navigation, as described above

Figure 10: These micro frontends interact only via route changes, not directly

The final thing worth mentioning about our micro frontends is that they both use styled-components for all of their styling. This CSS-in-JS library makes it easy to associate styles with specific components, so we are guaranteed that a micro frontend's styles will not leak out and effect the container, or another micro frontend.

Cross-application communication via routing

We mentioned earlier that cross-application communication should be kept to a minimum. In this example, the only requirement we have is that the browsing page needs to tell the restaurant page which restaurant to load. Here we will see how we can use client-side routing to solve this problem.

All three React applications involved here are using React Router for declarative routing, but initialised in two slightly different ways. For the container application, we create a <BrowserRouter>, which internally will instantiate a history object. This is the same history object that we've been glossing over previously. We use this object to manipulate the client-side history, and we can also use it to link multiple React Routers together. Inside our micro frontends, we initialise the Router like this:

In this case, rather than letting React Router instantiate another history object, we provide it with the instance that was passed in by the container application. All of the <Router> instances are now connected, so route changes triggered in any of them will be reflected in all of them. This gives us an easy way to pass “parameters” from one micro frontend to another, via the URL. For example in the browse micro frontend, we have a link like this:

<Link to={`/restaurant/${restaurant.id}`}>

When this link is clicked, the route will be updated in the container, which will see the new URL and determine that the restaurant micro frontend should be mounted and rendered. That micro frontend's own routing logic will then extract the restaurant ID from the URL and render the right information.

Hopefully this example flow shows the flexibility and power of the humble URL. Aside from being useful for sharing and bookmarking, in this particular architecture it can be a useful way to communicate intent across micro frontends. Using the page URL for this purpose ticks many boxes:

Its structure is a well-defined, open standard
It's globally accessible to any code on the page
Its limited size encourages sending only a small amount of data
It's user-facing, which encourages a structure that models the domain faithfully
It's declarative, not imperative. I.e. “this is where we are”, rather than “please do this thing”
It forces micro frontends to communicate indirectly, and not know about or depend on each other directly

When using routing as our mode of communication between micro frontends, the routes that we choose constitute a contract. In this case, we've set in stone the idea that a restaurant can be viewed at /restaurant/:restaurantId, and we can't change that route without updating all applications that refer to it. Given the importance of this contract, we should have automated tests that check that the contract is being adhered to.

Common content

While we want our teams and our micro frontends to be as independent as possible, there are some things that should be common. We wrote earlier about how shared component libraries can help with consistency across micro frontends, but for this small demo a component library would be overkill. So instead, we have a small repository of common content, including images, JSON data, and CSS, which are served over the network to all micro frontends.

There's another thing that we can choose to share across micro frontends: library dependencies. As we will describe shortly, duplication of dependencies is a common drawback of micro frontends. Even though sharing those dependencies across applications comes with its own set of difficulties, for this demo application it's worth talking about how it can be done.

The first step is to choose which dependencies to share. A quick analysis of our compiled code showed that about 50% of the bundles was contributed by react and react-dom. In addition to their size, these two libraries are our most 'core' dependencies, so we know that all micro frontends can benefit from having them extracted. Finally, these are stable, mature libraries, which usually introduce breaking changes across two major versions, so cross-application upgrade efforts should not be too difficult.

As for the actual extraction, all we need to do is mark the libraries as externals in our webpack config, which we can do with a rewiring similar to the one described earlier.

module.exports = (config, env) => {
config.externals = {
react: 'React',
'react-dom': 'ReactDOM'
}
return config;
};

Then we add a couple of script tags to each index.html file, to fetch the two libraries from our shared content server.

<body>
<noscript>
You need to enable JavaScript to run this app.
</noscript>
<div id="root"></div>
<script src="%REACT_APP_CONTENT_HOST%/react.prod-16.8.6.min.js"></script>
<script src="%REACT_APP_CONTENT_HOST%/react-dom.prod-16.8.6.min.js"></script>
</body>

Sharing code across teams is always a tricky thing to do well. We need to ensure that we only share things that we genuinely want to be common, and that we want to change in multiple places at once. However, if we're careful about what we do share and what we don't, then there are real benefits to be gained.

Infrastructure

The application is hosted on AWS, with core infrastructure (S3 buckets, CloudFront distributions, domains, certificates, etc), provisioned all at once using a centralised repository of Terraform code. Each micro frontend then has its own source repository with its own continuous deployment pipeline on Travis CI, which builds, tests, and deploys its static assets into those S3 buckets. This balances the convenience of centralised infrastructure management with the flexibility of independent deployability.

Note that each micro frontend (and the container) gets its own bucket. This means that it has free reign over what goes in there, and we don't need to worry about object name collisions, or conflicting access management rules, from another team or application.

Downsides

At the start of this article, we mentioned that there are tradeoffs with micro frontends, as there are with any architecture. The benefits that we've mentioned do come with a cost, which we'll cover here.

Payload size

Independently-built JavaScript bundles can cause duplication of common dependencies, increasing the number of bytes we have to send over the network to our end users. For example, if every micro frontend includes its own copy of React, then we're forcing our customers to download React n times. There is a direct relationship between page performance and user engagement/conversion, and much of the world runs on internet infrastructure much slower than those in highly-developed cities are used to, so we have many reasons to care about download sizes.

This issue is not easy to solve. There is an inherent tension between our desire to let teams compile their applications independently so that they can work autonomously, and our desire to build our applications in such a way that they can share common dependencies. One approach is to externalise common dependencies from our compiled bundles, as we described for the demo application. As soon as we go down this path though, we've re-introduced some build-time coupling to our micro frontends. Now there is an implicit contract between them which says, “we all must use these exact versions of these dependencies”. If there is a breaking change in a dependency, we might end up needing a big coordinated upgrade effort and a one-off lockstep release event. This is everything we were trying to avoid with micro frontends in the first place!

This inherent tension is a difficult one, but it's not all bad news. Firstly, even if we choose to do nothing about duplicate dependencies, it's possible that each individual page will still load faster than if we had built a single monolithic frontend. The reason is that by compiling each page independently, we have effectively implemented our own form of code splitting. In classic monoliths, when any page in the application is loaded, we often download the source code and dependencies of every page all at once. By building independently, any single page-load will only download the source and dependencies of that page. This may result in faster initial page-loads, but slower subsequent navigation as users are forced to re-download the same dependencies on each page. If we are disciplined in not bloating our micro frontends with unnecessary dependencies, or if we know that users generally stick to just one or two pages within the application, we may well achieve a net gain in performance terms, even with duplicated dependencies.

There are lots of “may’s” and “possibly’s” in the previous paragraph, which highlights the fact that every application will always have its own unique performance characteristics. If you want to know for sure what the performance impacts will be of a particular change, there is no substitute for taking real-world measurements, ideally in production. We've seen teams agonise over a few extra kilobytes of JavaScript, only to go and download many megabytes of high-resolution images, or run expensive queries against a very slow database. So while it's important to consider the performance impacts of every architectural decision, be sure that you know where the real bottlenecks are.

Environment differences

We should be able to develop a single micro frontend without needing to think about all of the other micro frontends being developed by other teams. We may even be able to run our micro frontend in a “standalone” mode, on a blank page, rather than inside the container application that will house it in production. This can make development a lot simpler, especially when the real container is a complex, legacy codebase, which is often the case when we're using micro frontends to do a gradual migration from old world to new. However, there are risks associated with developing in an environment that is quite different to production. If our development-time container behaves differently than the production one, then we may find that our micro frontend is broken, or behaves differently when we deploy to production. Of particular concern are global styles that may be brought along by the container, or by other micro frontends.

The solution here is not that different to any other situation where we have to worry about environmental differences. If we're developing locally in an environment that is not production-like, we need to ensure that we regularly integrate and deploy our micro frontend to environments that are like production, and we should do testing (manual and automated) in these environments to catch integration issues as early as possible. This will not completely solve the problem, but ultimately it's another tradeoff that we have to weigh up: is the productivity boost of a simplified development environment worth the risk of integration issues? The answer will depend on the project!

Operational and governance complexity

The final downside is one with a direct parallel to microservices. As a more distributed architecture, micro frontends will inevitably lead to having more stuff to manage - more repositories, more tools, more build/deploy pipelines, more servers, more domains, etc. So before adopting such an architecture there are a few questions you should consider:

Do you have enough automation in place to feasibly provision and manage the additional required infrastructure?
Will your frontend development, testing, and release processes scale to many applications?
Are you comfortable with decisions around tooling and development practices becoming more decentralised and less controllable?
How will you ensure a minimum level of quality, consistency, or governance across your many independent frontend codebases?

We could probably fill another entire article discussing these topics. The main point we wish to make is that when you choose micro frontends, by definition you are opting to create many small things rather than one large thing. You should consider whether you have the technical and organisational maturity required to adopt such an approach without creating chaos.

Conclusion

As frontend codebases continue to get more complex over the years, we see a growing need for more scalable architectures. We need to be able to draw clear boundaries that establish the right levels of coupling and cohesion between technical and domain entities. We should be able to scale software delivery across independent, autonomous teams.

While far from the only approach, we have seen many real-world cases where micro frontends deliver these benefits, and we've been able to apply the technique gradually over time to legacy codebases as well as new ones. Whether micro frontends are the right approach for you and your organiation or not, we can only hope that this will be part of a continuing trend where frontend engineering and architecture is treated with the seriousness that we know it deserves.

Acknowledgements

Huge thanks to Charles Korn, Andy Marks, and Willem Van Ketwich for their thorough reviews and detailed feedback.
Thanks also to Bill Codding, Michael Strasser, and Shirish Padalkar for their input given on the Thoughtworks internal mailing list.
Thanks to Martin Fowler for his feedback as well, and for giving this this article a home here on his website.
And finally, thanks to Evan Bottcher and Liauw Fendy for their encouragement and support.

Pages

Transforming Primary Care: a Case Study in Evolving from Start-Up to Scale-Up

Mike's Notes

Resources

References

Repository

Last Updated

Transforming Primary Care: a Case Study in Evolving from Start-Up to Scale-Up

Transcript

Roadmap

Tech in Hardware

Company Profile (Context)

Product History (Containers)

Architecture and Services (Components)

Domain Modelling (Code)

Summary

Questions and Answers

Micro frontend

Mike's Notes

Resources

References

Repository

Last Updated

Micro frontends

Benefits

Incremental upgrades

Simple, decoupled codebases

Independent deployment

Autonomous teams

In a nutshell

The example

Integration approaches

Server-side template composition

Build-time integration

{ "name": "@feed-me/container", "version": "1.0.0", "description": "A food delivery web app", "dependencies": { "@feed-me/browse-restaurants": "^1.2.3", "@feed-me/order-food": "^4.5.6", "@feed-me/user-profile": "^7.8.9" }}

Run-time integration via iframes

Run-time integration via JavaScript

Styling

Shared component libraries

Cross-application communication

Backend communication

Testing

The example in detail

The container

<Switch> <Route exact path="/" component={Browse} /> <Route exact path="/restaurant/:id" component={Restaurant} /> <Route exact path="/random" render={Random} /></Switch>

The micro frontends

Cross-application communication via routing

<Link to={`/restaurant/${restaurant.id}`}>

Common content

Infrastructure

Downsides

Payload size

Environment differences

Operational and governance complexity

Conclusion

Acknowledgements

{
"name": "@feed-me/container",
"version": "1.0.0",
"description": "A food delivery web app",
"dependencies": {
"@feed-me/browse-restaurants": "^1.2.3",
"@feed-me/order-food": "^4.5.6",
"@feed-me/user-profile": "^7.8.9"
}
}

<Switch>
<Route exact path="/" component={Browse} />
<Route exact path="/restaurant/:id" component={Restaurant} />
<Route exact path="/random" render={Random} />
</Switch>