The CHT Core Framework is a whole health system, not a set of screens

What the Core Framework is actually for

The Core Framework's own description is worth starting from, because the word digital health app covers a lot of ground. It makes it faster to build full-featured, scalable digital health apps that equip health workers to provide better care in their communities.

The model is team-based healthcare delivery and management. Health workers use SMS messages or mobile applications to submit health data, and that data is then viewed and exported using a web application. The web applications are fully responsive with a mobile-first design, and they support localization using any written language, including Left-to-Right and Right-to-Left writing systems.

Those three properties are the design constraints everything else follows from. Offline first, because a health worker in the field frequently has no connectivity and the submission must not be lost. Mobile first, because the primary data entry device is a phone that may be a low-end Android handset rather than a laptop. And localization down to script direction, because the intended deployments are across many countries and the language support is not an afterthought.

The framework also addresses complexities like health system roles and reporting hierarchies, and the readme notes its features are flexible enough to support a range of health programs and local care provider workflows.

This is a distinction worth keeping in mind when reading the repository. It is not a hospital information system, not an electronic medical records product and not a clinical decision support tool. It is a data collection and reporting pipeline for community health workers, where the output is programme data rather than patient records.

The project is a technical resource of the Community Health Toolkit, stewarded by Medic, and it carries a Digital Public Goods verified badge along with a Discourse forum badge in the readme header, which tells you the CHT is treated as a public good with its own community infrastructure rather than as a product with a support desk.

The pieces in the repository, and what each one is

The top-level entries describe the shape of the system more clearly than any architecture diagram would.

There is a webapp/ directory, which is the responsive web application the supervisors and programme managers use. There is an api/ directory for the service layer, and an admin/ directory, which in the CHT world is the separate administration application rather than a settings screen. There is a sentinel/ directory, and in the CHT architecture Sentinel is the transition between SMS and the web app, processing incoming messages and routing them.

Then there is ddocs/, which holds the documentation format that lives in the database itself, so that a deployed instance carries its own documentation. There is config/ for the configuration, and a separate scripts/ directory for build and operational scripts. There is shared-libs/ for the shared libraries, and package.json declares npm workspaces over that directory, with the shared-libs/cht-datasource package built separately from the root.

The infrastructure directories are just as revealing. There is couchdb/, the local database, and couchdb-nouveau/, which is the newer document database work. There is nginx/ and haproxy/ with a haproxy-healthcheck/ directory beside it, so the HTTP layer and its health checking are part of the repository rather than something you assemble. There is sentinel/, already mentioned, and patches/ for patch-package fixes.

There is also a Tests/ and scripts/ pair, a release-notes/ directory, and the governance files you would expect: AGENTS.md, CLAUDE.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, TESTING.md, DEVELOPMENT.md and Changes.md.

The repository also has an .opencodereview/ directory, which indicates that the project has an automated code review workflow in place, and a .sonarcloud.properties file for SonarCloud analysis, a commitlint.config.js for commit message rules, and a .mocharc.js and .husky/ for the test and hook setup.

Running it locally, and the tool beside it

The readme splits the audience clearly. If you are a developer looking to contribute to the Core Framework, you should follow the contributor's guide. If you wish to evaluate the Core Framework, or you are a developer looking to create or modify applications built with it, you can instead follow the easy deployment instructions, which get the latest stable release running locally via Docker.

That distinction is the practical entry point for most people, and the readme recommends the easy deployment route even for developers who intend to modify applications rather than the framework itself.

A second tool is required either way: cht-conf, a tool to manage and configure applications built using the Core Framework, with a brief guide for modifying the config alongside the config directory and a more detailed guide in the documentation. The split between the framework and its configuration is the important architectural point, because it is what allows the same Core Framework to serve several different health programmes with different forms, different contact models and different indicator sets.

The build itself is driven by npm scripts in the root package.json, and the shared libraries are built as part of it. The scripts show the shape of a development loop:

npm run --prefix shared-libs/cht-datasource build
npm run --prefix webapp build-watch

There is also a dev-api script and a dev-sentinel script, both of which set LOG_LEVEL=debug and run the datasource build in watch mode alongside the service, which is what you want when you are working on the SMS path rather than the web interface. The postinstall hook runs patch-package, which is how the patches/ directory applies its fixes.

The engine requirements are stated in package.json: Node.js 22.15.0 or later and npm 10.9.0 or later, with the package marked as type commonjs, and the version in the file is 5.3.0 against the 5.3.1 release tag.

Hosting, browsers and the awkward parts

Applications can be installed locally or in the cloud with Docker or Kubernetes, and the hosting documentation is linked for both.

The browser support statement is the kind of thing worth reading before you promise a deployment to someone. Currently the latest versions of Chrome, Chrome for Android and Firefox are functionally supported. Safari is not supported, because of unreliable implementations of necessary web APIs, and the generic Android browser is not supported either, because of unreliable implementations in general.

The distinction between those two exclusions is worth noting. Safari is excluded for a specific technical reason, since the web APIs the framework depends on are implemented badly there, while the generic Android browser is excluded because the implementations are unreliable in general. In practice the second exclusion is about the browser shipped with a low-end Android device, which is exactly the device a health worker is likely to be holding, and it is the reason the SMS path exists as a first-class input rather than a fallback.

That is the deeper point about the offline-first design. The SMS path is not a legacy leftover; it is how data collection works where the network does not, and the mobile application covers the cases where a data connection is available.

The version matrix is also handled with some care. The readme points at the release notes directory for the latest changes and release announcements, and at a supported versions page in the documentation for the CHT version support matrix including older app versions. Keeping the framework and the app configurations on separate version tracks is what makes a long-running deployment possible, since a programme can upgrade its forms without rebuilding the framework.

The documentation itself is split by topic, with an architecture overview for how the pieces fit together, a database schema page for the format of docs in the database, and a message states page for the SMS exchange protocol between the webapp and the gateway. That last one is the piece to read if you are debugging an SMS workflow, since the SMS exchange is a state machine and the states are where problems live.

Where cht-core fits, and where it stops

The comparison worth making is with a general purpose offline sync library and with a conventional web application stack.

Against a general purpose sync library, the difference is that the framework has already solved the parts of the problem that are specific to community health work: contact models with roles and reporting hierarchies, forms defined in configuration rather than in code, SMS and mobile as parallel data entry paths, and a web layer that is responsive and localisable from the outset. A team using a sync library still has to build all of that, and the reporting hierarchies in particular are not a generic concern.

Against a conventional web stack, the difference is that this is a deployment-ready product rather than a set of components. The webapp, the API, Sentinel, the database, nginx, HAProxy and the health checks are all in one repository and all versioned together, and the Docker route exists so you can evaluate the whole thing on a laptop before deciding anything.

The limits are substantial and mostly inherent to the domain. The AGPL-3.0 licence is the first thing a commercial adopter will notice, and the readme is explicit that contributions are accepted under the same licence. The supported-browser list rules out Safari, which excludes a large share of web users, though for a health worker using an Android handset that is less consequential than it sounds.

The framework also assumes a specific data model, and adapting it to a different one is not a small job. The documentation format lives in the database, the forms and the contact model are configuration, and the whole reporting layer is built around aggregates of community data rather than individual records. A project that needs patient-level clinical records or that has to interoperate with an existing hospital system is working against the architecture rather than with it.

And it is a large repository to take on. The list of directories at the root is a reminder that the framework spans a web application, a service layer, an admin application, an SMS gateway, a document database and a reverse proxy setup, with its own patching, linting, commit conventions, SonarCloud analysis and open code review workflow. Onboarding onto it is a real project rather than an afternoon.

On maintenance, the picture is healthy. The releases are 5.3.1 from 2026-09-15, 5.3.0 from 2026-08-31 and 5.2.0 from 2026-06-26, the last push was on 2026-10-19 and the repository is not archived, and the copyright runs from 2013 to 2026 for Medic Mobile, Inc., which is a long enough history to suggest the framework has survived more than one generation of mobile phones and SMS gateways.

Editorial conclusion

cht-core suits a health programme that needs an offline-first data collection system for community health workers, because the SMS and mobile submission paths, the sync model, the reporting hierarchies and the hosting options are already solved rather than assembled, and because the whole thing can be brought up locally with Docker to evaluate it. It is the wrong tool for a clinical records system or anything handling patient-identifiable data, since the design assumes aggregated community reporting rather than individual care records, and it is the wrong tool if you cannot accept AGPL-3.0, since contributions are accepted under the same licence. Before you evaluate it, read the architecture overview and the database schema documentation, and check the supported versions matrix, because the framework and the app configurations are versioned separately.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. medic/cht-core on GitHub
3. Project website
4. README
5. Releases