World Food Programme - HungerMap

This is the repository for the World Food Program's HungerMap. For a more information, check out the documentation.

This software is dual-licensed:

1. Open-Source License: Distributed under the terms of the Server Side Publc License (SSPL). See the LICENSE file for details.
2. Commercial License: Available for businesses requiring proprietary use. Contact the Center for Software Engineering Excellence at partners@csee.tech for more information. Failure to comply with either license will constitute a violation of intellectual property rights.

Table of contents

• Contibutors
• Technologies Used
• Feature highlights
• Local development
• Deployment
• Development guidelines

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Lachezar Marinov 📆 👀 💻	Bohdan Garchu 💻 📆 👀	Cansu Moran 💻 📆 👀	Sámuel Fekete 💻 📆 👀	Ahmed Farouk 💻	Armanpreet Ghotra 💻	Haidong Xu 💻
Jakob Schödl 💻	Linus Sander 💻	Ahmet Selman Güclü 💻	Georgi Tsipov 💻	Lukas Weigmann 💻	Georgi Peev 💻	Marius Moldovan 💻
Muhammed Emre Bayraktaroglu 💻	Shaurya Sharma 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Technologies Used

• Next.js 14
• NextUI v2
• Tailwind CSS
• Tailwind Variants
• TypeScript
• Framer Motion
• next-themes
• leaflet, react-leaflet
• Highcharts, highcharts-react
• Tanstack Query

Feature highlights

Explore the most exciting new or improved features of the new HugerMap here through these showcase videos.

• Hunger data visualized on multiple map and alert types
• Information pages
• Chatbot
• Comparison portal
• Download portal
• Email service

Local development

Make sure to use yarn instead of npm!

Install dependencies

yarn install

Set up .env file

Create a file called .env in the root of the project and populate it with the following values:

To use the chatbot feature of the application, start its backend locally.

NEXT_PUBLIC_API_URL=https://api.hungermapdata.org/v2
NEXT_PUBLIC_V3_API_URL=https://b8m0cvbhz3.execute-api.eu-west-1.amazonaws.com/v3
NEXT_PUBLIC_CHATBOT_API_URL=<chatbot API URL>
NEXT_PUBLIC_EMAIL_SERVICE=https://wpf-email-service-backend.onrender.com
NEXT_PUBLIC_GA_ID=<google analytics id>     # Google Analytics ID, optional
NEXT_PUBLIC_FORECASTS_ENABLED=true

Run the development server

yarn dev

Lint your code

To check if there are any lint errors, run

yarn lint

To fix any lint errors, run

yarn lint:fix

Deployment

The application can easily be deployed to PaaS platforms supporting Next.js such as Netlify or Vercel. In addition, the repository contains a Dockerfile, with which you can easily deploy it on any server. Requirements: Docker installed on the machine.

1. Populate the .env file
2. Build the image: docker build -t wfp-hungermap .
3. Start the container: docker run -p 3000:3000 wfp-hungermap

Development guidelines

Besides the usual guidlines, we're following these as per the customer's request:

Styling

Linting and styling is based on Airbnb's React style guide. A pre-commit hook will make sure that only well-formatted code is commited to the repo, but a GitHub Actions workflow will also check this on each PR.

Git and GitHub

Always work on a separate branch, never commit to main! When you're creating a branch, you should use the branchname provided by Linear. Click the branch icon in the upper right corner of issue's page on Linear to copy the branchname. It should have the following format: feature/<issue no.>-<concise description of issue>.

Commit messages are also linted using husky and commitlint, so make sure to start each commit message with feat:, fix: or docs: depending on the type of work implemented in that commit.

After you're done with your task, create a Pull Request and share it with your teammates, ask your team lead and/or TPL for a review. Use squash merge when the PR is approved.

Project Structure

Each component should have their own file, where the file name is the name of the component. The app directory is for pages and layouts, all other components should go to the components directory. Try to group components to sub-directories based on their function. Code that doesn't belong to a specific component should be placed in a different file, in directories like utils, config, types, etc.

Domain Driven Design

DDD is a software design approach that is against the idea of having a single unified model; instead it divides a large system into bounded contexts, each of which have their own model.

What this means for a React application, is that instead of using one global state with, for example Redux, we will have a React context for each of our entities that will store all the data and offer all the methods related to that domain.

• The domain folder contains all the entities and repositories. (Types, Interfaces, etc.)
• The infrastructure folder contains the implementations of the interfaces. (API calls, etc.)
• The operations folder contains the business logic that is not related to a specific entity.
• Bigger files and functions should be placed in the operations folder

Dependency Injection

The point of DI is that the dependencies of services should not be hardcoded, instead they should receive them as parameters, where the type of the parameter is an interface. This makes testing easier and the code more reusable, since the same service can be used with different implementations of the same interface (for example mock implementations for testing).

• Example of how to use the container to resolve a dependency can be found in src/app/elements/page.tsx.
• A list of all dependencies and their implementations can be found in src/container.tsx.

Accessibility score

Form elements must have labels

Programmatically associate labels with all form controls. The recommended method for most circumstances is to use the label element and an explicit association using the for and id attributes. The examples here are ordered from the most common acceptable solution to the least common acceptable solution. For more information, please check: https://dequeuniversity.com/rules/axe/4.9/label

list HTML structure

Ensure all ordered and unordered lists (defined by ul or ol elements) contain only li content elements.

For more information, please check: https://dequeuniversity.com/rules/axe/4.9/list

Color contrast

Ensure all text elements have sufficient color contrast between the text in the foreground and background color behind it.

Success Criterion: Ensure color contrast of at least 4.5:1 for small text or 3:1 for large text, even if text is part of an image. Large text has been defined in the requirements as 18pt (24 CSS pixels) or 14pt bold (19 CSS pixels). Note: Elements found to have a 1:1 ratio are considered "incomplete" and require a manual review.

For more information, please check: https://dequeuniversity.com/rules/axe/4.9/color-contrast

Aira-label

For more information, please check: https://dequeuniversity.com/rules/axe/4.9/aria-command-name

Target size

For more information, please check:https://dequeuniversity.com/rules/axe/4.9/target-size