Monolith to Microservices — a practical example

Let’s build an OPD application with microservices


Let’s imagine we have a web application that is developed for a hospital OPD (OutPatient Department). This is a standard Java based web application running on Tomcat. Everything was working fine until recently where there had many outages of the entire application due to increased patient influx due to a pandemic. After a root cause analysis (RCA) done by the development team, they identified that having the application as a single, monolithic application is causing a lot of trouble when fixing issues and rolling out new updates. Some of the challenges they have identified are

  • Adding new features and improving existing features is a tedious task that requires a restart of the entire application, with possible downtimes.
  • The failure of one function can cause the entire application to be useless.
  • If one particular function needs more resources, the entire application needs to be scaled (vertically or horizontally).
  • Integrating with other systems is difficult since most of the functional logic is baked into the same service.
  • It contains large code bases that become complex and hard to manage.

Understanding the monolith

The development team has decided to go with an approach where they can divide the functionality of the application into separate modules which can develop, deploy and maintain separately. They first look at the existing application architecture and identified certain level modularity by going through the user interface of the web application. The below figure depicts the web application and its main components.

Figure: Hospital OPD web application components

As per the preceding figure, we could identify there are several main components that execute specific functions within the application.

  • Patient Registration — This is where the new patients coming into the OPD section within the hospital are registered into the system. The patient or a guardian comes to the registration desk and a hospital staff member collects the patient details and updates the system
  • Patient Inspection — Once the patient is registered into the system, a token is generated and the patient goes to the next step which is the inspection by a doctor or a physician. Once the inspection is done, the patient will be admitted to the temporary treatment unit or admitted to a ward for longer term treatment depending on the patient's status.
  • Temporary Treatment — If the patient is inserted into the temporary treatment unit, the hospital staff will provide the necessary treatments and carry out the tests which are recommended by the doctor. Once the temporary treatment is done, the patient will be released from the unit.
  • Patient Release — Once the patient is ready to be released from the OPD unit, the doctor will provide the final recommendation to send the patient back home or admit the patient to the ward for longer-term treatments.
  • Login (Security) — It is important to secure access to patient data and the records that are stored in the application so that only the people with respective authorization can access the data.
  • Database — This is where the patient details, treatment history, and other health-related information are stored.

Once the main components are identified, the development team has decided to break down the application into separate microservices and develop them as independently managed components. The development team has been using a waterfall type approach to deliver applications in the past and they have identified several challenges with that approach. Some of them are:

  • Longer release cycles (few months)
  • Resistant to make changes causes a lack of innovation
  • Friction between development, deployment, and support teams cause problems such as

— delayed releases

— missing features

— low-quality products

  • Higher risk of failure and uncertainty

This kind of approach was not helping the organization and the business leadership has been questioning this process due to the lack of innovation and flexibility when it comes to improving the software.

Defining the microservices

After considering all the aspects, the development team has decided to break down the application into separate microservices and build the user interface component as a single page application (SPA) that communicates with these microservices. They started with the already identified functional components (above) to implement the new microservices. The below figure depicts the new architecture with the microservices.

Figure: OPD application with microservices

The preceding figure depicts how the team has divided the application into separate microservices based on the functionality and also the usage of an API gateway and a Message Broker to build the application along with a SPA for user interfaces. Some of the core principles of the above diagram are:

  • Each functionality is implemented as a microservice
  • Each microservices has its own datastore
  • A message broker is introduced for inter-service communication
  • An API Gateway is introduced to provide common functions such as security, rate-limiting, analytics for external-facing communications
  • The web interface is designed as a single page application (SPA)

Here the authentication service and the common data service are optional services. If you are using the API Gateway for security, this authentication service can be ignored. The common data service is depicted above if there is a requirement to provide a read-only view of the various data for some applications in a materialized view. Instead of accessing data from 4 major functional microservices, this common data service can provide a read-only copy of the data that are managed by individual microservices. This microservice can also be ignored if there is no such demand for heavy read-only data access.


You can find an actual implementation of the OPD application as a set of microservices as depicted in the preceding figure in the following GitHub repository. This repository contains the source code for this application. The implementation uses Go programming Language along with NATS as the message broker technology.

Read more

If you want to learn more about the topic of implementing microservices with real-world examples, you can read this book which contains the full source code and the explanations of each microservice and the approach.



Learn microservices architecture and practical usage

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Chanaka Fernando

Writes about Microservices, APIs, and Integration. Author of “Designing Microservices Platforms with NATS” and "Solution Architecture Patterns for Enterprise"