# bahmni/openmrs-distro-bahmni architecture

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

- Interactive diagram: https://gitdiagram.com/bahmni/openmrs-distro-bahmni
- Repository: https://github.com/bahmni/openmrs-distro-bahmni

## Overview

##### Project type and purpose
- This is a *distribution builder* for OpenMRS (a Java-based EMR platform) tailored to the Bahmni distribution.
- It assembles OpenMRS core + Bahmni configuration module + FHIR CDSS and Terminology modules into deployable artifacts.
- It provides Docker images and Helm charts for containerized deployment.

##### File structure
- Top-level: Maven wrapper (mvnw, pom.xml), distro (assembly), openmrs-module-bahmni.configuration (custom module), package (docker + helm), GitHub workflows for CI/CD.
- distro/src/main/assembly: defines Maven Assembly descriptor to bundle core + modules.
- openmrs-module-bahmni.configuration: Java code + resource files (apps JSON, config.xml, message bundles) – this is the main customization module.
- package/docker/openmrs: Dockerfile, shell startup scripts, property templates.
- package/helm/openmrs: Helm Chart (Chart.yaml, values.yaml) + Kubernetes templates (Deployments, Services, ConfigMaps, Secrets, Volumes, HPA).

##### README for additional insights
- Build command: `./mvnw clean deploy` publishes artifacts into the Bahmni Maven repo.
- Bundles FHIR CDSS and Terminology modules.

a. Main components
1. *Build & Packaging*
- Maven Build Server (CI via GitHub Actions)
- Maven Assembly Plugin (produces distro ZIPs/JARs)
2. *Artifact Repository*
- bahmnirepo.thoughtworks.com (Maven repo)
3. *Container Image*
- Dockerfile builds openmrs + modules
- startup scripts inject configuration
4. *Deployment & Orchestration*
- Kubernetes Cluster
- Helm Chart for OpenMRS
5. *Runtime Components*
- OpenMRS Platform (Spring web app)
- Bahmni Configuration Module (Activator.java + resources)
- FHIR CDSS Module
- FHIR Terminology Service Module
- Database (MySQL / Postgres)
- Persistent Volumes (for uploads, images, forms)
- ConfigMaps & Secrets (properties, credentials)
6. *External Services*
- FHIR Terminology Server (SNOMED CT service)
- CDSS Rule Engine (if hosted externally)

b. Relationships & Interactions
- CI pushes Maven artifacts → Maven repo
- Docker build fetches artifacts from repo → produces image → pushes to Docker registry
- Helm install pulls image → creates Kubernetes Deployment
- Container at startup uses `bahmni_startup.sh` + ConfigMap/Secret → writes `openmrs-runtime.properties` → launches OpenMRS
- OpenMRS loads Bahmni configuration module + FHIR modules on startup
- OpenMRS connects to the relational DB (persistent volume claim)
- OpenMRS exposes REST APIs (FHIR endpoints); may call out to external CDSS/Terminology services
- Kubernetes manages scaling (HPA), service endpoints, volume mounts, and secrets injection

c. Architectural patterns & design principles
- Plugin modularity (OpenMRS modules loaded via Activator)
- Build ↔ Repository ↔ Container ↔ Orchestration pipeline
- Infrastructure-as-code (Helm charts, Dockerfiles)
- Separation of concerns: build vs package vs deploy vs runtime

d. Key technologies/frameworks
- Java, Spring, Maven
- OpenMRS module framework
- Maven Assembly Plugin
- Docker, Bash shell scripts
- Kubernetes, Helm
- GitHub Actions for CI/CD
- FHIR (CDSS, Terminology)

##### Essential details to capture
- Assembly descriptor’s role in bundling modules
- openmrs-module-bahmni.configuration as the customization entry point
- Use of ConfigMap templates in Helm for `openmrs-runtime.properties` and other `.template` files
- Volume mounts for persistent data
- Optional scaling via HPA

– how source code flows from GitHub → Maven → Docker → Kubernetes
– how the OpenMRS server is composed at runtime (core, Bahmni config module, FHIR modules)
– how infrastructure elements (DB, volumes, config, secrets, external FHIR services) connect together
– which technologies and frameworks play each role.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build/CI Layer
    subgraph "Build & CI" 
        style BuildCI fill:#cce5ff,stroke:#3399ff
        BuildCI["Maven Build Server<br/>(GitHub Actions)"]:::build
        BuildConfig["Top-Level Build Config<br/>(mvnw, pom.xml)"]:::build
        Assembly["Maven Assembly Plugin<br/>(assembly.xml)"]:::build
    end

    %% Packaging Layer
    subgraph "Packaging" 
        style Packaging fill:#ffe5cc,stroke:#ff9933
        DockerBuild["Docker Image Context<br/>(Dockerfile)"]:::package
        StartupScripts["Docker Startup Scripts & Templates"]:::package
    end

    %% Deployment & Infra Layer
    subgraph "Deployment & Orchestration"
        style Deploy fill:#e6ffe6,stroke:#33cc33
        ArtifactRepo["Maven Artifact Repository"]:::deploy
        DockerRegistry["Docker Registry"]:::deploy
        HelmChart["Helm Chart<br/>(Chart.yaml, values.yaml)"]:::deploy
        K8sTemplates["Kubernetes Templates<br/>(Deployment, Service, ConfigMap, Secrets, HPA, Volumes)"]:::deploy
        K8sCluster["Kubernetes Cluster"]:::deploy
    end

    %% Runtime Layer
    subgraph "Runtime Components"
        style Runtime fill:#f2e6ff,stroke:#9933ff
        Container["OpenMRS Container"]:::runtime
        subgraph "Application Modules"
            style Modules fill:#f9e6ff,stroke:#cc99ff
            Core["OpenMRS Platform"]:::runtime
            BahmniModule["Bahmni Configuration Module<br/>(Activator.java)"]:::runtime
            BahmniResources["Bahmni Config Resources"]:::runtime
            FHIRCDSS["FHIR CDSS Module"]:::runtime
            FHIRTerm["FHIR Terminology Module"]:::runtime
        end
        DB["Relational DB<br/>(MySQL/Postgres)"]:::runtime
        PV["Persistent Volumes"]:::runtime
        Configs["ConfigMaps & Secrets"]:::runtime
        ExternalFHIR["External FHIR Services"]:::external
    end

    %% Connections
    BuildCI -->|"publishes artifacts"| ArtifactRepo
    BuildCI --> Assembly
    BuildCI --> BuildConfig
    Assembly --> ArtifactRepo
    BuildConfig --> Assembly

    ArtifactRepo -->|"fetched by"| DockerBuild
    DockerBuild --> DockerRegistry
    StartupScripts --> DockerBuild

    DockerRegistry --> HelmChart
    HelmChart --> K8sCluster
    K8sTemplates --> K8sCluster

    K8sCluster --> Container
    Container --> Core
    Container --> BahmniModule
    Container --> BahmniResources
    Container --> FHIRCDSS
    Container --> FHIRTerm
    Container --> DB
    Container --> PV
    Container --> Configs
    Container --> ExternalFHIR

    %% Click Events
    click BuildCI "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/.github/workflows/build_publish_openmrs.yml"
    click BuildCI "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/.github/workflows/validate_pr.yml"
    click Assembly "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/distro/src/main/assembly/assembly.xml"
    click BahmniModule "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/openmrs-module-bahmni.configuration/src/main/java/org/openmrs/distro/bahmni/Activator.java"
    click BahmniResources "https://github.com/bahmni/openmrs-distro-bahmni/tree/master/openmrs-module-bahmni.configuration/src/main/resources"
    click DockerBuild "https://github.com/bahmni/openmrs-distro-bahmni/tree/master/package/docker/openmrs/Dockerfile"
    click StartupScripts "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/docker/openmrs/bahmni_startup.sh"
    click StartupScripts "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/docker/openmrs/config.yml"
    click StartupScripts "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/docker/openmrs/templates/*.template"
    click StartupScripts "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/docker/openmrs/update_elis_host_port.sh"
    click HelmChart "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/Chart.yaml"
    click HelmChart "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/values.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/deployment.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/service.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/configMap.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/secrets.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/hpa.yaml"
    click K8sTemplates "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/package/helm/openmrs/templates/volumes/deployment.yaml"
    click BuildConfig "https://github.com/bahmni/openmrs-distro-bahmni/tree/master/mvnw"
    click BuildConfig "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/mvnw.cmd"
    click BuildConfig "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/pom.xml"
    click BuildConfig "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/.mvn/wrapper/maven-wrapper.properties"
    click Assembly "https://github.com/bahmni/openmrs-distro-bahmni/blob/master/distro/pom.xml"

    %% Classes
    classDef build fill:#cce5ff,stroke:#3399ff,color:#000
    classDef package fill:#ffe5cc,stroke:#ff9933,color:#000
    classDef deploy fill:#e6ffe6,stroke:#33cc33,color:#000
    classDef runtime fill:#f2e6ff,stroke:#9933ff,color:#000
    classDef external fill:#f0f0f0,stroke:#888888,color:#000,stroke-dasharray: 5 5
```
