Key repositories

Repositories you should know in O3 include:

Core - the core packages of the O3 frontend that handle cross-cutting concerns such as loading frontend modules, configuration, internationalization, rendering the UI, routing, error handling, styling, and so forth.
Home - renders the UI for the landing page after the user logs in.
Template - a seed app that is usually most developers' first introduction to O3.
Patient chart - the patient dashboard, including widgets for concerns such as vitals and biometrics, test results, forms, and allergies. This is where you'll find your run-of-the-mill EMR features.
Patient management - contains frontend modules that handle patient-related concerns such as search, patient lists, registration, service queues, and appointments.
Angular form engine - a form engine tool, originally built by AMPATH. Leverages Angular's powerful support for forms to build a fully-fledged form engine with capabilities such as field validation, injection of custom data sources, conditional rendering, historical expressions, and more.
React form engine (WIP) - originally built by the UCSF-IGHS team, this new form engine is built in React and leverages the powerful formik library to provide a robust solution. Work is ongoing to get this engine to a stable version that has feature parity with the Angular form engine.
Form builder - form builder tool baked into O3. 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 via the forms widget.
Fast data entry app - built by Mekom Solutions, enables retrospective data entry.
Dispensing app - built collaboratively by PIH and UCSF-IGHS, the medication dispensing app enables implementers to track medication dispensed within OpenMRS.
O3 distro refapp config - holds the build configuration for the O3 reference application (opens in a new tab).
Admin tools - provides an interstitial page that links users to various frontend modules that aren't part of the core EMR such as the form builder, the cohort builder, and the legacy admin page.
Cohort builder - enables the user to perform ad-hoc queries for patients with defined characteristics, and combines multiple queries into more complex ones.
Module management - a learning application based on the legacy module management interfaces. The code in this repo is annotated with comments and can serve as a good starting point for new developers.
Frontend RFC - 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 - where standard JSON schemas used in OpenMRS are hosted.

Overview

Our major repositories are set up as monorepos. A monorepo is a collection of many different applications and packages in a single codebase. Typically, these monorepos are set up using lerna and yarn workspaces (opens in a new tab). The monorepo will have one root-level package.json manifest file which contains all the root-level scripts in addition to the package.json files of all of its constituent packages.

Core

Most of the time, you'll likely be working with either the patient chart or patient management repositories. However, you might find yourself occasionally needing to delve into core. The packages available in core include:

Login - responsible for rendering the loading page, the login page, and the location picker.
Devtools (opens in a new tab) - provides a UI that enables developers to use the import map overrides (opens in a new tab) library in O3. This 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.
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. Once tested and validated, these configuration properties can then be persisted to a distro's configuration.
Primary navigation (opens in a new tab) - renders the top navigation menu in the application, featuring the app icon, patient search, the implementer tools menu, the registration page, the app menu, and the user menu.
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 packages:

Framework (opens in a new tab) - contains packages that make up the core O3 framework library, 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 package called esm-framework (opens in a new tab) that gets reused by most frontend modules.
Shell (opens in a new tab) - the app shell, which forms the base of the application, and is tasked with doing a whole host of things, from registering frontend modules in the import map to starting the application.
Tooling (opens in a new tab) - the openmrs CLI (opens in a new tab) which is the one-stop CLI for O3 that's useful for firing dev servers, assembling frontend modules for distribution, 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 the appointments and service queues apps (originally developed by Palladium) and patient lists.

Template

Contains the seed starter app. The template app (opens in a new tab) 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.
Appointments (opens in a new tab) - provides a tabular overview of the appointments recorded for a patient as well as a form for recording appointments.
Attachments (opens in a new tab) - shows a gallery of attachments uploaded for the patient as well as a file uploader for uploading new attachments via the file system or the user's camera.
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 (opens in a new tab).
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 the ability to modify, reorder or discontinue medications as well as an order basket 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.
Patient banner (opens in a new tab) - provides 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.
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.
Test results (opens in a new tab) - provides tabular and chart-based overviews of the test results available for a patient.
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 managing workspaces, concept metadata, and pagination.
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:

Angular form engine (opens in a new tab) (an Angular application)
React form engine (opens in a new tab)

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.

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

Originally built by the UCSF-IGHS team, the OHRI form engine (opens in a new tab) is built in React and leverages the powerful formik library to provide a robust solution. JSON schemas built using this engine conform to the OpenMRS 3.0 form schema specification (opens in a new tab). Work is ongoing to get this engine to a stable version that has feature parity with the Angular form engine

Form builder

The Form Builder (opens in a new tab) is a frontend module used to create OpenMRS form schemas. It enables users to both create new schemas and edit existing ones. It provides an embedded code editor that accepts JSON code and an interactive editor 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. Schemas built in the form builder get rendered via the React form engine, which allows users to validate and test their forms straight from the form builder UI.

Fast data entry

The Fast Data Entry App (opens in a new tab) is a frontend module that allows for a natural workflow when 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 allows the rapid input of forms for group sessions enabling recording information about a group session or for session participants.

Medication dispensing

The medication dispensing app (opens in a new tab) is a simple tool that enables tracking dispensed medications. It's designed to serve small sites that don't want to deal with implementing a whole other external supply chain/ERP system. These sites typically only care about tracking what needs to be dispensed vs 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, who want to dispense medications based on orders within the same OpenMRS instance. Billing and inventory are out of scope.

Distro refapp config

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 micro frontend.

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 Visual Studio Code.

Prerequisite knowledge Overview