Open source info

Mission statement

By engaging and collaborating with our community we can deliver a more robust product that bridges cultural differences and empowers decision making within health systems worldwide.

Community

The Tupaia Contributing Guidelines and BES Contributor Code of Conduct are published in this repo.

Packages

Note

This is a monorepo.

It is set up using Yarn workspaces, meaning any command you would normally run inside a package can be run from the root directory using yarn workspace @tupaia/package-name command. For example, yarn workspace @tupaia/central-server start-dev.

If you want to watch internal dependencies while running a server, run yarn workspace @tupaia/package-name start-dev -i. The -i command will listen to changes in the internal dependencies' dist folders and restart on changes. You can also run build-watch on these internal dependencies to watch changes and rebuild the package on change. This, combined with -i on the server start script will mean anytime you change something in your chosen package, the servers will restart. For example, you could run yarn workspace @tupaia/central-server start-dev and also yarn workspace @tupaia/utils build-watch which would mean the central-server would restart anytime you make a change in utils. By default, central-server, datatrak-web-server, and tupaia-web-server have -i enabled, for convenience.

Use the start-stack command to start all servers needed to run a stack. Available for admin-panel, datatrak, lesmis, psss and tupaia-web. For example, yarn start-stack tupaia-web.

Tip

The easiest way to open the packages in VS Code is to open the tupaia-packages.code-workspace file. This opens all packages as roots in the workspace, and means linting et al will work correctly.

Package structure

The Tupaia monorepo has three types of packages:

1. Platform interfaces. Front-end React applications that the user interacts with.
2. Servers.
   • Orchestration servers. Dedicated backend applications for each platform interface.
   • Micro servers. Applications which are used by the orchestration servers to perform common system functions.
3. Libraries. Various utility and common libraries that are used throughout the monorepo.

While each package type has their own structure, there are a few common standards:

File	Purpose
<package>/package.json	Package definition
<package>/src/	Contains source code
<package>/.env.example	File showing what environment variables are required by the package
<package>/.env	Environment variables used by package (ignored by Git)
<package>/src/__tests__/	Contains unit tests

Platform interfaces

• Tupaia Web
• Tupaia DataTrak Web
• Admin Panel
• LESMIS
• PSSS
• MediTrak

Servers

Orchestration servers

• admin-panel-server
• datatrak-web-server
• lesmis-server
• meditrak-app-server
• psss-server
• tupaia-web-server
• web-config-server (Tupaia’s orchestration server, referred to as web-config-server for legacy reasons)

Micro servers

• central-server
• entity-server
• report-server
• data-table-server

Server packages can be built by running yarn workspace @tupaia/package-name build. Server packages can then be started by running yarn workspace @tupaia/package-name start.

All servers are Node.js–Express applications, and the packages follow the same basic structure:

File	Purpose
<package>/examples.http	Example queries showing the server interface
<package>/src/index.ts	Server entry point
<package>/src/app/createApp.ts	Express router definition
<package>/src/routes/	Route definitions

Libraries

• access-policy
• aggregator
• api-client
• auth
• data-api
• data-broker
• data-lake-api
• database
• devops
• dhis-api
• e2e
• expression-parser
• indicators
• server-boilerplate
• server-utils
• superset-api
• tsutils
• types
• ui-chart-components
• ui-components
• ui-map-components
• utils
• weather-api

Getting started

Comprehensive setup instructions are available in the Tupaia dev onboarding series.

Secrets

Most packages will require a .env file. .env.example files indicate the required variables per package. More instructions for setting environment variables are in the Tupaia monorepo setup documentation.

Development database

Development database setup instructions are in the Tupaia monorepo setup documentation.

Dependencies

We use Yarn Workspaces to manage our packages, which allows us to run yarn once at the project root, and it will install dependencies everywhere.

CI/CD

We use GitHub Actions for CI/CD.

Tests

Most of the packages support the following scripts for testing:

yarn test
yarn test:coverage  # Also displays code coverage

This project is also tested with BrowserStack.

Style guide

We use a combination of ESLint configs to detect quality and formatting issues in code:

• @beyondessential/eslint-config-js for JavaScript packages
• @beyondessential/eslint-config-ts for TypeScript packages
• @beyondessential/eslint-config-jest for packages using Jest

The config for this repository is defined in .eslintrc under the root folder. Additional rules/overrides per package are specified in this file.

Important

Please do not use individual ESLint configs. Update the main configuration file instead.

Auto-formatting in Visual Studio Code

In order to automatically format code in VS Code according to our style guide:

1. Install Prettier for VS Code.
2. Enable the Editor: Format on Save setting: "editor.formatOnSave": true.

Your files will now be formatted automatically when you save them.