Key repositories

The code for O3 is hosted in a number of community-maintained GitHub repositories. The O3 application uses a microfrontends-based architecture. This means that is made up of many smaller, independent applications called "frontend modules". These frontend modules are grouped into different repositories based on which part of O3 they support.

The code in each repository is focused on a particular concern. For example, the Patient Chart (opens in a new tab) repository contains frontend modules for the features of the patient chart, such as allergies, appointments, conditions, forms, medications, notes, programs, test results, and vitals. This is an example of a monorepo, where multiple packages are contained in a single repository; most O3 repositories are structured in this way. The Core (opens in a new tab) repository is special. It contains a few frontend modules, but also the core application logic that loads frontend modules, as well as the O3 tooling (opens in a new tab) and the JavaScript API (opens in a new tab).

Repositories you should know in O3 include:

Core - contains frontend modules for low-level concerns such as authentication. It also contains the base application which loads and stitches together all frontend modules, the app shell. This app shell provides the JavaScript library @openmrs/esm-framework, which provides for essential cross-cutting concerns such as configuration, internationalization, feature flagging, and global state management. This repository also contains the tooling for O3.
Home - renders the UI for the landing page after the user logs in. Implementers can customize this page to render dashboards for things like appointments, patient lists, service queues, data visualizations, and more.
Template - a starter template repository that is designed to be forked and used as template for new frontend modules. It contains all the boilerplate configuration needed to get a new frontend module up and running.
Patient Chart - aggregates frontend modules that altogether constitute the patient dashboard, including widgets for attachments, allergies, appointments, conditions, forms, immunizations, medications, notes, programs, test results, and vitals.
Patient Management - aggregates frontend modules that handle concerns related to patient management such as appointment scheduling, searching for patients, managing patient lists, registering new patients, and managing service queues and wards.
Laboratory App - A frontend module for managing laboratory requests and queues built on OpenMRS 3.x
Angular Form Engine - a form engine library built in Angular. It leverages Angular's powerful support for forms to provide a robust solution with capabilities such as field validation, injection of custom data sources, conditional rendering, historical expressions, and more.
React Form Engine - a form engine library built in React. The RFE is the successor to the Angular Form Engine and is built on top of a modern technology stack with the goal of providing fast, performant, and more flexible form rendering capabilities.
Form Builder - enables users to build OpenMRS form schemas interactively using an embedded JSON schema editor or an interactive builder UI. It also provides a render tab that renders your form schema using the React Form Engine. Users can publish their schemas to their backend server, enabling them to access their forms and collect data in the patient chart in the Clinical Forms workspace.
Fast Data Entry app - enables retrospective data entry workflows. Powered by the Angular Form Engine.
Medication Dispensing app - enables implementers to track medication dispensed within OpenMRS.
O3 Distro Reference application - the reference implementation of O3. Implementers can use this as a starting point for their own distributions.
Admin Tools - renders an interstitial page that links users to various frontend modules that aren't part of the core EMR such as the Form Builder, Cohort Builder, OCL Management dashboard, Stock Management dashboard, and more. It also provides a link to the O2 Legacy Admin UI for admin users.
Cohort Builder - a tool that enables users to build and manage dynamic patient cohorts (groups) of patients based on multiple clinical and demographic criteria.
Module Management - a learning frontend module based on the legacy OpenMRS Module management UI. The code in this repo is annotated with comments and can serve as a good starting point for new developers looking to understand how to build frontend modules.
Frontend RFC - a repository where architectural decisions affecting technologies and processes that apply to all new O3 distributions are first presented, argued, and finally agreed upon via consensus.
JSON Schemas - a repository that hosts standard JSON schemas (opens in a new tab) used in OpenMRS. These schemas are used to provide auto-completion and validation capabilities when editing routes registry files for O3 frontend modules and O3 form schemas.

Core

Core contains both typical frontend modules as well as packages that don't render UIs. Typical frontend modules include:

Login (opens in a new tab) - responsible for rendering the login page when a user first launches the application, and the location picker after a user logs in.
Devtools (opens in a new tab) - renders the import-map-overrides (opens in a new tab) UI which enables developers to override frontend modules at runtime, essentially replacing them with local versions. This mechanism allows developers to test their local changes to frontend modules against the most up-to-date production version of the application without needing to rebuild and redeploy the entire application.
Implementer Tools (opens in a new tab) - provides a UI for implementers and developers to tweak configuration properties dynamically at runtime and viewing administrative information about their frontend. It also provides an embedded JSON editor, which allows developers to edit configuration properties via code, a UI editor mode for viewing which extension slots exist in the application and their current configurations, a UI for toggling feature flags, a backend module viewer, and a frontend module viewer that shows detailed configuration and dependency information for each installed module.
Primary Navigation (opens in a new tab) - renders the top navigation menu in the application, featuring the compact Patient search widget, links to the Implementer tools menu, Registration page, User menu, and the App switcher.
Offline Tools (opens in a new tab) - responsible for rendering the widgets related to offline mode.

In addition to these UI-related packages, Core also includes the following non-UI packages:

Core Framework (opens in a new tab) - aggregates packages that make up the core O3 framework API (opens in a new tab), including shared API objects (such as the patient and visit objects), the breadcrumbs menu, the extension system, shared React utils, global state management tools, error handling, and the style guide, among other things. The functionality exported by these packages gets aggregated into an NPM JavaScript package called esm-framework (opens in a new tab) that gets reused by most frontend modules.
App Shell (opens in a new tab) - the app shell is the entrypoint for the application. It is responsible for loading and registering frontend modules in the import map, coordinating the application lifecycle, handling core routing and module loading mechanics, and more. Read the app shell guide for more information.
Tooling (opens in a new tab) - provides a unified command-line interface for various frontend development and deployment tasks. The CLI gets aggregated into an NPM package called openmrs (opens in a new tab). Developers can use the CLI to fire up Webpack dev servers for local development, assemble frontend modules for a distribution, build the application, and more.

Home

Contains the home (opens in a new tab) frontend module, which renders the landing page that users get to after successfully logging in. This page has a left nav menu with entries for appointments, patient lists, and service queue applications.

By default, you'll see an active visits widget and a widget for the appointments scheduled for that day in the UI. The configuration schema (opens in a new tab) for the home app allows developers and implementers to configure which URL to navigate the user to after they click on a search result following a patient search. By default, the user will get navigated to the patient chart. The side menu and home dashboard expose extension slots into which dashboards from the Patient Management repo plug into. These include dashboards for Appointments, Laboratory Patient Lists, Service Queues and Wards.

Template

A starter template (opens in a new tab) repository that is designed to be forked and used as template for new frontend modules. It will be most developers' first foray into O3. Most components in the template app are annotated with useful comments that serve as a guide for developers working on the application. Because the template app is in fact a template, you can generate your own frontend module by forking it and using it as a template.

Patient Chart

Contains various frontend modules that constitute widgets in a patient dashboard. These widgets include:

Allergies (opens in a new tab) - provides a tabular overview of the allergies recorded for a patient as well as a form for recording allergies.
Attachments (opens in a new tab) - shows a gallery of attachments uploaded for a patient as well as a file uploader UI for uploading new attachments via the file system or the user's camera. Users can upload images and PDF documents or images captured using their device's camera. They can also delete existing attachments.
Conditions (opens in a new tab) - provides a tabular overview of the conditions recorded for a patient as well as a form for recording new conditions and editing existing ones.
Forms (opens in a new tab) - provides a tabular overview of the clinical forms available for use in the system. Presently, the forms widget is configured to use forms built using the Angular Form Engine.
Generic patient widgets (opens in a new tab) - This is a proof-of-concept for a generic widget that can be added to the patient chart using configuration. It can be made to display any obs in either a tabular view or a chart view. It's intended as a pathway to creating reusable widgets across the application.
Immunizations (opens in a new tab) - provides a tabular overview of the immunizations recorded for a patient as well as a form for recording new immunizations. This application is no longer used in the reference application and its import map entry is omitted in the distro config.
Medications (opens in a new tab) - provides a tabular overview of the active and past medications recorded for a patient. It also provides a form for ordering new medications.
Notes (opens in a new tab) - provides a tabular overview of the visit notes recorded for a patient as well as a form for recording new visit notes.
Orders (opens in a new tab) - renders the Order Basket in the workspace that allows users to order new drug and test orders, modify existing ones, and more.
Patient Banner (opens in a new tab) - renders a banner that displays the patient's name, their avatar, gender, age, and identifiers. It also provides an expandable panel that shows their address, contact details, and relationships with other patients. The patient banner can also display custom tags to mark whether a patient has an active visit ongoing or whether they are deceased among other things.
Programs (opens in a new tab) - provides a tabular overview of the programs a patient is enrolled in as well as a form for enrolling the patient into new programs.
Tests (opens in a new tab) - provides functionality for ordering and viewing test results for a patient. These could include things like lab tests, radiology tests, and more.
Vitals (opens in a new tab) - provides tabular and chart-based overviews of the vitals and biometrics recorded for a patient as well as a form for recording vitals and biometrics. It also provides a vitals header that displays a summary of the most recently recorded vitals.

In addition to these widgets, two other microfrontends exist that encapsulate cross-cutting concerns. These are:

Common Lib (opens in a new tab) - a library of components and utilities shared across widgets in the patient chart. These include:
- Custom components for card headers, error and empty states, and pagination.
- Custom hooks for fetching orders, concept metadata, program enrollments, global properties, and more reusable logic.
Patient Chart (opens in a new tab) - provides the underlying framework on top of which all the individual widgets are run. It sets up the layout of the patient chart and handles routing between the chart summary and widget dashboards. It also sets up core extensions, the workspace, the left nav and side menus, visits functionality as well as offline mode.

The Patient Chart also includes packages that provide wrappers for both the Angular and React form engines:

Patient management

This monorepo includes the following frontend modules:

Active Visits (opens in a new tab) - provides a tabular overview of checked in patients for the current day.
Appointments (opens in a new tab) - provides capabilities to create, edit and manage patient appointments.
Service Queues (opens in a new tab) - provides capabilities to create, manage and view queues in a location.
Patient Search (opens in a new tab) - provides the ability to search for existing patients using simple and advanced search.
Patient Registration (opens in a new tab) - provides the ability to register new patients and verify them through configurable external patient registries.
Patient List (opens in a new tab) - provides a UI to create and manage patient lists.
Wards (opens in a new tab) - provides a UI for managing admissions to wards.

Laboratory app

The Laboratory app (opens in a new tab) provides a UI for managing laboratory requests and queues. It includes the following widgets:

Laboratory Header (opens in a new tab) - Displays the page header details, including the page name, icon, and other relevant information.
Laboratory Summary Tiles (opens in a new tab) - Provide numerical summaries of the laboratory tests, indicating the number of tests ordered, in progress, and completed.
Laboratory Orders Tabs (opens in a new tab) - Widgets (buttons) that allow toggling between the ordered, in-progress, and completed test results. These results are displayed in a tabular format within the overlay.
Overlay (opens in a new tab) - Displays test orders in a tabular view. The content can be toggled using the Laboratory Orders Tabs.

Angular Form Engine

The Angular Form Engine (opens in a new tab) is a form engine solution originally built by AMPATH. It leverages Angular's forms capabilities to build a fully-fledged form engine with capabilities such as field validation, injection of custom data sources, conditional rendering, historical expressions, and more. Forms built using the form engine get rendered in the Clinical Forms workspace in the patient chart. The patient chart provides a wrapper Form Entry (opens in a new tab) Angular micro frontend that consumes the form engine library and exposes its functionality via a Single SPA parcel. This allows the form engine to be consumed by the patient chart as a micro frontend. To learn more about the Angular Form Engine, check out its README (opens in a new tab) and technical roadmap (opens in a new tab). You can learn more about the Angular framework here (opens in a new tab).

React Form Engine

The React Form Engine (opens in a new tab) is a library that enables creating and rendering medical forms within O3. It provides a flexible, JSON-based form schema with built-in validation, conditional rendering, and multilingual support. O3 form schemas conform to the O3 standard JSON schema spec (opens in a new tab) which defines the structure and constraints of the form data. Learn more about the React Form Engine from the official docs (opens in a new tab). The O3 reference application (opens in a new tab) ships an embedded Form Builder (opens in a new tab) to make building forms easy.

Form Builder

The Form Builder (opens in a new tab) is a frontend module used to create OpenMRS form schemas, for use with the React Form Engine. It enables users to both create new schemas and edit existing ones. It provides an embedded code editor that facilitates writing JSON code, and a WYSIWYG schema builder interface where users can construct a schema interactively without writing code. Schemas built using the Form Builder can be persisted to the server, and optionally published, which makes them available to the frontend via the forms widget. The React Form Engine is used in the Form Builder to validate and test forms directly in the Form Builder UI.

Fast Data Entry

The Fast Data Entry app (opens in a new tab) is a frontend module that provides a natural workflow for entering many pre-recorded forms at a time. It is not meant for point-of-care workflows, but rather as a way to do retrospective data entry. It also can be used for the rapid input of forms for group sessions.

Medication Dispensing

The Medication Dispensing app (opens in a new tab) is a simple tool for tracking dispensed medications. It's designed to serve small sites that don't want to deal with implementing a whole external supply chain/ERP system. It simply tracks what needs to be dispensed and what has already been dispensed. The primary target users for this functionality are implementations and facilities that have an on-site pharmacy and don't charge the patient/customer for the services, and who want to dispense medications based on orders within the same OpenMRS instance. Billing and inventory are out of scope.

Distro Reference Application

This project holds the build configuration for the OpenMRS 3.0 reference application, found on https://dev3.openmrs.org (opens in a new tab) and https://o3.openmrs.org (opens in a new tab). This distribution consists of four docker images:

db - This is just the standard MariaDB image supplied to use as a database
backend - This image is the OpenMRS backend. It is built from the main Dockerfile included in the root of the project and based on the core OpenMRS Docker file. Additional contents for this image are drawn from the distro sub-directory which includes a full Initializer configuration for the reference application intended as a starting point.
frontend - This image is a simple nginx container that embeds the 3.x frontend, including the modules described in the file.
proxy - This image is an even simpler nginx reverse proxy that sits in front of the backend and frontend containers and provides a common interface to both. Basically, this helps mitigate CORS issues.

Admin Tools

Originally conceived as a way to provide a UI for the legacy admin tools, the Admin Tools (opens in a new tab) provide an interstitial page that links the user to non-core EMR apps such as the Cohort Builder, Form Builder, Legacy Admin UI, OCL Management page, and more. It also contains the OCL frontend module.

Cohort Builder

The Cohort Builder (opens in a new tab) leverages the Reporting Compatibility module to enable users to perform ad-hoc queries for patients with defined characteristics and combine multiple queries into more complex ones.

Module Management

The Module Management (opens in a new tab) frontend module is meant to serve as a learning resource for our coding conventions and best practices when building a microfrontend.

This app is based on the System Administration Manage Module management page from the legacy 2.x reference application. It allows users to manage modules. It lists all the installed modules and allows admin users to control modules using Start, Stop and Unload actions. Users can also view detailed information about the listed modules. This includes metadata such as the module author, version, required OpenMRS version, and more.

Frontend RFC

A repo (opens in a new tab) where the technologies and processes that apply to all new OpenMRS distributions are explained. The purpose of this repo is to:

Provide a way to enact change in the OpenMRS frontend.
Clarify what things we are aligned on across all of OpenMRS so that everything else can be decided by the individual modules and distributions.

The RFC process was successful in setting up the frontend architecture, and the merged pull requests form a great resource for anyone wishing to understand how we got to where we are today.

JSON schemas

A repo (opens in a new tab) that hosts standard JSON schemas used in OpenMRS. These schemas then get published via a web-accessible URL. For example, the standard routes schema (opens in a new tab) is used to provide auto-completion and validation capabilities when editing a routes.json file in your IDE.

Prerequisite knowledge Overview