From 88b2621147e005ba9bd387d9b4e1ba95774d87d0 Mon Sep 17 00:00:00 2001 From: Gareth Bowen Date: Thu, 24 Feb 2022 07:18:33 +1300 Subject: [PATCH] Document offline first --- content/en/apps/_index.md | 4 +- content/en/apps/guides/database/_index.md | 2 +- content/en/apps/guides/hosting/offline.md | 24 +++--- content/en/apps/tutorials/local-setup.md | 12 +-- content/en/core/_index.md | 2 +- content/en/core/overview/architecture.md | 18 ++--- .../core/overview/data-flows-for-analytics.md | 6 +- content/en/core/overview/offline-first.md | 77 +++++++++++++++++++ content/en/why-the-cht.md | 22 +++--- 9 files changed, 122 insertions(+), 45 deletions(-) create mode 100644 content/en/core/overview/offline-first.md diff --git a/content/en/apps/_index.md b/content/en/apps/_index.md index 065fc88ae..4765f44bc 100644 --- a/content/en/apps/_index.md +++ b/content/en/apps/_index.md @@ -11,7 +11,7 @@ description: > This section provides an introduction to CHT Applications, provides some sample CHT Applications, and provides guides and reference materials for those wanting to build a CHT Application or deploy an existing one. {{% /pageinfo %}} -Community Health Toolkit (CHT) Applications are digital health tools built using the [CHT Core Framework]({{< ref "core" >}}). The Core Framework provides a foundation on which custom CHT Applications are built. Since all CHT Applications share the same foundation, they also share capabilities and attributes. For example, all CHT Applications share a similar user-interface and share the same look-and-feel. All CHT Applications can be built to scale, can run across a variety of devices, support offline-first experiences, and support most languages. These baseline capabilities are foundational across all CHT Applications. Read more about this in [Why the CHT?]({{< ref "why-the-cht" >}}). +Community Health Toolkit (CHT) Applications are digital health tools built using the [CHT Core Framework]({{< ref "core" >}}). The Core Framework provides a foundation on which custom CHT Applications are built. Since all CHT Applications share the same foundation, they also share capabilities and attributes. For example, all CHT Applications share a similar user-interface and share the same look-and-feel. All CHT Applications can be built to scale, can run across a variety of devices, support [Offline-First]({{< ref "core/overview/offline-first" >}}) experiences, and support most languages. These baseline capabilities are foundational across all CHT Applications. Read more about this in [Why the CHT?]({{< ref "why-the-cht" >}}). To create a digital health tool using the Community Health Toolkit, you'll need to build a CHT Application or re-use an existing CHT Application. @@ -19,7 +19,7 @@ CHT Applications have been built to support a range of health interventions incl ## What skills are required -Building a CHT Application or altering an existing app is a technical undertaking requiring a technical skillset. +Building a CHT Application or altering an existing app is a technical undertaking requiring a technical skillset. ### To Build an App diff --git a/content/en/apps/guides/database/_index.md b/content/en/apps/guides/database/_index.md index f5814741f..914b2b4ba 100644 --- a/content/en/apps/guides/database/_index.md +++ b/content/en/apps/guides/database/_index.md @@ -55,7 +55,7 @@ This is the standard CouchDB database used to configure user authentication and ## PouchDB -Used to store documents on the client device to allow for offline-first access. Bidirectional replication is done on the "medic" and "medic-user-{username}-meta" databases. The "medic" database is only partially replicated so the user stores only a subset of the entire CouchDB database for performance and security reasons. +Used to store documents on the client device to allow for [Offline-First]({{< ref "core/overview/offline-first" >}}) access. Bidirectional replication is done on the "medic" and "medic-user-{username}-meta" databases. The "medic" database is only partially replicated so the user stores only a subset of the entire CouchDB database for performance and security reasons. {{< see-also page="apps/guides/performance/replication" >}} diff --git a/content/en/apps/guides/hosting/offline.md b/content/en/apps/guides/hosting/offline.md index bd970ee6e..52168720b 100644 --- a/content/en/apps/guides/hosting/offline.md +++ b/content/en/apps/guides/hosting/offline.md @@ -6,15 +6,15 @@ description: > Deploying and hosting CHT Core server instances without Internet connectivity --- -{{% alert title="Note" %}} This guide is not meant for a production CHT instance. Support may be added in the future an offline CHT server in a production environment. Please see the "Considerations" section below. - +{{% alert title="Note" %}} This guide is not meant for a production CHT instance. Support may be added in the future an offline CHT server in a production environment. Please see the "Considerations" section below. + Proceed only if you have staff familiar with DNS, TLS Certs, DHCP, LAN topology and Linux in general. This is a complex deployment where mistakes are easy to make unless proper training is in place. {{% /alert %}} ## Introduction -The CHT is built as an offline first application. This applies to clients, either browsers or Android applications, connecting to the CHT server. The server itself assumes it has Internet connectivity to provide services such as DNS, software updates and general use connectivity. This document explores what it looks like when the CHT server is offline without these services available. +The CHT is built as an [Offline-First]({{< ref "core/overview/offline-first" >}}) application. This applies to clients, either browsers or Android applications, connecting to the CHT server. The server itself assumes it has Internet connectivity to provide services such as DNS, software updates and general use connectivity. This document explores what it looks like when the CHT server is offline without these services available. -Running a CHT server offline requires no modifications to the CHT itself. Instead, supporting services normally found online are replicated locally. +Running a CHT server offline requires no modifications to the CHT itself. Instead, supporting services normally found online are replicated locally. ## Considerations @@ -37,20 +37,20 @@ Browsers might allow you to connect to a server with an invalid TLS certificate It is common to use [Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_encrypt) to acquire certificates because they provide free certificates. Let's Encrypt certificates expire after 90 days, so the server will need to be constantly updated with a new certificate. Other CAs provide certificates that expire after a year, so this concern will always apply. -After acquiring the certificate, if you are running a Docker-based CHT deployment, see [TLS instructions for Docker]({{< relref "/apps/guides/hosting/ssl-cert-install" >}}) to install the certificate. +After acquiring the certificate, if you are running a Docker-based CHT deployment, see [TLS instructions for Docker]({{< relref "/apps/guides/hosting/ssl-cert-install" >}}) to install the certificate. ### Domain Name Server -In order to match the static IP of the web server to the CN in the certificate, a Domain Name Server (DNS) must be used. This will allow any client on the LAN to easily connect to your CHT server without needing anything more than the domain name. +In order to match the static IP of the web server to the CN in the certificate, a Domain Name Server (DNS) must be used. This will allow any client on the LAN to easily connect to your CHT server without needing anything more than the domain name. Most LANs will defer to the Internet Service Provider (ISP) to provide DNS, but there is no ISP in an offline scenario. Instead, one must be provided. This DNS server will then be configured to have an `A` record (or `AAAA` in the case of IPv6) to point to the CHT server. -### Dynamic Host Configuration Protocol +### Dynamic Host Configuration Protocol -Any new client that connects to a network will get an IP address from a Dynamic Host Configuration Protocol (DHCP) server. It is critical that the DHCP server for the LAN the CHT is on instructs all clients to use the DNS server configured above. +Any new client that connects to a network will get an IP address from a Dynamic Host Configuration Protocol (DHCP) server. It is critical that the DHCP server for the LAN the CHT is on instructs all clients to use the DNS server configured above. -### Wi-Fi AP +### Wi-Fi AP A Wi-FI Access Point (AP) needs to be deployed on the LAN so Android devices can connect to the CHT. This can be an AP included with the router or a standalone AP. If the AP is standalone, check that any DHCP or DNS servers that could conflict with the one above are disabled. @@ -62,9 +62,9 @@ An offline deployment may consider substituting some requirements above with the When an offline solution is deployed, traffic stays 100% local, whereas when using either [your own reverse proxy]({{< relref "/secure-sharing-of-developer-instance" >}}) or a third party provider like [ngrok](https://ngrok.com/), traffic may traverse 100s or 1,000s of kilometers to ultimately reach the CHT server which is 10 meters away. This can help when Internet connectivity is very slow, very expensive per megabyte, or both. -### local-ip.co +### local-ip.co -[local-ip.co](http://local-ip.co/) offers both the TLS certificate and private key for `*.my.local-ip.co`. Additionally, the service has a DNS server that dynamically maps any IP you pass in the sub-sub-domain to the real world IP such that `192-168-0-1.my.local-ip.co` would resolve to `192.168.0.1`. This can make it very handy to deploy a development instance where all HTTP traffic remains local (unlike `ngrok` above). +[local-ip.co](http://local-ip.co/) offers both the TLS certificate and private key for `*.my.local-ip.co`. Additionally, the service has a DNS server that dynamically maps any IP you pass in the sub-sub-domain to the real world IP such that `192-168-0-1.my.local-ip.co` would resolve to `192.168.0.1`. This can make it very handy to deploy a development instance where all HTTP traffic remains local (unlike `ngrok` above). As the DNS traffic still needs to leave your network and return, it is not a viable solution for a truly offline CHT deployment. @@ -76,6 +76,6 @@ This may only work on certain, older version of Android as well. ### No DHCP or DNS Server -To avoid installing both the DHCP and DNS servers, an Android app that enables custom DNS entries, like [DNS Changer](https://play.google.com/store/apps/details?id=com.burakgon.dnschanger) or [Daedalus](https://play.google.com/store/apps/details?id=org.itxtech.daedalus) could be used. As [seen here](https://stackoverflow.com/questions/6370017/mapping-a-hostname-to-an-ip-address-on-android), on each Android device you could install this and add custom DNS entries to reach the TLS certificate on the CHT. +To avoid installing both the DHCP and DNS servers, an Android app that enables custom DNS entries, like [DNS Changer](https://play.google.com/store/apps/details?id=com.burakgon.dnschanger) or [Daedalus](https://play.google.com/store/apps/details?id=org.itxtech.daedalus) could be used. As [seen here](https://stackoverflow.com/questions/6370017/mapping-a-hostname-to-an-ip-address-on-android), on each Android device you could install this and add custom DNS entries to reach the TLS certificate on the CHT. Like the self-signed certificate solution, this is hard to scale and would need to be complimented by editing `/etc/hosts` files on desktop browsers. diff --git a/content/en/apps/tutorials/local-setup.md b/content/en/apps/tutorials/local-setup.md index df5fb9f5b..84797d321 100644 --- a/content/en/apps/tutorials/local-setup.md +++ b/content/en/apps/tutorials/local-setup.md @@ -23,11 +23,11 @@ By the end of the tutorial you should be able to: ## Brief Overview of Key Concepts -*CHT Core Framework* The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are offline-first, and work on basic phones (via SMS), smartphones, tablets, and computers. +*CHT Core Framework* The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are [Offline-First]({{< ref "core/overview/offline-first" >}}), and work on basic phones (via SMS), smartphones, tablets, and computers. *CHT Project Configurer* a.k.a ***cht-conf*** is command-line interface tool to manage and configure CHT apps. -*Docker* is a tool designed to make it easier to create, deploy, and run applications by using containers. +*Docker* is a tool designed to make it easier to create, deploy, and run applications by using containers. *Containers* allow a developer to package up an application with all of the parts it needs, such as libraries and other dependencies, and deploy it as one package. @@ -50,7 +50,7 @@ Now that you have the dependent tools and software installed, you are ready to s ### 1. Install the Core Framework -Check out the [cht-core respository](https://github.com/medic/cht-core) to your local machine. This can be done either by using the [Github Desktop app](https://desktop.github.com/) or by running the following command in the directory where you want the CHT code: `git clone https://github.com/medic/cht-core.git`. Checking out the repo will create a `cht-core` directory. +Check out the [cht-core respository](https://github.com/medic/cht-core) to your local machine. This can be done either by using the [Github Desktop app](https://desktop.github.com/) or by running the following command in the directory where you want the CHT code: `git clone https://github.com/medic/cht-core.git`. Checking out the repo will create a `cht-core` directory. Open your terminal and navigate to the `cht-core` directory, where you should see the `docker-compose.yml` file. Run the command: @@ -100,7 +100,7 @@ By default, the CHT will have the [Maternal & Newborn Health Reference Applicati - Navigate your terminal to the `cht-core/config/default` directory. This is where the reference application is stored. - Run the following `cht-conf` command to compile and upload default test data to your local instance: -```shell +```shell cht --url=https://medic:password@localhost --accept-self-signed-certs csv-to-docs upload-docs`. ``` @@ -147,7 +147,7 @@ Once you have run the above command it should complete with the message: `INFO A ***** -### 5. Optional: Install Valid TLS Certificate +### 5. Optional: Install Valid TLS Certificate {{< figure src="local-ip.TLS.png" link="local-ip.TLS.png" class="right col-6 col-lg-8" >}} @@ -159,7 +159,7 @@ To install a valid certificate, open a terminal in the `cht-core` directory. Ens ./scripts/add-local-ip-certs-to-docker.sh ``` -To see what a before and after looks like, note the screenshot to the left which uses `curl` to test the certificate validity. +To see what a before and after looks like, note the screenshot to the left which uses `curl` to test the certificate validity. The output of `add-local-ip-certs-to-docker.sh` looks like this: diff --git a/content/en/core/_index.md b/content/en/core/_index.md index d5f209412..49cb47ce8 100644 --- a/content/en/core/_index.md +++ b/content/en/core/_index.md @@ -10,7 +10,7 @@ description: > This section provides an overview and reference for development of the Core Framework of the Community Health Toolkit (CHT). {{% /pageinfo %}} -The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are offline-first, and work on basic phones (via SMS), smartphones, tablets, and computers. +The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are [Offline-First]({{< ref "core/overview/offline-first" >}}), and work on basic phones (via SMS), smartphones, tablets, and computers. App developers are able to define health system roles, permissions and reporting hierarchies, and make use of five highly configurable areas of functionality: messaging, task and schedule management, decision support workflows, longitudinal person profiles, and analytics. diff --git a/content/en/core/overview/architecture.md b/content/en/core/overview/architecture.md index e44e48eae..a2b2ca142 100644 --- a/content/en/core/overview/architecture.md +++ b/content/en/core/overview/architecture.md @@ -18,11 +18,11 @@ A free and open source NoSQL database we use to store all our data, configuratio ### api -A NodeJS service which runs on the server as a wrapper around CouchDB. It provides security and APIs for browsers and integrations. It also includes a custom implementation of filtered replication to allow it to support more concurrent users. See more at the [Medic API site](https://github.com/medic/cht-core/tree/master/api) on Github. +A NodeJS service which runs on the server as a wrapper around CouchDB. It provides security and APIs for browsers and integrations. It also includes a custom implementation of filtered replication to allow it to support more concurrent users. See more at the [CHT Core API repo](https://github.com/medic/cht-core/tree/master/api) on Github. ### sentinel -Another NodeJS service running on the server, sentinel performs actions called transitions every time a document in CouchDB is added or modified. Some examples are validations, generating scheduled messages, automatic responses, creating patients, and sending alerts. See more at the [Medic Sentinel site](https://github.com/medic/cht-core/tree/master/sentinel) on Github. +Another NodeJS service running on the server, sentinel performs actions called transitions every time a document in CouchDB is added or modified. Some examples are validations, generating scheduled messages, automatic responses, creating patients, and sending alerts. See more at the [CHT Core Sentinel repo](https://github.com/medic/cht-core/tree/master/sentinel) on Github. ### PostgreSQL @@ -44,7 +44,7 @@ The CHT Web Application is [reactive](https://angular.io/guide/rx-library), resp | Technology | Usage | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [PouchDB](https://pouchdb.com) | To implement an offline first strategy which means the data is stored on the client and all pages can load immediately regardless of whether the user has a fast connection, slow connection, or no connection at all. The data is stored in PouchDB which replicates changes back and forth in the background with the server CouchDB. | +| [PouchDB](https://pouchdb.com) | To implement an [Offline-First]({{< ref "core/overview/offline-first" >}}) strategy which means the data is stored on the client and all pages can load immediately regardless of whether the user has a fast connection, slow connection, or no connection at all. The data is stored in PouchDB which replicates changes back and forth in the background with the server CouchDB. | | [Enketo](https://enketo.org) | To render configured xforms and help with styling and dynamic elements such as show/hide and validation rules. | | [Nools](https://github.com/C2FO/nools) | A rules engine to compute the upcoming tasks and monthly targets of the users. | | [Ngx-Bootstrap](https://github.com/valor-software/ngx-bootstrap) | To integrate Bootstrap components in the Angular application. | @@ -56,7 +56,7 @@ The CHT Web Application is [reactive](https://angular.io/guide/rx-library), resp ##### Structure -The CHT Web Application has the following high level structure: +The CHT Web Application has the following high level structure: - **/js**: Contains the vanilla JavaScript scripts, for example: Enketo widgets, MomentJS locales, etc. - **/ts**: Contains the Angular application source code which uses TypeScript. @@ -64,7 +64,7 @@ The CHT Web Application has the following high level structure: - **/components**, **/directives**, **/pipes**, **/providers** and **/services**: Contain the reusable elements from [Angular](https://angular.io/) framework. - **/modals**: Contains the all application’s modals components. - **/modules**: Contains the application’s modules, each of them has components that are associated to the modules’ routing. -- **/css**: Contains the style files. It uses [Less](http://lesscss.org/) as a CSS preprocessor. +- **/css**: Contains the style files. It uses [Less](http://lesscss.org/) as a CSS preprocessor. - **/fonts**: Contains the fonts. - **/img**: Contains the static images. @@ -85,9 +85,9 @@ App Management is a single page application built with [AngularJS](https://angul | [Less](http://lesscss.org/) | A CSS preprocessor | ##### Structure -- **/css**: Contains style files. It uses [Less](http://lesscss.org/) as a CSS preprocessor. -- **/js**: Contains the JavaScript code. - - **/actions**, **/reducers** and **/selectors**: Contain the implementation of [Redux](https://github.com/reduxjs/redux). +- **/css**: Contains style files. It uses [Less](http://lesscss.org/) as a CSS preprocessor. +- **/js**: Contains the JavaScript code. + - **/actions**, **/reducers** and **/selectors**: Contain the implementation of [Redux](https://github.com/reduxjs/redux). - **/controllers**, **/directives**, **/filters** and **/services**: Contain the reusable elements from [AngularJS](https://angularjs.org) framework. - **/modules**: Contains the vanilla JavaScript scripts. - **/template**: Contains the HTML templates that are used in the AngularJS components and directives. @@ -100,7 +100,7 @@ CHT Web Application works in the browser or wrapped in the [CHT Android](https:/ ### cht-gateway -[Medic Gateway](https://github.com/medic/cht-gateway) is an android app for sending and receiving SMS messages. Each SMS enabled project has one gateway running. It polls an api endpoint to write incoming SMS into the CouchDB and retrieve outgoing SMS to send. +[CHT Gateway](https://github.com/medic/cht-gateway) is an android app for sending and receiving SMS messages. Each SMS enabled project has one gateway running. It polls an api endpoint to write incoming SMS into the CouchDB and retrieve outgoing SMS to send. ### medic-collect diff --git a/content/en/core/overview/data-flows-for-analytics.md b/content/en/core/overview/data-flows-for-analytics.md index fb47f0225..31bb31a9f 100644 --- a/content/en/core/overview/data-flows-for-analytics.md +++ b/content/en/core/overview/data-flows-for-analytics.md @@ -10,7 +10,7 @@ relatedContent: > --- -In this section, we focus on how data flows through the various components of the Community Health Toolkit. The CHT is built to support the delivery of quality community health care at the last mile. The CHT is designed to work in areas with low connectivity, which means it is an offline-first toolkit for care provision. The architectural and technology choices in the stack are mostly guided by this principle, which will be evident in the discussion of the data management pipeline. +In this section, we focus on how data flows through the various components of the Community Health Toolkit. The CHT is built to support the delivery of quality community health care at the last mile. The CHT is designed to work in areas with low connectivity, which means it is an [Offline-First]({{< ref "core/overview/offline-first" >}}) toolkit for care provision. The architectural and technology choices in the stack are mostly guided by this principle, which will be evident in the discussion of the data management pipeline. @@ -64,7 +64,7 @@ Data in the views and functions mentioned in this section is as accurate as the #### 3. Data Use -The data in PostgreSQL is mostly either used by direct querying or via dashboard visualizations for impact monitoring and data driven-decision making. Database visualizations are built scoped to the requirements of supporting a successful deployment. The work of our Research & Learning team, specifically data science, is supported at the PostgreSQL level through updated contactviews, formviews, useviews and functions with access to these provided to relevant parties as and when needed. Our use of data follows our Privacy & Data Protection policy and is in accordance to agreements with our CHT partners. +The data in PostgreSQL is mostly either used by direct querying or via dashboard visualizations for impact monitoring and data driven-decision making. Database visualizations are built scoped to the requirements of supporting a successful deployment. The work of our Research & Learning team, specifically data science, is supported at the PostgreSQL level through updated contactviews, formviews, useviews and functions with access to these provided to relevant parties as and when needed. Our use of data follows our Privacy & Data Protection policy and is in accordance to agreements with our CHT partners. As mentioned previously, formviews are built to present data in a structure similar to the data collection tool (form) used. Useviews are tailored to align with a use case, mostly using the formviews as the data sources. These are fundamentally guided by design of the workflows and should be interpreted in the context of the design materials including a document explaining the definitions of variables used. @@ -80,7 +80,7 @@ The objects present here are not limited to views and functions. Additional tabl ### Beyond Our Current Pipeline -The [cht-core](https://github.com/medic/cht-core) is mostly data collection tools and is the first component of the data management pipeline. It is the core part of a deployment but the rest of the tools can be easily replaced with other preferred options. It also helps that couch2pg is an open source tool which provides the opportunity for collaboration to extend its functionality to support other implementations. Klipfolio, the tool that we currently use for visualizations, is a proprietary tool but there are many open source options, such as [Apache Superset](https://superset.incubator.apache.org/) that are worth exploring and building into future iterations of our impact monitoring and analytics support for the CHT. +The [cht-core](https://github.com/medic/cht-core) is mostly data collection tools and is the first component of the data management pipeline. It is the core part of a deployment but the rest of the tools can be easily replaced with other preferred options. It also helps that couch2pg is an open source tool which provides the opportunity for collaboration to extend its functionality to support other implementations. Klipfolio, the tool that we currently use for visualizations, is a proprietary tool but there are many open source options, such as [Apache Superset](https://superset.incubator.apache.org/) that are worth exploring and building into future iterations of our impact monitoring and analytics support for the CHT. ## Backup diff --git a/content/en/core/overview/offline-first.md b/content/en/core/overview/offline-first.md new file mode 100644 index 000000000..c9f105778 --- /dev/null +++ b/content/en/core/overview/offline-first.md @@ -0,0 +1,77 @@ +--- +title: "Offline-First in the CHT" +linkTitle: "Offline-First" +weight: 2 +description: > + An overview of what Offline-First means, why the CHT uses it, and how to contribute code that uses it. +--- + +## Introduction + +CHT applications are designed to be used equally well in areas with no internet connectivity, slow or unreliable internet connectivity, and good internet connectivity. Achieving reliable performance and powerful features requires diligence and strict adherence to the principles of Offline-First development. + +In this page we'll cover why and how we achieve this in the CHT. + +## Why this is important + +The CHT is designed to improve healthcare in the hardest to reach communities. While some users have a strong internet connection, to be as inclusive as possible we optimise for Care Teams with connections that are intermittent, unreliable, expensive, and low bandwidth. To achieve this the CHT is designed to be offline first, which, as the name suggests, means the application never relies on an internet connection for day to day tasks. + +Caveat: a small set of use cases require a decent internet connection, but these are limited to: +- Logging in +- Initial download of the application and data +- Changing your own password +- Most administrative tasks such as creating new users +- Data analytics over large data sets + +## Requirements + +### Code + +The CHT uses a [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers) to store the code needed to start up and run which is best practice for caching web applications. The CHT Core Framework code is downloaded when the user visits the login page for the first time and completes silently in the background while the user logs in. + +The code includes JavaScript, CSS, HTML, fonts, and images. It doesn't contain any private information so it's safe to download and cache it without authentication. It also doesn't contain deployment specific configuration (covered in detail [below](#data)). + +The CHT Core Framework checks for updates to the code by attempting to connect to the server in the background. The user isn't notified if this check fails or times out, so they can continue to complete workflows without interruption. When an update is found the new code is downloaded and the service worker cache is updated. The user is prompted to reload to start using the new version of the application, but this can be dismissed if they are busy with a patient or don't want to lose their progress if they are midway through an action like creating a contact or completing a form. Either way, the update will be automatically applied the next time the application starts up. + +### Data + +Once the application has started up it needs data to be useful. This data falls into two categories: + +- **Configuration** specific to a single deployment such as forms, task definitions, places, and hierarchies. +- **Patient data** such as personal details, information about visits, reports, tasks, and messages. + +Both of these types of data are cached on the device because they are required for the user to do their job. The CHT Core Framework uses [PouchDB](https://pouchdb.com/) to store the data on the device's disk. Once cached, when the application starts up the code is executed, which reads the data, allowing the user to do their job regardless of the quality of their internet connection. + +If the user creates new patient data by registering a family or completing a task the application stores this in the phone's cache and attempts to submit this to the server. Periodically the application checks to see if there is new data on the server that is relevant to the user and if so, it updates the cache. This process of sending and receiving data updates is called [replication]({{< relref "apps/guides/performance/replication" >}}), and is performed without interrupting the user from their work. + +## FAQs from CHT contributors + +### Q: Should I rely on request failure handling? + +A: No. This only works well when the user has a strong connection, or if the user is completely offline and the request fails immediately. It's impossible to know for sure how long the request will take, so users with poor connectivity may end up waiting forever. If this request is essential to doing their job they will be unable to move on. It is important to handle request failures gracefully, but it doesn't make a request offline first. + +### Q: Should I rely on a request timeout? + +A: No. This attempts to mitigate the problem by unblocking the user eventually. The problem is setting the timeout length correctly - if it's too short then the request won't succeed, but if it's too long the user will be required to wait. Experience suggests the timeout for a simple request would have to be around a minute to allow the request to succeed for most users, but a minute is far too long to expect a user to wait. Almost all requests should have a timeout, but that is not sufficient to make a request offline first. + +### Q: Should I rely on a spinner or loading bar? + +A: No. Much like the timeout solution, this is an attempt to mitigate the problem in this case by giving the user more information about the request. Regardless of the UX, blocking user interaction while waiting for a response is not offline first and therefore not appropriate for the CHT. Showing UX elements when loading is still recommended for local requests, user initiated server requests, and other potentially slow operations. + +### Q: How can I check if the user is authenticated? + +A: It is not possible to know for certain if a user has an active session without getting a response from the server. The CHT caches some data to hint at whether the session is still active, for example the session expiry date. However, the only way to be certain is to connect to the server, which is not offline first. This has been implemented in the CHT by checking the status code on background requests such as replication, and instructing the user to login when necessary. + +### Q: Should I rely on APIs which report device connection status? + +A: No. There are [APIs available](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) which report whether the device is online with reasonable reliability. Unfortunately these APIs don't reliably report whether the connection is slow, whether the connection will be held until the request completes, or whether the CHT server is available. This means that even if the browser API reports that the device is online the code will still make a request that may fail or wait indefinitely for a response. These APIs can be useful but must be used in conjunction with Offline-First principles, for example, the CHT uses the "online" event listener as a prompt to attempt replication in the background. + +### Q: Should I add a feature that requires a connection? + +A: Maybe. There are some things that cannot be done offline first because they either require server interaction (eg: authentication during login) or they need to access data that cannot be cached locally (eg: deployment-wide analytics). Every effort should be made to find a way to implement the feature using Offline-First principles, and trade-offs discussed with senior CHT contributors. If the feature truly needs to be online first then the UX needs to be designed so that the user understands the feature requires an internet connection. + +## Further reading + +- [Designing Offline-First Web Apps](https://alistapart.com/article/offline-first/) by A List Apart +- [A Design Guide for Building Offline First Apps](https://hasura.io/blog/design-guide-to-offline-first-apps/) by Hasura +- [CouchDB takes CHT to the front lines of healthcare work](https://blog.couchdb.org/2017/09/19/couchdb-takes-medic-mobile-to-the-front-lines-of-healthcare-work/) by CouchDB diff --git a/content/en/why-the-cht.md b/content/en/why-the-cht.md index f98c03de9..0315af0f5 100644 --- a/content/en/why-the-cht.md +++ b/content/en/why-the-cht.md @@ -1,7 +1,7 @@ --- title: "Why the Community Health Toolkit?" linkTitle: "Why the CHT?" -menu : +menu : weight : 1 --- @@ -10,9 +10,9 @@ The [Community Health Toolkit](https://communityhealthtoolkit.org) is a collecti {{% /pageinfo %}} -Community health systems can dramatically improve the accessibility, quality, speed, and equity of primary health care, but only if health workers are effectively equipped and supported. Advances in open source technology are making it easier and more affordable than ever to deliver impactful, dignified care in even the hardest-to-reach communities. +Community health systems can dramatically improve the accessibility, quality, speed, and equity of primary health care, but only if health workers are effectively equipped and supported. Advances in open source technology are making it easier and more affordable than ever to deliver impactful, dignified care in even the hardest-to-reach communities. -With thousands of health workers using these tools to support a million home visits every month, the CHT is the most full-featured, mature, and widely-used open source software toolkit designed specifically for community health systems. Hundreds of individuals contribute to the CHT as designers, developers, researchers, health policy experts, health system implementers, and frontline health workers. +With thousands of health workers using these tools to support a million home visits every month, the CHT is the most full-featured, mature, and widely-used open source software toolkit designed specifically for community health systems. Hundreds of individuals contribute to the CHT as designers, developers, researchers, health policy experts, health system implementers, and frontline health workers. {{< youtube SXN76-EZnsM >}} @@ -20,9 +20,9 @@ With thousands of health workers using these tools to support a million home vis ## The CHT Community -The CHT is 100% open source--it always has been and always will be freely available as a public good. This is possible thanks to a diverse community of contributors that includes global health NGOs, technical organizations, governments, and research institutions, with the non-profit organization [Medic](https://medic.org) serving as a technical steward. +The CHT is 100% open source--it always has been and always will be freely available as a public good. This is possible thanks to a diverse community of contributors that includes global health NGOs, technical organizations, governments, and research institutions, with the non-profit organization [Medic](https://medic.org) serving as a technical steward. -Our longterm focus on community-driven health systems, integrated care, and universal health coverage has surfaced innumerable insights that make the CHT unique. We're also deeply committed to [human-centered and participatory design](https://doi.org/10.1080/02681102.2019.1667289), as an approach to building technology with and for hard-to-reach communities. These principles have helped us to foster a remarkably dynamic and innovative community; learning and building with this community is one of the key reasons people decide to work with the CHT. +Our longterm focus on community-driven health systems, integrated care, and universal health coverage has surfaced innumerable insights that make the CHT unique. We're also deeply committed to [human-centered and participatory design](https://doi.org/10.1080/02681102.2019.1667289), as an approach to building technology with and for hard-to-reach communities. These principles have helped us to foster a remarkably dynamic and innovative community; learning and building with this community is one of the key reasons people decide to work with the CHT.
@@ -47,10 +47,10 @@ If you’re contributing to the CHT and would like to see your organization’s ## Speeding up app development with the CHT Core Framework -The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are offline-first, and work on basic phones (via SMS), smartphones, tablets, and the web. Rich interactive applications that would take 6-18 months to build from scratch can be built using CHT Core in as little as 1-2 months. Some of our COVID-19 response applications shipped in under 2 weeks. +The Core Framework makes it faster to build full-featured, scalable digital health apps by providing a foundation developers can build on. These apps can support most languages, are offline-first, and work on basic phones (via SMS), smartphones, tablets, and the web. Rich interactive applications that would take 6-18 months to build from scratch can be built using CHT Core in as little as 1-2 months. Some of our COVID-19 response applications shipped in under 2 weeks. -App developers are able to define health system roles, permissions and reporting hierarchies, and make use of five highly configurable areas of functionality: messaging, task and schedule management, decision support workflows, longitudinal person profiles, and analytics. +App developers are able to define health system roles, permissions and reporting hierarchies, and make use of five highly configurable areas of functionality: messaging, task and schedule management, decision support workflows, longitudinal person profiles, and analytics. The Core Framework can be used to support the unique needs of a given health system and the work of community health workers, frontline supervisors, facility-based nurses, health system managers, and even patients and caregivers. @@ -59,16 +59,16 @@ The Core Framework can be used to support the unique needs of a given health sys -Digital health apps need to support health systems in a wide range of low infrastructure environments. Apps built with the Core Framework are designed to be offline-first and work with only an occasional internet connection. +Digital health apps need to support health systems in a wide range of low infrastructure environments. Apps built with the Core Framework are designed to be [Offline-First]({{< ref "core/overview/offline-first" >}}) and work with only an occasional internet connection. -These apps store a user’s data locally on their device so that workflows can be completed without syncing to the server. When a connection becomes available, data will automatically sync to and from the server. Offline-first technology enables health workers to carry out important duties even when opportunities to sync may be weeks apart. As with any app, there is a limit to how much data can be stored locally, particularly on a mobile device. For users needing access to large amounts of data, online user roles are available. +These apps store a user’s data locally on their device so that workflows can be completed without syncing to the server. When a connection becomes available, data will automatically sync to and from the server. Offline-first technology enables health workers to carry out important duties even when opportunities to sync may be weeks apart. As with any app, there is a limit to how much data can be stored locally, particularly on a mobile device. For users needing access to large amounts of data, online user roles are available. ## Build one application and run it across smartphones, tablets, and the web -A responsive web app is a hybrid of a website and a native mobile application. On desktop and laptop computers, it runs in the web browser. On Android devices (such as cell phones or tablets), it is downloaded as an app. The same source code powers the experience, meaning that the app you see on your desktop is the same app you see on your mobile device. +A responsive web app is a hybrid of a website and a native mobile application. On desktop and laptop computers, it runs in the web browser. On Android devices (such as cell phones or tablets), it is downloaded as an app. The same source code powers the experience, meaning that the app you see on your desktop is the same app you see on your mobile device. -Web apps built with the Core Framework are fully responsive, which means content will scale to fill the available space. Users accessing the app on a mobile device will see a single-panel mobile layout. Users accessing the app on a desktop or laptop device will see a two-panel layout. +Web apps built with the Core Framework are fully responsive, which means content will scale to fill the available space. Users accessing the app on a mobile device will see a single-panel mobile layout. Users accessing the app on a desktop or laptop device will see a two-panel layout. Progressive Web Application (PWA) is another term for web apps that are built and enhanced with modern APIs to deliver offline-first, native-like capabilities while reaching anyone, anywhere, on any device with a single codebase. For more about how CHT Apps and other PWAs integrate the best of native apps and the open web, see the post [What are Progressive Web Apps?](https://web.dev/what-are-pwas/) on web.dev.