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.
The Tupaia Contributing Guidelines and BES Contributor Code of Conduct are published in this repo.
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.
The Tupaia monorepo has three types of packages:
- Platform interfaces. Front-end React applications that the user interacts with.
- 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.
- 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 |
- 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)
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 |
- 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
Comprehensive setup instructions are available in the Tupaia dev onboarding series.
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 setup instructions are in the Tupaia monorepo setup documentation.
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.
We use GitHub Actions for CI/CD.
Most of the packages support the following scripts for testing:
yarn test
yarn test:coverage # Also displays code coverageThis project is also tested with BrowserStack.
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.
In order to automatically format code in VS Code according to our style guide:
- Install Prettier for VS Code.
- Enable the Editor: Format on Save setting:
"editor.formatOnSave": true.
Your files will now be formatted automatically when you save them.