# openmrs/openmrs-esm-core architecture

> Architecture diagram of the GitHub repository openmrs/openmrs-esm-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openmrs/openmrs-esm-core
- Repository: https://github.com/openmrs/openmrs-esm-core

## Overview

##### Project Type and Purpose
- This is a Yarn-workspaces monorepo (“openmrs-esm-core”) that provides the core frontend framework, tooling, and a set of React-based microfrontends (apps) for the OpenMRS 3 frontend.
- It’s structured as:
- Core “framework” libraries for configuration, state, routing, API, offline support, extension system, styleguide, etc.
- An “app shell” that boots the SPA, implements the plugin/extension model, service worker, import-map/dynamic loading via Webpack Module Federation.
- A set of standalone “frontend modules” (login, primary navigation, devtools, help menu, implementer tools, offline tools) that the shell loads at runtime.
- CLI tooling for building, developing, and releasing modules.

##### File-Structure Analysis
- Top-level:
- package.json, yarn workspaces, Turbo repo config
- /packages/tooling: CLI and webpack config generators
- /packages/shell/esm-app-shell: the host application shell with service-worker and dynamic remote loader
- /packages/framework/esm-*: ~15 shared libraries (API, config, context, dynamic-loading, error-handling, extensions, feature-flags, globals, navigation, offline, react-utils, routes, state, styleguide, translations, utils); all aggregated by @openmrs/esm-framework
- /packages/apps: React “microfrontends” (each with its own webpack config, routes.json, translations)
- e2e/: Playwright tests and Docker setups
- .github/workflows, CI, code-ql, bundle-size, e2e, docs

##### README Insights
- Enumerates the purpose of each package (API helpers, module config, AppContext, dynamic loading, error-handling, etc.).
- Describes the development flow: building all packages, running app-shell, developing apps against local core via yarn link/yalc, and test commands (unit via Turbo, E2E via Playwright).
- Emphasizes the plugin/extension system and Webpack Module Federation dynamic remotes.

1. Developer Tooling & CI/CD
– Turbo repo (yarn workspaces)
– CLI (`packages/tooling/openmrs`)
– GitHub Actions (build, verify, docs, e2e)
2. Monorepo Packages
– Framework Libraries (@openmrs/esm-api, esm-config, …, esm-utils)
– App Shell (@openmrs/esm-app-shell)
– Frontend Modules (@openmrs/esm-login-app, esm-primary-navigation-app, esm-devtools-app, …)
3. Runtime Environment (Browser)
– Service Worker (caching, offline sync)
– Import Map / Dynamic Remote Loader (Module Federation)
– React Context & State (esm-context, esm-state)
– Extension API (esm-extensions)
4. External Services
– OpenMRS Backend (FHIR REST API)
– Translation service or JSON files (@openmrs/esm-translations)
– Shell ↔ Framework libraries (shared code loaded at startup)
– Shell → Frontend Modules (dynamic import at runtime via import-map / module federation)
– Modules → esm-api → OpenMRS backend (HTTP/FHIR calls)
– Service Worker intercepts network requests (offline caching, sync)
– Modules & Shell ↔ esm-config (module and global configuration store)
– Modules & Shell ↔ esm-context & esm-state (global contextual state)
– Modules ↔ esm-extensions (publish and consume extension slots)
– Modules & Shell consume styleguide components (esm-styleguide) and translation libs (esm-translations)
c. Architectural Patterns & Principles:
– Monorepo + Yarn Workspaces + Turbo for dependency graph and caching
– Microfrontend plugin model via Webpack Module Federation dynamic remotes
– Publish-subscribe extension slots for loose coupling between modules
– Single SPA-style shell hosting independently developed React apps
– Service worker for offline support (esm-offline)
– Centralized context/provider pattern for global state and config
d. Key Technologies/Frameworks:
– Yarn Workspaces, TurboRepo
– TypeScript, React
– Webpack Module Federation (dynamic-loading)
– Playwright (E2E), Jest (unit)
– GitHub Actions, Bamboo Docker for e2e
– Service Worker (offline-sync)
– FHIR REST API (OpenMRS backend)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Tooling & CI
    subgraph "Tooling & CI"
        direction TB
        Turbo["Turbo Repo<br/>(yarn workspaces)"]:::tooling
        GitHubActions["GitHub Actions CI/CD"]:::tooling
        CLI["openmrs CLI Tool"]:::tooling
        WebpackGen["Webpack Config Generator"]:::tooling
    end

    %% Monorepo Packages
    subgraph "Monorepo Packages"
        direction TB
        subgraph "Framework Libraries"
            direction TB
            FrameworkAgg["@openmrs/esm-framework"]:::framework
            API["@openmrs/esm-api"]:::framework
            Config["@openmrs/esm-config"]:::framework
            Context["@openmrs/esm-context"]:::framework
            DynamicLoad["@openmrs/esm-dynamic-loading"]:::framework
            ErrorHandling["@openmrs/esm-error-handling"]:::framework
            Extensions["@openmrs/esm-extensions"]:::framework
            FeatureFlags["@openmrs/esm-feature-flags"]:::framework
            Globals["@openmrs/esm-globals"]:::framework
            Navigation["@openmrs/esm-navigation"]:::framework
            OfflineLib["@openmrs/esm-offline"]:::framework
            ReactUtils["@openmrs/esm-react-utils"]:::framework
            Routes["@openmrs/esm-routes"]:::framework
            State["@openmrs/esm-state"]:::framework
            Styleguide["@openmrs/esm-styleguide"]:::framework
            Translations["@openmrs/esm-translations"]:::framework
            Utils["@openmrs/esm-utils"]:::framework
        end

        subgraph "App Shell"
            direction TB
            Shell["@openmrs/esm-app-shell"]:::shell
            SW["Service Worker"]:::shell
            ImportMap["Import Map Loader"]:::shell
        end

        subgraph "Frontend Modules"
            direction TB
            Login["esm-login-app"]:::app
            PrimaryNav["esm-primary-navigation-app"]:::app
            DevTools["esm-devtools-app"]:::app
            HelpMenu["esm-help-menu-app"]:::app
            ImplTools["esm-implementer-tools-app"]:::app
            OfflineTools["esm-offline-tools-app"]:::app
        end
    end

    %% Runtime Environment (Browser)
    subgraph "Runtime (Browser)"
        direction TB
        SWBrowser["Service Worker"]:::runtime
        ImportLoader["Dynamic Remote Loader"]:::runtime
        ReactContext["React Context & State"]:::runtime
        ExtensionAPI["Extension API"]:::runtime
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Backend["OpenMRS FHIR REST API"]:::external
        TranslationSvc["Translation JSON Files"]:::external
    end

    %% Relationships
    Shell -->|"uses"| FrameworkAgg
    Shell -->|"bootstraps"| ImportMap
    Shell -->|"registers"| SW
    ImportMap -->|"loads at runtime"| Login
    ImportMap -->|"loads at runtime"| PrimaryNav
    ImportMap -->|"loads at runtime"| DevTools
    ImportMap -->|"loads at runtime"| HelpMenu
    ImportMap -->|"loads at runtime"| ImplTools
    ImportMap -->|"loads at runtime"| OfflineTools

    Login -->|"calls API"| API
    PrimaryNav -->|"calls API"| API
    DevTools -->|"calls API"| API
    HelpMenu -->|"calls API"| API
    ImplTools -->|"calls API"| API
    OfflineTools -->|"calls API"| API

    API -->|"HTTP/FHIR calls"| Backend
    SWBrowser -->|"intercepts/cache"| Backend

    Login -->|"config/state/ext"| Config
    Shell -->|"config/state/ext"| Config
    Login -->|"context/state"| Context
    Shell -->|"context/state"| Context
    Login -->|"extensions"| Extensions
    Shell -->|"extensions"| Extensions

    Login -->|"style/translation"| Styleguide
    Shell -->|"style/translation"| Styleguide
    Login -->|"style/translation"| Translations
    Shell -->|"style/translation"| Translations

    Turbo -->|"manages workspaces"| FrameworkAgg
    Turbo -->|"manages workspaces"| Shell
    Turbo -->|"manages workspaces"| Login

    GitHubActions -->|"CI/CD pipelines"| Turbo
    CLI -->|"scaffold/build/release"| FrameworkAgg
    CLI -->|"scaffold/build/release"| Shell
    CLI -->|"scaffold/build/release"| Login

    WebpackGen -->|"generates configs"| Shell
    WebpackGen -->|"generates configs"| Login

    %% Click Events
    click Turbo "https://github.com/openmrs/openmrs-esm-core/blob/main/turbo.json"
    click GitHubActions "https://github.com/openmrs/openmrs-esm-core/tree/main/.github/workflows/"
    click CLI "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/tooling/openmrs/src/cli.ts"
    click WebpackGen "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/tooling/webpack-config/src/index.ts"
    click Shell "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/shell/esm-app-shell/src/index.ts"
    click SW "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/shell/esm-app-shell/src/service-worker/index.ts"
    click ImportMap "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/shell/esm-app-shell/src/run.ts"
    click Shell "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/shell/esm-app-shell/webpack.config.js"
    click FrameworkAgg "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-framework/src/index.ts"
    click FrameworkAgg "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-framework/package.json"
    click API "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/index.ts"
    click Config "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-config/src/module-config/module-config.ts"
    click Context "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-context/src/context.ts"
    click DynamicLoad "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-dynamic-loading/src/dynamic-loading.ts"
    click ErrorHandling "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-error-handling/src/index.ts"
    click Extensions "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-extensions/src/extensions.ts"
    click FeatureFlags "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-feature-flags/src/feature-flags.ts"
    click Globals "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-globals/src/events.ts"
    click Navigation "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-navigation/src/navigation/navigate.ts"
    click OfflineLib "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/service-worker.ts"
    click OfflineLib "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-offline/src/offline-db.ts"
    click ReactUtils "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-react-utils/src/ExtensionSlot.tsx"
    click Routes "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-routes/src/routes.ts"
    click State "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-state/src/state.ts"
    click Styleguide "https://github.com/openmrs/openmrs-esm-core/tree/main/packages/framework/esm-styleguide/src/components"
    click Translations "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-translations/src/translations.ts"
    click Utils "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-utils/src/index.ts"
    click Login "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-login-app/src/index.ts"
    click PrimaryNav "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-primary-navigation-app/src/index.ts"
    click DevTools "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-devtools-app/src/index.ts"
    click HelpMenu "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-help-menu-app/src/index.ts"
    click ImplTools "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-implementer-tools-app/src/index.ts"
    click OfflineTools "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/apps/esm-offline-tools-app/src/index.ts"
    click SWBrowser "https://github.com/openmrs/openmrs-esm-core/blob/main/packages/shell/esm-app-shell/src/service-worker/import-map-utils.ts"

    %% Styles
    classDef tooling fill:#FFEB3B,stroke:#333,stroke-width:1px
    classDef framework fill:#2196F3,stroke:#333,stroke-width:1px
    classDef shell fill:#FF9800,stroke:#333,stroke-width:1px
    classDef app fill:#4CAF50,stroke:#333,stroke-width:1px
    classDef runtime fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#9E9E9E,stroke:#333,stroke-width:1px
```
