A Software Engineer’s Exploration of OpenMRS

I. Introduction

OpenMRS is a free and open-source medical record system designed to support healthcare delivery in low-resource environments. It was first launched in 2004 as a collaboration between multiple organizations, including the Regenstrief Institute and Partners In Health (Wikipedia). It started out being used in Kenya and Rwanda to support HIV care. Today, OpenMRS is used in a variety of settings, including hospitals, clinics, and research organizations, and is supported by a global community of contributors. 

There are other open source medical record system applications (DHIS2 and OpenEMR are a few big ones), and OpenMRS has been integrated into other larger systems (like Bhamni), but I chose to dive into OpenMRS specifically because it has a widely accessible open-source developer community. The purpose of this blog post is to document my own exploration of OpenMRS from a software engineering perspective, providing insights into the code base, architecture, and testing process. My hope is that this post will serve as a valuable resource not just for me as I poke around in a system I’ve wanted to learn about for some time, but also for others interested in exploring OpenMRS or working on similar projects.

II. Exploring the OpenMRS Code Base

Starting with the OpenMRS Wiki, I learned how OpenMRS is built using a three-tier system: a core data model, a java Spring API with full documentation, and a web-based application that uses that API. The project also comes with Implementer Documentation for those who are seeking to set up OpenMRS for actual use. 

I wanted to get a 10,000-mile overhead view of the tools of the project, and the OpenMRS documentation offers a clear path for new open-source contributors. In particular, the Development Process page of the OpenMRS Developers Guide provides a clear step-by-step set of instructions for how to contribute to the open-source project.

OpenMRS’ core data model is built using a concept dictionary meant to define all the unique concepts used in the system. I’m a budding enthusiast of domain-driven design, and this immediately struck me as to how ubiquitous language from a DDD perspective should be defined.

III. Understanding the OpenMRS Architecture

The core domains of the core OpenMRS data model are as follows:

• Concepts: These are utilized to facilitate strongly coded data across the system.
• Encounter: This contains the metadata related to the healthcare providers’ interactions with the patient.
• Form: Essentially, it describes the user interface for various components.
• Observation: This is the place where the actual health information is stored. Within an Encounter, there may be several observations.
• Order: Refers to things or actions that have been requested.
• Patient: Contains fundamental information about the patients within the system.
• User: Contains basic information about the people who use the system.
• Person: Contains basic information about individuals in the system.
• Business: Pertains to non-medical data that is used for administering OpenMRS.
• Groups/Workflow: Refers to Cohort data and workflows.

An in-depth image of the tables used to construct the datamodel can be found here.

A laundry list of OpenMRS tech stack entries:

• Java: primary programming language used in OpenMRS backend
• Spring: a Java platform application framework that helps structure the project to use the Model-View-Controller pattern
• Maven: handles building, reporting and documenting the Java project
• Hibernate: an Object Relational Mapper for Java that abstracts the relational database table design away from the core backend logic
• MySQL: a relational database management system used for data storage
• Jakarta Server Pages (JSP): renders views for the web browser using Java. This is generally considered to be outdated tech since it does not allow designers direct access to the plain HTML of templates, with an alternative like Spring Boot, JavaServer Faces (component-based), and React being preferable
• jQuery: JavaScript library used for HTML DOM tree and Ajax handling
• Direct Web Remoting (DWR): translates java objects and methods into javascript objects and methods during Ajax.
• Groovy: programming language used in reference application user interfaces that tap into the OpenMRS backend.
• Jira: issue management system used to track planned project changes
• GitHub: version control system for OpenMRS core applications
• Bamboo: continuous integration system that performs regression testing

Wow! That’s a whole lot of jargon. To be totally up front, I’m not much of a Java developer (more of a Typescript and Python guy, so far), a lot of these tools were new to me.

IV. Digging into OpenMRS

Ready to dive in? Okay, let’s go.

To start off, I wanted to see what the frontend application looks like to end users. OpenMRS offers a demo of the tool on their website.

I’d like to highlight three points from the user perspective:

1. The system is quite modular, and allows an admin user to manage the Modules currently installed. For example, in the following screenshot, you can see modules like FHIR2 and Bahmni Appointment Scheduling, which correspond to actual code repositories on GitHub (openmrs-module-fhir2 and openmrs-module-appointments respectively):

2. The frontend of the system utilizes the same ubiquitous language that was used in the core data model. For example, in the following screenshot of the Admin view, you can see some of the core domains that were identified in the core data model:

3. Remember how I mentioned the Concept Dictionary? It turns out, the tool allows each instance of the application to define its own terms, called Concepts, in the form of a living dictionary within the application:

The demo is not without its limitations, and I did come across a few bugs with the demo, like when I tried to open the “Form Builder”:

… and when I tried to load the “Cohort Dashboard” from the Admin Dashboard:

Overall though, after playing around with the frontend application demo I can see how this is a flexible tool that could be modified and tweaked based on each implementation. From what I could see, it has a highly modular architecture and a great deal of care has been taken when it comes to designing the tool to be adaptable to different purposes. Cool stuff!

Conclusion

Overall this was a good entrypoint into this application. Next steps for me would definitely be try to get it running locally and maybe even make a few Open Source commits. But even this exercise provided some insights into the application and more broadly into the types of applications that hold up to international development projects within the healthcare space. This was a fun exercise to go through, and I’m excited to see what the next steps will be.