GITBOOK-52: Getting started improvements and architecture

documentation/README (1).md

@@ -9,7 +9,7 @@ description: What you need to start using OpenHIM Platform.
 Before getting started with OpenHIM Platform you will need to have Instant OpenHIE tool installed and functional. [Please follow this guide here](https://app.gitbook.com/s/TwrbQZir3ZdvejunAFia/getting-started/quick-start).
 
 {% hint style="info" %}
-* If you're a _**Windows**_** user and are** using WSL2 to be able to run the platform: you should limit the amount of RAM/CPU that will be used by WSL, for more details please check the following link: [Limiting memory usage in WSL2](https://www.aleksandrhovhannisyan.com/blog/limiting-memory-usage-in-wsl-2/).
+* If you're a _**Windows**_** user** and are using WSL2 to be able to run the platform: you should limit the amount of RAM/CPU that will be used by WSL, for more details please check the following link: [Limiting memory usage in WSL2](https://www.aleksandrhovhannisyan.com/blog/limiting-memory-usage-in-wsl-2/).
 {% endhint %}
 
 ## Quick Start
@@ -48,6 +48,14 @@ instant package destroy --name interoperability-layer-openhim --name message-bus
 
 Next, you might want to browse the [recipes](recipes/) available in OpenHIM Platform. Each recipe bundles a set of packages and configuration to setup an HIE for a particular purpose.
 
+For example, this command allows the most [comprehensive recipe](recipes/central-data-repository-with-data-warehousing.md) to be deployed with one command:
+
+```bash
+wget https://github.com/jembi/platform/releases/latest/download/cdr-dw.env && \
+wget https://github.com/jembi/platform/releases/latest/download/config.yaml && \
+instant package init -p cdr-dw --dev
+```
+
 Alternatively you can also browse the individual set of [packages](packages/) that OpenHIM Platform offers. Each package's documentation lists the environment variables used to configure them.
 
 For more information on how to start stop and destroy packages using the command line, see the [Instant OpenHIE 2 CLI docs](https://jembi.gitbook.io/instant-v2/cli).

documentation/SUMMARY.md

@@ -55,6 +55,7 @@
 * [Provisioning remote servers](provisioning-up-remote-servers/README.md)
   * [Ansible](provisioning-up-remote-servers/ansible.md)
   * [Terraform](provisioning-up-remote-servers/terraform.md)
+* [Architecture](architecture.md)
 * [Resource Allocations](resource-allocations.md)
 * [Development](development/README.md)
   * [Config Importing](development/config-importing.md)

documentation/architecture.md

@@ -0,0 +1,78 @@
+# Architecture
+
+OpenHIM Platform builds on Instant OpenHIE v2 as the deployment tool which provides the concepts of packages, profiles and the CLI utility that powers the ability to launch OpenHIM Platform packages and recipes. Please read the the [Instant OpenHIE Architecture](https://app.gitbook.com/s/TwrbQZir3ZdvejunAFia/concepts/architecture) for some foundational concepts about how packages are run.
+
+On this page we will discuss the architecture of OpenHIM Platform which is a set of packages and recipes that use those packages that create a fully functional HIE from scratch.
+
+## Modularity and flexibility
+
+OpenHIM Platform packages are able to stood up individually so that as much or as little of the package set that is necessary from an implementer can be utilised. However, OpenHIM Platform is designed with some key features that will only be available if a number of packages are setup together. Recipes group those sets of packages together so that it is easier to deploy all at once.
+
+## Component Architecture
+
+<figure><img src=".gitbook/assets/Jembi Platform - Component architecture - OpenHIM Platform.png" alt=""><figcaption><p>OpenHIM Platform Architecture</p></figcaption></figure>
+
+The architecture is split into 3 distinct parts:
+
+* Client: This section represents client systems that might want to interact with the HIE, they have a particular set of interactions that the core OpenHIM Platform packages enable support for.
+* Platform core: These are a set of packages with instantiate applications and mediators that enable the core client workflows to be executed. This includes accepting FHIR bundles, splitting patient demographic data into an MPI and clinical data into a FHIR data store as well as managing the linkage from patient demographics to clinical data in a way that isn't affected by potencial linking and unlinking of patient records via the MPI. More on this later.
+* Platform pluggable services: by design, once the core packages have processed FHIR request, they are pushed into Kafka for secondary use by other systems. Typically this includes data analytics pipelines and a default implementation is included in OpenHIM Platform, however, the data can be read an used for any purpose i.e. syncing to another HIE or sent to a national data warehouse.
+
+## Platform core wokflow
+
+This is how the core packages interact to split the data into two separate stores, a clinical data store and a patient demographics store.
+
+```mermaid
+sequenceDiagram
+  participant Health Facility
+  participant OpenHIM
+  participant OCL Mediator
+  participant MPI Mediator
+  participant FHIR Mapping Facade
+  participant JeMPI
+  participant HAPI FHIR
+
+  Health Facility->>OpenHIM: FHIR Bundle (Patient)
+  activate OpenHIM
+  OpenHIM->>OCL Mediator: FHIR Bundle (Patient)
+  activate OCL Mediator
+  OCL Mediator->>OCL Mediator: Translate codes
+  OCL Mediator->>MPI Mediator: FHIR Bundle (Patient)
+  deactivate OCL Mediator
+  activate MPI Mediator
+  MPI Mediator->>MPI Mediator: Extract Patient Resource
+  MPI Mediator->>FHIR Mapping Facade: POST Patient (FHIR format)
+  activate FHIR Mapping Facade
+  FHIR Mapping Facade->>JeMPI: Submit Patient (JeMPI API format)
+  activate JeMPI
+  JeMPI->>JeMPI: Create a new interaction, if matches to existing source id auto link else run linking
+  JeMPI->>FHIR Mapping Facade: Interaction ID
+  deactivate JeMPI
+  FHIR Mapping Facade->>MPI Mediator: Interaction ID
+  deactivate FHIR Mapping Facade
+  MPI Mediator->>HAPI FHIR: Fetch stub patient resource
+  activate HAPI FHIR
+  HAPI FHIR->>MPI Mediator: Return patient
+  deactivate HAPI FHIR
+  alt If NO patient exists
+  MPI Mediator->>MPI Mediator: Modify bundle (Strip Patient Demographics, add JeMPI ref with Interaction ID to Patient.link, retain original Patient.id (uuid))
+  else If patient exists
+  MPI Mediator->>MPI Mediator: Modify bundle (Replace patient resource in bundle with HAPI FHIR stub retaining Patient.link, add additional JeMPI ref with Interaction ID to Patient.link)
+  end
+  MPI Mediator->>HAPI FHIR: Modifed Bundle
+  activate HAPI FHIR
+  HAPI FHIR->>MPI Mediator: Response
+  deactivate HAPI FHIR
+  MPI Mediator->>OpenHIM: Response
+  deactivate MPI Mediator
+  activate OpenHIM
+  OpenHIM->>Health Facility: Response
+  deactivate OpenHIM
+
+```
+
+The reason for doing this are as follows:
+
+* With the clinical and patient demographic data split it is easier to link and unlink patient identities as no data in the clinical store needs to change. They continue to reference the source patient ID and whatever happen to that patient, whether they are grouped together with other identities in the MPI or not, that ID remains constant.
+* The split of data is a useful security feature as the clinical data and the Personal Identifiable Information (PII) or stored separately. An attacker would need to compromise both to relate clinical information to a particular person.
+* It prevent duplicate information being stored in multiple places, a clear source of truth for each type of information is identified. This prevent data from getting out of sync when it is stored in multiple places.

documentation/community.md

@@ -2,4 +2,6 @@
 
 We encourage any contributions and suggestions! If you would like to get involved, please visit us on [Github](https://github.com/jembi/platform/). Feel free to submit an issue or to create a PR to see your features included in the project.
 
-We look forward to growing the set of capabilities within OpenHIM Platofrm together!
+If you'd like to chat about OpenHIM Platform please join our [community on Discord](https://discord.gg/R4XwXyZbwk).
+
+We look forward to growing the set of capabilities within OpenHIM Platform together!

documentation/development/README.md

@@ -3,6 +3,6 @@
 ## Adding Packages
 
 * The Go Cli runs all services from the `jembi/platform` docker image. When adding new packages or updating existing packages to Platform you will need to build/update your local `jembi/platform` image. [How to build the image](<../README (1).md>).
-* As you add new packages to the platform remember to list them in the `config.yml` file - otherwise the added package will not be detected by the [platform-cli tool](http://127.0.0.1:5000/o/lTiMw1wKTVQEjepxV4ou/s/TwrbQZir3ZdvejunAFia/).
+* As you add new packages to the platform remember to list them in the `config.yml` file - otherwise the added package will not be detected by the [platform-cli tool](https://app.gitbook.com/o/lTiMw1wKTVQEjepxV4ou/s/TwrbQZir3ZdvejunAFia/).
 
 ##

documentation/provisioning-up-remote-servers/README.md

@@ -4,9 +4,17 @@ description: Infrastructure tools for the OpenHIM Platform
 
 # Provisioning remote servers
 
-As part of the OpenHIM Platform Github repository we also provide scripts to easily setup new servers. The Terraform script are able to instanciate server in AWS and the Ansible script are able to configure those server to be ready to accept OpenHIM Platform packages.
+Deploying from your local environment to a remote server or cluster is easy. All you have to do is ensure the remote servers are setup as a Docker Swarm cluster. Then, from your local environment you may target a remote environment by using the \`DOCKER\_HOST\` env var. e.g.
 
-## Ansible
+```
+DOCKER_HOST=ssh://ubuntu@<ip> instant package init ...
+```
+
+## Setting up new servers
+
+In addition, as part of the OpenHIM Platform Github repository we also provide scripts to easily setup new servers. The Terraform script are able to instantiate server in AWS and the Ansible script are able to configure those server to be ready to accept OpenHIM Platform packages.
+
+### Ansible
 
 See [here](https://github.com/jembi/platform/tree/main/infrastructure/ansible).
 
@@ -19,6 +27,6 @@ All the passwords are saved securely using Keepass.
 
 In the inventories, there is different environment configuration (development, production and staging) that contains: users and their ssh keys list, docker credentials and definition of the hosts.
 
-## Terraform
+### Terraform
 
 Is used to create and set AWS servers. See [here](https://github.com/jembi/platform/tree/main/infrastructure/terraform).

documentation/recipes/central-data-repository-no-reporting.md

@@ -14,7 +14,7 @@ This recipe sets up an HIE that does the following:
 To launch this package in dev mode copy and paste this into your terminal in a new folder (ensure you have the [instant CLI installed](https://jembi.gitbook.io/instant-v2/getting-started/quick-start)):
 
 ```bash
-wget https://raw.githubusercontent.com/jembi/platform/main/cdr.env && \
-wget https://raw.githubusercontent.com/jembi/platform/main/config.yaml && \
+wget https://github.com/jembi/platform/releases/latest/download/cdr.env && \
+wget https://github.com/jembi/platform/releases/latest/download/config.yaml && \
 instant package init -p cdr --dev
 ```

documentation/recipes/central-data-repository-with-data-warehousing.md

@@ -18,8 +18,8 @@ This recipe sets up an HIE that does the following:
 To launch this package in dev mode copy and paste this into your terminal in a new folder (ensure you have the [instant CLI installed](https://jembi.gitbook.io/instant-v2/getting-started/quick-start)):
 
 ```bash
-wget https://raw.githubusercontent.com/jembi/platform/main/cdr-dw.env && \
-wget https://raw.githubusercontent.com/jembi/platform/main/config.yaml && \
+wget https://github.com/jembi/platform/releases/latest/download/cdr-dw.env && \
+wget https://github.com/jembi/platform/releases/latest/download/config.yaml && \
 instant package init -p cdr-dw --dev
 ```
 

documentation/recipes/master-patient-index.md

@@ -9,7 +9,7 @@ This recipe sets up an HIE that deploys JeMPI behind the OpenHIM with a mapping
 To launch this package in dev mode copy and paste this into your terminal in a new folder (ensure you have the [instant CLI installed](https://jembi.gitbook.io/instant-v2/getting-started/quick-start)):
 
 ```bash
-wget https://raw.githubusercontent.com/jembi/platform/main/mpi.env && \
-wget https://raw.githubusercontent.com/jembi/platform/main/config.yaml && \
+wget https://github.com/jembi/platform/releases/latest/download/mpi.env && \
+wget https://github.com/jembi/platform/releases/latest/download/config.yaml && \
 instant package init -p mpi --dev
 ```