# Droughtmap Hub

The Drought-map Hub is a streamlined system that automates the generation and publication of the Composite Drought Index (CDI) map for Eswatini.

# Project Sheet

<table border="1" id="bkmrk-name-name-of-the-pro" style="border-collapse: collapse; width: 100%; height: 297.969px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">Droughtmap Hub Eswatini  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Project Scope**  
</td><td style="height: 29.7969px;"><span style="font-weight: 400;">The National Disaster Management Agency (NDMA) of Eswatini requires a system to monitor, evaluate, and analyse drought conditions in the country. Akvo is developing a platform that utilises output data generated by the Composite Drought Index (CDI) script, provided by the National Drought Mitigation Center (NDMC), through the GeoNode platform, which will be deployed by the NDMA.</span></td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Contract Link**  
</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Project Dashboard Link**</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Start Date**  
</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**End Date**  
</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Repository Link**  
</td><td style="height: 29.7969px;">[https://github.com/akvo/eswatini-droughtmap-hub/](https://github.com/akvo/eswatini-droughtmap-hub/)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Tech Stack**</td><td style="height: 29.7969px;">List of technologies used to execute the technical scope of the project:

- Front-end: JavaScript with React Framework
- Back-end: Python with Django Framework
- Testing: Django Test Framework, Jest
- Coverage: Coveralls
- Documentation: RTD, dbdocs
- CI &amp; CD: Github Workflows
- Hosting: GKE
- Database: PostgreSQL, Cloud-SQL
- Storage: Cloud Storage Buckets

</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Asana Link**  
</td><td style="height: 29.7969px;">[2435 - Drought Monitoring - Eng. Planning Board](https://app.asana.com/0/1208796157034791/1208847968993113)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Slack Channel Link**</td><td style="height: 29.7969px;">[https://akvo.slack.com/archives/C07C0GG86BW](https://akvo.slack.com/archives/C07C0GG86BW)</td></tr></tbody></table>

# Low Level Design

## Introduction

### About Drought-map Hub

The **Eswatini DroughtMap Hub** is a collaborative effort between the National Drought Management Center of Eswatini, the Ministry of Agriculture, and the Eswatini Meteorological Service. This platform is designed to provide a streamlined and user-friendly interface for validating, publishing, and exploring Combined Drought Indicator (CDI) products, enhancing the country's drought monitoring capabilities by enabling efficient data management and promoting public access to critical information.

The platform is structured into two key areas, catering to both administrative and public needs. The **Admin Area** is dedicated to authorized users who play a vital role in ensuring the accuracy and reliability of the CDI products. In this section, users can review and validate the outputs generated by CDI scripts, engage in collaborative discussions to assess data quality and address any inconsistencies, and approve and prepare validated datasets for public release. By maintaining robust data validation protocols, the Admin Area ensures that only high-quality, reliable information is made available to the public.

The **Public Area** serves as the platform’s primary interface for open access to CDI data. It is designed to be intuitive and engaging, allowing users of all backgrounds to explore comprehensive drought-related datasets, gain insights into drought trends and patterns, and utilize the data for research, planning, and decision-making purposes.

By bridging the gap between data generation and public accessibility, the **Eswatini DroughtMap Hub** empowers stakeholders, policymakers, and communities to make informed decisions for mitigating the impacts of droughts. This platform embodies a commitment to transparency, collaboration, and resilience in the face of environmental challenges.

### The Purpose of Drought-map Hub

- **Automate CDI generation:** Using external datasets, the platform automatically computes the CDI on a monthly basis, leveraging scripts from the National Drought Mitigation Center (NDMC).
- **Structure CDI processing and storage:** It processes CDI data and stores the output, including GeoTIFF raster files and aggregated GeoJSON vector files, in a structured manner on a Geonode platform.
- **Create a web application for collaboration and publication:** It offers a web application for authorized users to review, validate, and discuss the CDI map before publishing it for public access.

## CDI Automation  


The CDI is computed using external datasets. These datasets are expected to be updated on a monthly basis by their respective providers, allowing for the CDI to be automatically computed on a monthly basis thanks to scripts provided by the National Drought Mitigation Center (NDMC). The NDMC scripts output raster (GeoTIFF) files.

The output of the NDMC scripts is then processed by an aggregation script that computes an aggregated CDI value for each inkhundla. The aggression script outputs a vector file (GeoJSON).

The NDMC and aggregation scripts are run as part of a monthly cron/background job on a dedicated virtual machine. The scripts compute the outputs for the previous month (outputs for August are computed in September). The job executes the following steps:

[![image2.png](https://wiki.cloud.akvo.org/uploads/images/gallery/2024-12/scaled-1680-/2KCoHz7QnIE1kmNS-image2.png)](https://wiki.cloud.akvo.org/uploads/images/gallery/2024-12/2KCoHz7QnIE1kmNS-image2.png)

### 1. Check external datasets

The external datasets we want to check are as follows:

- **CHIRPS**:  
    A high-resolution precipitation dataset combining satellite estimates and ground observations to monitor rainfall deficits and detect meteorological drought.   
    ***Data source URL:** [https://data.chc.ucsb.edu/products/CHIRPS-2.0/global\_monthly/tifs/](https://data.chc.ucsb.edu/products/CHIRPS-2.0/global_monthly/tifs/)*
- **LST (MOD21)**:  
    Land surface temperature data from MODIS track heat stress and evapotranspiration anomalies linked to drought conditions.  
    ***Data source URL:*** <u>[https://e4ftl01.cr.usgs.gov/MOLT/MOD21C3.061/](https://e4ftl01.cr.usgs.gov/MOLT/MOD21C3.061/)</u>
- **NDVI (MOD13)**:  
    The vegetation greenness index from MODIS indicates plant health and detects agricultural drought through changes in vegetation cover.  
    ***Data source URL:** [https://e4ftl01.cr.usgs.gov/MOLT/MOD13C2.061/](https://e4ftl01.cr.usgs.gov/MOLT/MOD13C2.061/)*
- **SM (Soil Moisture)**:  
    Soil water content data is essential for assessing water availability, hydrological drought, and crop stress.  
    ***Data source URL:** [https://hydro1.gesdisc.eosdis.nasa.gov/data/FLDAS/FLDAS\_NOAH01\_C\_GL\_M.001/](https://hydro1.gesdisc.eosdis.nasa.gov/data/FLDAS/FLDAS_NOAH01_C_GL_M.001/)*

To verify that external datasets are up to date, we must first store all download URLs for each dataset before proceeding with the verification step. Please note that some datasets, including LST (Land Surface Temperature), NDVI (Normalized Difference Vegetation Index), and SM (Soil Moisture), require NASA Earthdata login credentials for access. To obtain these credentials, you can register at the following URL: [https://urs.earthdata.nasa.gov/users/new](https://urs.earthdata.nasa.gov/users/new)

### 2. Check data is up to date

Check if the data is up to date by comparing the number of available external dataset entries with the number of downloaded input data entries.

- If they don't match, identify the missing data, download it, and provide a progress update on the missing list.
- If they match, proceed to the next step: running the CDI script.

### 3. Run NDMC Scripts (CDI Scripts)

Once all datasets are updated to the previous month, run the CDI script to produce the CDI Map output computed from the input datasets

- If an error occurs, send an error message and exit.
- Otherwise, proceed to the next step: run the aggregation once the CDI Map output is generated.

### 4. Run aggregation script

The aggregation script will produce a GeoJSON file containing CDI values for each Inkhundla. The steps are as follows:

1. Take the CDI raster that is generated.
2. Filter out no\_data pixels (-9999).
3. Create a percentile value for each pixel.
4. Generate a median percentile value for each polygon/administrative boundary as defined in Eswatini GeoJSON.
5. Use the Drought classification table to assign a drought category to each polygon.

If an error occurs, send an error message and exit. Otherwise, proceed to the next step: upload outputs to Geonode.

### 5. Upload outputs to Geonode

Upload all CDI outputs (raster and GeoJSON) to the GeoNode instance via the authenticated API. This process consists of two steps:

1. Track the upload progress, as the upload is an asynchronous process, and check when it’s finished.
2. Once the upload is complete, update the metadata to set the category for each output.

If any errors occur, send an error message and exit. Otherwise, proceed to the next step.

### 6. Send success message

The notification informs the Drought-map Hub Admin that all CDI outputs have been successfully uploaded and are now available in their GeoNode instance, while also triggering an endpoint in the Drought-map Hub to create a new Publication Process object.

## Functional Overview

This functional overview describes how the Drought-map hub will use GeoNode to manage and publish CDI Maps, focusing on preventing automatic publishing and access control. It also covers the CDI Map publication workflow.

### Automation/Job

1. **Manual Run of CDI Map Automation:**  
    DroughtMap Hub Admins can manually trigger the cron job from the DroughtMap Hub admin area. This process will call the Rundeck API and track the job's status in the background.
2. **Sending** **email notifications:** All email notifications will proceed as a background process to prevent delays in the user interface. This ensures a seamless user experience while maintaining reliable communication channels.

### Notification List

1. **User Invitation After Account Creation:**  
    Send an email notification to new users containing an invitation link and instructions to activate their account.
2. **Reset Password:**  
    Send an email notification to users requesting a password reset, including a secure link to reset their credentials.
3. **CDI Map Review Request:**  
    Send an email notification to reviewers, informing them of a new CDI Map assigned for review and providing relevant details.
4. **CDI Map Starts the Validation Process:**  
    Send an email notification to the Admin, informing them that all reviewers have submitted their input and the CDI Map is ready for the validation process.
5. **Feedback Submitted:**  
    Send an email notification to the Admin, informing them that a user or visitor has submitted feedback about the Drought-map Hub.

### Home Page

- Visitors can **browse published maps** and select specific maps based on the date. The interface will display the map, associated narrative, and a link to the relevant bulletin (if available).
- To compare changes over time, visitors can use the **compare published maps** functionality to select two points in time. The two chosen maps will be displayed with a slider to control the overlay, facilitating comparison of CDI values.
- **Map download** options are available in GeoJSON, shapefile and image formats (PNG and SVG) in public area for reach published map.
- A **feedback form** allows visitors to share feedback or report bugs, with submissions sent directly to the admins.
- An **About Page** provides information about the drought monitor, data sources, drought severity levels, contact information, and resources for drought monitoring and planning.

### Data Approval

The Drought-map hub will use GeoNode's API to retrieve the CDI Map dataset. This API allows the hub to interact with the GeoNode instance and retrieve the necessary data. More information on using the GeoNode API can be found in the [GeoNode documentation](https://docs.geonode.org/en/master/devel/api/usage/index.html).

The sources provide details on the CDI Map publication process within the Drought-map Hub, encompassing three key steps:

#### 1. Review Step

**![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXerySDmo3RyqncsOytdEh4e4ObamO0q14oQAXXOJjMPX3sRzDD5IGgNkV12ABTVrcyOwkZE2eT2xfJvDhVFzfGbvGdtcJQh9XYdKsN8ZUAE2Mc11r7MYl2l0wq1_dd2mhQrJrzXVg?key=OqHlbBLB3rzksXmka2bgYdYm)**

Reviewers, who are members of the Technical Working Group, are notified via email when a new CDI Map is available for review. They can access the map in the Drought-map hub Admin Area, review each *inkhundla* (administrative region), approve the computed CDI value, or suggest new values with justifications. Reviewers can also access the non-aggregated CDI Raster Map for additional context. Once the review is complete, reviewers finalize it, triggering an email notification to admins.

#### 2. Validation Step

The validation of a CDI Map is done based on the reviews submitted by the reviewers. The admin does not have to wait for all reviewers to send their reviews to start the validation step. Admins click a button to change the status of the Publication Process object to “In Review”. For a CDI Map not yet published, the admins see a table that provides them with an overview of the suggestions of reviews for each inkhundla. The table has the following format:

<table border="1" id="bkmrk-inkhungla-initial-va" style="border-collapse: collapse; width: 100%; height: 59.5938px;"><colgroup><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col><col style="width: 16.6865%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Inkhungla**</th><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Initial Value**</th><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Reviewer 1**</th><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Reviewer 2**</th><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Reviewer X**</th><th class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**Validated Value**</th></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">Value + rationale</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">Value + rationale</td></tr></tbody></table>

All columns but the “Validated Value” are read-only. The admins have an easy way to pick the value from a reviewer or to input their value. They can optionally provide a comment/rationale.

#### 3. Publication Step

After validating the values, admins can publish the CDI Map, making it accessible to the public on the Drought-map hub Public Area. The publishing process involves adding a narrative to provide context to visitors, with the option to share the map on social media.

### User Access Control

The platform has three user types:

1. **Visitors:** Read-only access to published CDI maps and public area features.
2. **Reviewers:** Access to review and provide feedback on computed CDI maps before publication.
3. **DroughtMap Hub Admins:** Full access to manage the platform, users, and data publication processes.

### Data Visualization and Maps

The Drought-map Hub offers various visualization and map-related features:

- **Interactive CDI Maps:** Users can interact with published CDI maps, zoom in/out, and view CDI values for different inkhundlas.
- **Historical Map Comparison:** Visitors can compare two published maps to observe changes in CDI values over time.
- **CDI Raster Map:** Reviewers have access to the non-aggregated CDI Raster Map for additional context during the review process.
- **Map Download:** Visitors can download published maps in PNG and SVG formats, with customization options.

## User Workflow

### Default Admin Account Management

- **Actor:** Default Admin
- **Preconditions:** A default admin account is pre-created with the username and password `changeme123`.
- **Steps:**
    
    
    1. The default admin logs in using the pre-created credentials.
    2. Navigates to the profile page, which includes an email input field.
    3. Updates their email address in the provided input field.
    4. Receives an email verification link to the newly provided email address.
    5. Clicks the verification link to confirm the new email.
        
        
        - Until verification is completed, the email remains unchanged in the system.
    6. Logs out from the session.
    7. Requests a password reset if necessary, receiving an email with reset instructions.
    8. Follows the password reset instructions to set a new password.

### Login  


**Actors:** End User **Preconditions:** User account exists in the system.

**Steps**:

1. **Access Login Page**: 
    - The user navigates to the login page of the platform.
2. **Enter Credentials**: 
    - The user provides their registered email and password.
3. **Submit Login Form**: 
    - The user clicks the "Login" button.
4. **Authentication Process**: 
    - The system verifies credentials: 
        - **If valid**: The user is logged in and redirected to the dashboard based on their role.
        - **If invalid**: System displays an error message (e.g., "Invalid username or password").
5. **Post-Login Actions**: 
    - If it's the user’s first login, they may be prompted to update their password or complete their profile.

### Reset Password Workflow

**Actors:** End User **Preconditions:** User is registered in the system.

**Steps**:

1. **Initiate Reset**: 
    - The user clicks "Forgot Password" on the login page.
2. **Enter Email/Username**: 
    - The user inputs their registered email and submits.
3. **Receive Reset Link**: 
    - The system sends a reset password email with a secure link.
4. **Open Link**: 
    - The user clicks the link and is redirected to the reset password page.
5. **Set New Password**: 
    - The user enters and confirms a new password following password policy guidelines.
6. **Confirmation**: 
    - The system displays a success message and redirects the user to the login page

### Browse Published Maps  


**Actors:** End User **Preconditions:** Published maps exist in the system.

**Steps**:

1. **Navigate to Map Gallery**: 
    - The user selects the "Published Maps" section from the navigation bar or homepage.
2. **Filter and Search**: 
    - The user applies filters (e.g., region, date, type of data) or uses a search bar.
3. **Select a Map**: 
    - The user clicks on a map thumbnail or title.
4. **View Map Details**: 
    - Map opens in a detailed view, displaying metadata, legend, and interactive elements (e.g., zoom, pan)

### Compare Published Maps

**Actors:** End User **Preconditions:** At least two maps are published for different dates (e.g., months).

**Steps**:

1. **Navigate to Compare Section**:
    
    
    - User selects "Compare Maps" from the navigation menu or map gallery.
2. **Select Two Dates for Comparison**:
    
    
    - User is presented with a date picker or dropdown menu.
    - User selects two different dates (e.g., January 2024 and February 2024).
3. **System Fetches Corresponding Maps**:
    
    
    - The system retrieves aggregated vector data for the selected months.
    - Two layers are prepared:
        
        
        - Bottom layer: Map for the earlier date (e.g., January 2024).
        - Top layer: Map for the later date (e.g., February 2024).
4. **Display Overlaid Maps**:
    
    
    - Maps are rendered on top of each other in the same view.
    - A slider is added to control the transparency of the top layer.
5. **Interact with the Slider**:
    
    
    - User drags the slider to adjust how much of the top map overlays the bottom map.
    - Transparency changes dynamically, revealing differences between the two datasets.
6. **Analyze Differences**:
    
    
    - Users can observe changes visually and interact with the map.
    - Legends, metadata, and tooltips provide additional context for the values in each map.
7. **Optional: Apply Filters**:
    
    
    - User can refine the comparison by applying filters (e.g., focusing on specific regions or data ranges).
8. **Exit Comparison**:
    
    
    - User clicks a button (e.g., "Exit Comparison") to return to the standard map view or gallery.

### Export Data in Map View  


**Actors:** End User **Preconditions:** User has opened a map view.

**Steps**:

1. **Open Map View**: 
    - User selects a map from the gallery.
2. **Access Export Options**: 
    - User clicks the "Export" button/icon in the map view toolbar.
3. **Set Export Parameters**: 
    - User specifies: 
        - Data format (e.g., GeoJSON, shapefile, PNG or SVG).
4. **Download File**: 
    - Once the file is ready, the system provides a download link.

### Submit Feedback  


**Actors:** End User **Preconditions:** Landing page is accessible.

**Steps**:

1. **Access Feedback Section**: 
    - User navigates to the feedback form on the landing page.
2. **Fill Feedback Form**: 
    - User enters details such as email and feedback message.
3. **Submit Feedback**: 
    - User clicks the "Submit" button.
4. **Confirmation**: 
    - System displays a "Thank You" message or email acknowledgment

### User Management  


**Actors**: Admin  
**Preconditions**: Admin access to the dashboard.

**Steps**:

1. **Login to Admin Dashboard**: 
    - Admin enters credentials and logs in.
2. **Navigate to User Management**: 
    - Admin selects "System users" from the admin menu.
3. **View User List**: 
    - System displays a list of registered users with details (e.g., name, role, status).
4. **Perform User Actions**: 
    - Admin can: 
        - Add a new user (fill form with details).
        - Edit user information (e.g., name, email, role).
        - Activate/Deactivate user accounts.
5. **Confirm Changes**: 
    - Admin saves changes, and the system updates the user database

### Runs Manual CDI Automation

**Actors**: Admin  
**Preconditions**: CDI automation feature is configured in the system.

**Steps**:

1. **Login to Admin Dashboard**: 
    - Admin enters credentials and logs in.
2. **Navigate to CDI Automation**: 
    - Admin selects "CDI Automation" from the dashboard menu.
3. **Set Parameters for Automation**: 
    - Admin specifies: 
        - Datasets to include (e.g., LST, NDVI).
        - Date range for analysis.
        - Output resolution.
    - Optionally, admin chooses manual override settings (e.g., adjust weights for CDI calculation).
4. **Run Automation**: 
    - Admin clicks "Run CDI Process."
    - System begins processing and displays a status (e.g., "In Progress").
5. **Review Results**: 
    - Once complete, results (e.g., generated raster files) are available for review.
6. **Publish Results**: 
    - Admin publishes the CDI map or exports it for external use.

### Upload dataset via Geonode manually as candidates for CDI publication

**Actors**: Admin  
**Preconditions**:

Steps:

1. Log in to the GeoNode instance.
2. Navigate to **Add Resource** &gt; **Upload Dataset** &gt; Select the desired **raster file (.tif, .tiff)** &gt; Upload.
3. Once the upload is successfully completed, click **Edit** &gt; **Edit Metadata**.
4. **Select Date:** Choose the desired date when the raster file was generated. This will follow the <span style="text-decoration: underline;">**Year-Month**</span> format in the CDI Publication process.
5. **Select category:** CDI Raster Map
6. **Select region:** Swaziland \[Southern Africa\]
7. Go to the **Settings** tab and uncheck **Advertised** to prevent it from being shown in public view.
8. Click update
9. Done

### Create A New CDI Map Publication

**Actors**: Admin  
**Preconditions**: The admin receives a success notification email for the new CDI Map and new publication has been created.

**Steps:**

1. Go to the publication list page.
2. Click Start new publication
3. Set a due date.
4. Edit or use a review request message template
5. Add desired reviewers.
6. Create Publication.
7. Done.

### CDI Map In Review Process

**Actors**: End User  
**Preconditions**: The reviewer receives a review request email notification

**Steps:**

1. Go to the Review list page.
2. Select the pending review item
3. Review all initial values in the table for each Inkhundla. 
    1. Click approve all if all initial values do not need to change.
    2. Add suggestion value if the initial value needs adjustment and add a comment if it's necessary.
4. Submit review.
5. Done: All suggestions values are locked/read-only.

### CDI Map In Validation Process

**Actors**: Admin  
**Preconditions**: The admin receives all reviewers have been submitted

**Steps:**

1. Go to the publication list page.
2. Select the In-Validation item.
3. Review all suggestions &amp; comments values from all reviewers in the table.
4. Add a validated value for each Inkhundla and add a comment if needed.
5. Submit validated values.
6. Done

### CDI Map Publication Process

**Actors**: Admin  
**Preconditions**: Admin access to the dashboard.

**Steps:**

1. Go to the publication list page.
2. Select the "Ready to publish" item
3. Write a narrative text and add a bulletin URL if available.
4. Click Publish
5. Share to available channels: social media or generated shareable URL.
6. Done

## Architecture

### Class Functions

This section describes the relationships and functionalities among each Class Model, categorized by activities in the Drought-Map Hub platform.

#### 1. Administration Management

##### Administration Model

- **Relationship:** The `Administration` model interacts with other system components to maintain platform-wide configurations and settings. It acts as the central management entity, ensuring consistent behavior across various modules.
- **Functionality:**
    - Provides mechanisms for creating, updating, and deleting administrative configurations.
    - Ensures that settings are applied across all relevant modules of the platform.

#### 2. User Management

##### SystemUser Model

- **Relationship:** The `SystemUser` model connects with the `Role` and `UserRole` models to define access controls. It serves as the primary entity representing platform users.
- **Functionality:**
    - Handles user registration and authentication.
    - Links users to roles through the `UserRole` model.
    - Supports updating user profiles and managing user sessions.

##### UserRoleTypes Enum Class  


- **Relationship:** The `Role` model defines the permissions and access levels available in the system.
- **Functionality:**
    - Facilitates the creation and management of roles.
    - Provides an interface to assign and update permissions for specific roles.

#### 3. CDI Map Publication

##### Publication Model

- **Relationship:** The `Publication` model serves as the primary entity for drought map publications and It interacts with the `Review` model for review workflows.
- **Functionality:**
    - Supports the creation and management of CDI maps.
    - Provides access to associated map data and review processes.
    - Facilitates assigning reviewers to specific maps.
    - Tracks review progress and assignments.

##### Review Model

- **Relationship:** The `Review` model references the `Publication` model, connecting reviews to specific publication process. It encapsulates feedback and status updates for the review process.
- **Functionality:**
    - Provides a framework for submitting and managing reviews.
    - Tracks the status of reviews and feedback provided by reviewers.

#### 4. Automation/Job

##### Jobs Model

- **Relationship:** The `Jobs` model serves as a parent entity for the `Task` model. It organizes automation workflows into manageable jobs.
- **Functionality:**
    - Enables the creation and monitoring of jobs.
    - Tracks the status and progress of automation workflows.

##### Task Model

- **Relationship:** The `Task` model is a child of the `Jobs` model, representing individual steps within a job. It inherits the job context and provides detailed task-level information.
- **Functionality:**
    - Manages the creation and updating of tasks within jobs.
    - Tracks task-specific progress and statuses.

### Class Overview

<table border="1" id="bkmrk-class-name-class-not" style="border-collapse: collapse; width: 100%; height: 404.2px;"><colgroup><col style="width: 24.6777%;"></col><col style="width: 75.3203%;"></col></colgroup><thead><tr style="background-color: rgb(236, 240, 241); height: 29.8px;"><td style="height: 29.8px;">Class Name  
</td><td style="height: 29.8px;">Class Notes  
</td></tr></thead><tbody><tr style="height: 29.8px;"><td style="height: 29.8px;">Administration  
</td><td style="height: 29.8px;">Administration(id, name, region)</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">SystemUser  
</td><td style="height: 29.8px;">SystemUser(id, name, email, technical\_working\_group)</td></tr><tr style="height: 46.6px;"><td style="height: 46.6px;">Publication  
</td><td style="height: 46.6px;">Publication(id, cdi\_geonode\_id, year\_month, initial\_values, validated\_values, published\_at, status, narrative, bulletin\_url)</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">Reviews</td><td style="height: 29.8px;">Review(id, publication, user, administration, suggestion\_values, is\_completed)</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">Jobs  
</td><td style="height: 29.8px;">Jobs(id, task\_id, type, status, attempt, result, info, user, created, available)</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">Task  
</td><td style="height: 29.8px;">Task(id, name, func, hook, args, kwargs, result, group, started, stopped, success, attempt\_count)</td></tr></tbody></table>

### Database Overview

#### Main Tables

1. **Users Table:** Stores user details, including roles (visitor, reviewer, admin), username, password, email, and metadata.
2. **Administrations Table:** Contains administrative regions in Eswatini, including IDs, region names, inkhundla names, and matched entries with the `eswatini.topojson` file for geospatial representation.
3. **Publication Table:** Stores publication process of CDI maps, including GeoNode ID, validated values as JSON format, and workflow status (e.g., Pending, In Review, In Validation, Ready to Publish, Published).
4. **Reviews Table:** Stores comments and feedback from reviewers and admins during the data approval process, linked to specific inkhundlas and periods.

#### Relationship Diagrams

[![eswatini-droughtmap-hub.png](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-03/scaled-1680-/wE3gqj0bPgdnlIAe-eswatini-droughtmap-hub.png)](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-03/wE3gqj0bPgdnlIAe-eswatini-droughtmap-hub.png)

### Sequence Diagrams

#### Manual Run of CDI Map Automation

[![Eswatini_Sequence-run_manual-2025-01-06-072148.png](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-01/scaled-1680-/H9riIa05mv9du1jF-eswatini-sequence-run-manual-2025-01-06-072148.png)](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-01/H9riIa05mv9du1jF-eswatini-sequence-run-manual-2025-01-06-072148.png)

### Data Flow Diagrams

[![eswatini-dataflow-2024-12-12-0728.png](https://wiki.cloud.akvo.org/uploads/images/gallery/2024-12/scaled-1680-/pzMZ0Bx5jK9j641Q-eswatini-dataflow-2024-12-12-0728.png)](https://wiki.cloud.akvo.org/uploads/images/gallery/2024-12/pzMZ0Bx5jK9j641Q-eswatini-dataflow-2024-12-12-0728.png)

Source: [https://drive.google.com/file/d/1vNs\_SCCV6mztkzBSEVuLHUOo78RbnpJr/view?usp=drive\_link](https://drive.google.com/file/d/1vNs_SCCV6mztkzBSEVuLHUOo78RbnpJr/view?usp=drive_link)

## Dependencies

### Software Dependencies

The DroughtMap Hub platform incorporates various dependencies and frameworks to enable its functionality and deliver a seamless user experience. The following dependencies are essential components used in the development of the platform:

1. **Django:** The DroughtMap Hub utilizes Django, a high-level Python web framework, to build the back-end infrastructure. Django provides a solid foundation for handling data management, authentication, and implementing business logic.
2. **Pandas:** The DroughtMap Hub relies on Pandas, a powerful data manipulation and analysis library in Python, to handle data processing tasks efficiently. Pandas enable tasks such as data filtering, transformation, and aggregation, enhancing the platform's data management capabilities.
3. **GeoPandas:** The DroughtMap Hub leverages GeoPandas, an extension of Pandas designed for geospatial data, to handle CDI Map values during review, validation, and the generation of published GeoJSON files. GeoPandas simplifies spatial operations, making it easier to manipulate and analyze geospatial data for accurate map outputs.
4. **NextJS:** The front end of the DroughtMap Hub is developed using NextJS, a popular ReactJS framework for building modern web applications. NextJS provides server-side rendering (SSR) and static site generation (SSG), ensuring optimal performance, faster load times, and better SEO. Its built-in routing and API capabilities streamline development, while React enables the creation of dynamic and interactive UI components, ensuring a responsive and engaging user experience.
5. **Tailwind CSS:** The styling of the DroughtMap Hub leverages Tailwind CSS, a utility-first CSS framework that simplifies the process of designing responsive and consistent interfaces. Tailwind's modular approach allows developers to efficiently create visually appealing and highly customizable layouts without writing extensive custom CSS.
6. **Ant Design (antd)**: The platform utilizes Ant Design, a comprehensive UI library based on React, to design and implement a consistent and visually appealing user interface. Ant Design provides a rich set of customizable and reusable UI components, streamlining the development process.
7. **Leaflet:** The platform incorporates Leaflet, a JavaScript library for interactive maps, to handle geospatial data visualization. Leaflet enables the integration of maps, markers, and other geospatial features, enhancing the platform's ability to represent and analyze location-based information.

In addition to the previously mentioned dependencies, the DroughtMap Hub relies on the following essential dependencies and libraries to support its functionality and development process:

1. **Django Rest Framework (DRF):** The DroughtMap Hub utilises Django Rest Framework, a powerful and flexible toolkit for building Web APIs. DRF simplifies the development of APIs within the platform, providing features such as request/response handling, authentication, serialisation, and validation. It enables seamless integration of RESTful API endpoints, allowing for efficient communication between the frontend and backend components.
2. **PyJWT:** PyJWT is a Python library that enables the implementation of JSON Web Tokens (JWT) for secure user authentication and authorisation. The DroughtMap Hub utilises PyJWT to generate, validate, and manage JWT tokens. JWT tokens play a crucial role in ensuring secure user sessions, granting authorised access to specific functionalities and data within the platform.

### 3rd-Party Services

#### Mailjet

- - Mailjet is utilized for seamless email communication within the DroughtMap Hub.
    - It provides features such as email delivery, tracking, and management, ensuring reliable and efficient communication between system users.
    - Mailjet enables the platform to send notifications, reports, and other email-based communications to users, enhancing user engagement and system responsiveness.

#### Rundeck

[Rundeck](https://www.rundeck.com/) is utilized within the DroughtMap Hub platform to trigger and manage background jobs for CDI Automation. It provides a centralized interface for scheduling, executing, and monitoring automated tasks. By leveraging Rundeck's job orchestration capabilities, the platform ensures efficient execution of complex workflows, enabling seamless integration and reliable automation of CDI processes.

#### Geonode

Geonode serves as the spatial data infrastructure for the DroughtMap Hub platform. It is used to store CDI raster data, providing an organized and accessible repository for spatial datasets. Additionally, Geonode hosts aggregation results, which compute aggregated CDI values for each inkhundla, facilitating spatial analysis and visualization. This integration enables efficient management and sharing of geospatial information within the platform.

### High-Level Architecture Overview

#### 1. Front-end (NextJS)

The front-end serves as the user-facing layer, providing an intuitive interface for both public users and authorized administrators. Built with Next.js (powered by React), it enables dynamic routing, and server-side rendering (SSR) for improved performance and SEO.

**Components:**

- **Homepage:** Interactive content showcasing published CDI maps and includes an About page and feedback form.
- **Choropleth Map:** Displays CDI data visually on an interactive map for exploration and analysis.
- **User Authentication and Authorization**: Secure user login and role-based access control.
- **CDI Map Management:** Enables authorized users to review, validate, and publish CDI maps.
- **Users Management:** Provides tools for administrators to manage user accounts.
- **Communication:** The front-end will communicate with the back-end via RESTful APIs, and data will be fetched or submitted in JSON format.

#### 2. Back-end (Django)

The back-end powers the core functionality of the DroughtMap Hub, handling user authentication, data validation workflows, and publishing processes. It serves as the intermediary between the front-end and the GeoNode API for managing and retrieving datasets.

Components:

- **API Layer**: RESTful APIs for handling all interactions between the front-end and back-end.
- **CDI Map Management**: Handling data validation, publishing workflows, and API interactions for authenticated users with appropriate roles.
- **Authentication and Authorization**: Secure login and user roles (reviewers and admins) management.
- **Email Service**: Handles sending of verification emails, invitation links, and notifications.
- **Communication**: The back-end will interact with the database using Django’s ORM, ensuring efficient data retrieval and manipulation.
- **Worker/DjangoQ**: Handles background processes such as monitoring CDI Map automation, downloading maps from GeoNode, and managing long-running tasks without impacting user interactions.
- **Static config**: Generates a `config.js` file containing TopoJSON data for frontend consumption. This static file is produced once the backend container is up and can be re-generated using a custom Django command.

Each component is designed to work cohesively, ensuring the backend is reliable, maintainable, and scalable to meet the needs of the Drought-Map Hub platform

#### 3. Database (PostgreSQL)

To store and manage all data related to users, validation statuses, publishing workflows, and application logs. PostgreSQL, a reliable and feature-rich relational database, is used for efficient data storage and management. GeoNode's database remains external and is accessed through its API for geospatial data and user synchronization.

#### 4. Container Orchestration

The Drought-Map Hub Monitoring Platform uses Docker Compose to orchestrate containers in development and production environments. This ensures a seamless and consistent deployment experience while meeting environment-specific requirements.

##### 4.1 Development Environment Configuration

In the development environment, Docker Compose is configured to support a developer-friendly setup with hot-reloading, debugging capabilities, and minimal complexity. All services are defined in the `docker-compose.yml` file.

**Key Configuration Details:**

1. **Ports**:
    
    
    - Backend: `8000:8000`
    - Frontend: `3000:3000`
    - pgAdmin: `5050:5050`
2. **Volumes**:
    
    
    - Mounts local directories into containers to enable live code updates and preserve database state during container restarts.

##### 4.2 Production Environment Configuration

The production environment is designed for security, scalability, and performance. Services are defined in the `docker-compose.prod.yml` file and the setup includes SSL support with Traefik as the reverse proxy.

**Key Configuration Details:**

1. **Ports**: Only expose ports 80 and 443 to the public network
2. **Service:** The application and the database can be deployed separately on different servers.
3. **SSL**: SSL termination with Traefik using a certificate from Let's Encrypt.

#### 5. CD/CI Pipeline

**Purpose**: Continuous integration and deployment will be automated using GitHub Workflows to ensure smooth development and deployment processes.

**Workflow**:

- **Automated Testing**: Each code push or pull request will trigger tests to ensure code quality.
- **Build and Deploy**: Successful tests will automatically trigger build processes and deploy to the appropriate environment (staging, production).
- **Environment Management**: Separate environments for test, and production will be maintained to ensure stability in releases.

#### 6. Jobs

The Drought-Map Hub platform will utilize DjangoQ for job queue management and asynchronous task execution to support critical features. DjangoQ is an asynchronous task queue for Django, enabling background job processing and schedule management. It integrates seamlessly with Django applications and uses a database-backed broker for task management, making it suitable for the Drought-Map Hub platform.

**Summary Workflow:**

1. **Task Scheduling:** DjangoQ schedules and executes tasks for checking automation status and downloading maps.
2. **Status Monitoring:** Each task's progress and results are monitored and logged for transparency.
3. **User Feedback:** Users are notified of task outcomes, including success or failure, via the platform's user interface.

#### 7. CDI Automation with Rundeck

The **DroughtMap Hub (DMH)** platform integrates **Rundeck** to manage and orchestrate the **CDI Automation** workflows efficiently. Rundeck acts as the centralized platform for scheduling, executing, and monitoring the CDI Automation jobs, ensuring seamless automation and reliable integration of complex workflows.

---

#### [![Eswatini_block-diagram-jobs-2025-01-06-072942.png](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-01/scaled-1680-/poNju0VrC2DAixTX-eswatini-block-diagram-jobs-2025-01-06-072942.png)](https://wiki.cloud.akvo.org/uploads/images/gallery/2025-01/poNju0VrC2DAixTX-eswatini-block-diagram-jobs-2025-01-06-072942.png)

##### Key Features and Workflow Details:

1. **Server Management**:
    
    
    - The CDI Automation server (or VM hosting the API) is not always active.
    - **Yes, the server will only be switched on when the script runs.**
        - Rundeck orchestrates this by triggering the **"Turn on VM API via Rundeck"** job at the start of the workflow.
        - Once the workflow completes, Rundeck ensures the server is turned off through the **"Turn off VM API via Rundeck"** step.
2. **Workflow Execution**:
    
    
    - The workflow follows a well-defined sequence of tasks: 
        - Turn on the CDI server.
        - Execute the CDI automation background job.
        - Monitor for errors: 
            - If errors occur, notify the support team via email.
            - If no errors occur, send a success email to the EDM admin.
        - Turn off the CDI server to optimize resource utilization.
    - Notifications ensure stakeholders are informed of workflow status.
3. **Environment Compatibility**:
    
    
    - Rundeck supports both **production** and **development** environments.
    - In development, local CDI jobs can be triggered via a local DMH instance using the same Rundeck architecture, ensuring consistency across environments.
    - **Dockerized Rundeck** simplifies deployment across different environments. The Docker image for Rundeck can be found [here](https://docs.rundeck.com/docs/administration/install/docker.html#open-source-rundeck).

### Security and Stability Considerations

- **Secure User Authentication:** Implement robust authentication mechanisms like JWT (JSON Web Token) to protect user accounts and sensitive information.
- **Role-Based Access Control:** Restrict access to features and data based on user roles (visitor, reviewer, admin).
- **Secure Data Storage:** Encrypt sensitive data at rest and in transit to protect against unauthorized access.
- **Data Validation and Sanitization:** Validate and sanitize user inputs to prevent security vulnerabilities like SQL injection and cross-site scripting (XSS) attacks.
- **Regular Security Audits:** Conduct periodic security audits to identify and address potential vulnerabilities.
- **Error Handling and Logging:** Implement comprehensive error handling and logging mechanisms to track and resolve issues, improving system stability.

### Database Design

#### 1. Users Table

<table border="1" id="bkmrk-pos-column-null-dtyp" style="border-collapse: collapse; width: 100%; height: 447px;"><colgroup><col style="width: 6.41361%;"></col><col style="width: 29.3194%;"></col><col style="width: 9.55497%;"></col><col style="width: 26.4398%;"></col><col style="width: 6.80919%;"></col><col style="width: 21.5939%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="align-center" scope="col" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**pos**</th><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**column**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**null**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**dtype**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**len**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**default**</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">1</td><td style="height: 29.8px;">id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">system\_user\_id\_seq</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">2</td><td style="height: 29.8px;">name</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">character varying</td><td style="height: 29.8px;">100</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">3</td><td style="height: 29.8px;">email</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">character varying (unique)</td><td style="height: 29.8px;">255</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">4  
</td><td style="height: 29.8px;">role  
</td><td style="height: 29.8px;">No  
</td><td style="height: 29.8px;">enum(`UserRoleTypes`)  
</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">reviewer  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">5</td><td style="height: 29.8px;">password</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">character varying</td><td style="height: 29.8px;">128</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">6  
</td><td style="height: 29.8px;">email\_verified</td><td style="height: 29.8px;">No  
</td><td style="height: 29.8px;">boolean  
</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">false  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">7  
</td><td style="height: 29.8px;">email\_verification\_code</td><td style="height: 29.8px;">Yes  
</td><td style="height: 29.8px;">uuid</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">8  
</td><td style="height: 29.8px;">email\_verification\_expiry  
</td><td style="height: 29.8px;">Yes  
</td><td style="height: 29.8px;">datetime</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">9  
</td><td style="height: 29.8px;">reset\_password\_code</td><td style="height: 29.8px;">Yes  
</td><td style="height: 29.8px;">uuid</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">10  
</td><td style="height: 29.8px;">reset\_password\_code\_expiry</td><td style="height: 29.8px;">Yes  
</td><td style="height: 29.8px;">datetime</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">11</td><td style="height: 29.8px;">technical\_working\_group</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">enum(`TechncalWorkingGroup`)</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">12</td><td style="height: 29.8px;">created\_at</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">current\_datetime</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">13</td><td style="height: 29.8px;">updated\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">14</td><td style="height: 29.8px;">deleted\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr></tbody></table>


#### 2. Administrations Table

<table border="1" id="bkmrk-pos-column-null-dtyp-3" style="border-collapse: collapse; width: 100%; height: 208.6px;"><colgroup><col style="width: 6.41361%;"></col><col style="width: 29.8429%;"></col><col style="width: 10.0835%;"></col><col style="width: 22.2463%;"></col><col style="width: 5.49738%;"></col><col style="width: 26.0471%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="align-center" scope="col" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**pos**</th><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**column**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**null**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**dtype**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**len**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**default**</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">1</td><td style="height: 29.8px;">id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">administration\_id\_seq</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">3</td><td style="height: 29.8px;">name</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">character varying</td><td style="height: 29.8px;">100</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">4  
</td><td style="height: 29.8px;">region</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">character varying</td><td style="height: 29.8px;">50  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">5  
</td><td style="height: 29.8px;">created\_at</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">current\_datetime</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">6  
</td><td style="height: 29.8px;">updated\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr></tbody></table>

#### 3. Publication Table

<table border="1" id="bkmrk-pos-column-null-dtyp-4" style="border-collapse: collapse; width: 100%; height: 447px;"><colgroup><col style="width: 6.41361%;"></col><col style="width: 30.2356%;"></col><col style="width: 9.55497%;"></col><col style="width: 21.8586%;"></col><col style="width: 5.89895%;"></col><col style="width: 26.1691%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="align-center" scope="col" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**pos**</th><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**column**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**null**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**dtype**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**len**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**default**</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">1</td><td style="height: 29.8px;">id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">cdi\_map\_id\_seq</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">2</td><td style="height: 29.8px;">cdi\_geonode\_id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">3</td><td style="height: 29.8px;">year\_month</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">date</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">4  
</td><td style="height: 29.8px;">initial\_values  
</td><td style="height: 29.8px;">No  
</td><td style="height: 29.8px;">JSON  
</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">5  
</td><td style="height: 29.8px;">status</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">5</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">6  
</td><td style="height: 29.8px;">due\_date</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">date</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">7  
</td><td style="height: 29.8px;">validated\_values</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">JSON</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">8  
</td><td style="height: 29.8px;">published\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">10  
</td><td style="height: 29.8px;">narrative</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">text</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">11  
</td><td style="height: 29.8px;">bulletin\_url</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">character varying</td><td style="height: 29.8px;">255</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">12</td><td style="height: 29.8px;">created\_at</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">current\_datetime</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">13</td><td style="height: 29.8px;">updated\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr><td>14</td><td>delete\_at</td><td>Yes</td><td>timestamp</td><td>  
</td><td>  
</td></tr></tbody></table>


#### 4. Reviews Table

<table border="1" id="bkmrk-pos-column-null-dtyp-7" style="border-collapse: collapse; width: 100%; height: 268.2px;"><colgroup><col style="width: 6.41361%;"></col><col style="width: 29.3194%;"></col><col style="width: 8.63874%;"></col><col style="width: 20.0262%;"></col><col style="width: 7.5906%;"></col><col style="width: 28.1424%;"></col></colgroup><tbody><tr style="height: 29.8px;"><th class="align-center" scope="col" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**pos**</th><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**column**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**null**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**dtype**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**len**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.8px;">**default**</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">1</td><td style="height: 29.8px;">id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">reviewers\_id\_seq</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">2</td><td style="height: 29.8px;">publication\_id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">3</td><td style="height: 29.8px;">user\_id</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">int</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">4</td><td style="height: 29.8px;">is\_completed</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">boolean</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">5  
</td><td style="height: 29.8px;">suggestion\_values  
</td><td style="height: 29.8px;">Yes  
</td><td style="height: 29.8px;">JSON  
</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">6  
</td><td style="height: 29.8px;">created\_at</td><td style="height: 29.8px;">No</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">current\_datetime</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">7  
</td><td style="height: 29.8px;">updated\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr style="height: 29.8px;"><td style="height: 29.8px;">8  
</td><td style="height: 29.8px;">completed\_at</td><td style="height: 29.8px;">Yes</td><td style="height: 29.8px;">timestamp</td><td style="height: 29.8px;">  
</td><td style="height: 29.8px;">  
</td></tr><tr><td>9</td><td>is\_overdue\_notified</td><td>Yes</td><td>boolean</td><td>  
</td><td>false</td></tr></tbody></table>

#### 5. Jobs Table

<table border="1" id="bkmrk-pos-column-null-dtyp-10" style="border-collapse: collapse; width: 100%; height: 208.578px;"><colgroup><col style="width: 6.41361%;"></col><col style="width: 29.3194%;"></col><col style="width: 8.63874%;"></col><col style="width: 20.0262%;"></col><col style="width: 7.59162%;"></col><col style="width: 28.1414%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="align-center" scope="col" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**pos**</th><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**column**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**null**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**dtype**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**len**</td><td class="align-center" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle; height: 29.7969px;">**default**</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">1</td><td style="height: 29.7969px;">id</td><td style="height: 29.7969px;">No</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">jobs\_id\_seq</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">2</td><td style="height: 29.7969px;">task\_id</td><td style="height: 29.7969px;">No</td><td style="height: 29.7969px;">character varying</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">3</td><td style="height: 29.7969px;">user\_id</td><td style="height: 29.7969px;">No</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">  
</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">4</td><td style="height: 29.7969px;">type</td><td style="height: 29.7969px;">No</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">5</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">5</td><td style="height: 29.7969px;">status</td><td style="height: 29.7969px;">No</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">5</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">6</td><td style="height: 29.7969px;">attempt</td><td style="height: 29.7969px;">Yes</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">5</td><td style="height: 29.7969px;">  
</td></tr><tr><td>7</td><td>result</td><td>No</td><td>JSON</td><td>  
</td><td>  
</td></tr><tr><td>8</td><td>info</td><td>Yes</td><td>character varying</td><td>255</td><td>  
</td></tr><tr><td>9</td><td>created\_at</td><td>No</td><td>timestamp</td><td>  
</td><td>  
</td></tr><tr><td>10</td><td>updated\_at</td><td>Yes</td><td>timestamp</td><td>  
</td><td>  
</td></tr></tbody></table>

### API Design

#### A. Classes &amp; Utilities

##### A.1. Custom Pagination Class

**Response Structure**

```javascript
{
    "current": <current page number>,
    "total": <total items count>,
    "total_page": <total number of pages>,
    "data": <paginated data>
}
```

**Class Structure**

```python
from rest_framework.response import Response
from rest_framework.pagination import PageNumberPagination


class Pagination(PageNumberPagination):
    page_size = 10
    page_size_query_param = "page_size"
    max_page_size = 100

    def get_paginated_response(self, data):
        return Response(
            {
                "current": self.page.number,
                "total": self.page.paginator.count,
                "total_page": self.page.paginator.num_pages,
                "data": data,
            }
        )

    def get_paginated_response_schema(self, schema):
        return {
            "type": "object",
            "properties": {
                "current": {
                    "type": "integer",
                    "example": 123,
                },
                "total": {
                    "type": "integer",
                    "example": 123,
                },
                "total_page": {
                    "type": "integer",
                    "example": 123,
                },
                "data": schema,
            },
        }
```

#### 1. User API

##### 1.1. User Login

This API endpoint allows users to log in to the platform using their email and password credentials. Upon successful authentication, a session is established for the user.

**Endpoint**: `POST /api/v1/auth/login/`

**Request Body**:

```json
{
    "email": "john.doe@example.com",
    "password": "password123"
}
```

**Response**: **200 OK** on success, with **JWT token for session authentication**.

```json
{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiration_time": "2024-10-22T18:06:11Z",
    "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@example.com",
    }
}
```

##### 1.2. Verify the User's Email  


Verify the user's email using the verification link.

**Endpoint**: `GET /api/v1/email/verify?code={code}`

<span class="hljs-string">**Response**: </span>**200 OK** if successful.

```json
{
    "message": "Email verified successfully."
}
```


##### 1.3. Resend Verification Email  


 Allows the user to request a new verification email.

**Endpoint**: `POST /api/v1/email/verify/resend`

**Request Body**:

```json
{
  "email": "john.doe@mail.com"
}
```

<span class="hljs-string">**Response**: </span>**200 OK** if successful.

```json
{
    "message": "Verification email sent successfully"
}
```


##### 1.4. User Forgot password

This API endpoint allows users to request a password change. Users can initiate the process by providing their registered email address, and a password reset link or instructions will be sent to them.

**Endpoint**: `POST /api/v1/users/forgot-password/`

**Request Body**:

```json
{
    "email": "john.doe@example.com"
}

```

**Response**: **200 OK** on success


##### 1.5. Verify password code

This API endpoint verifies the token provided during the password reset process. It validates that the token belongs to the correct user who requested the password reset, ensuring the authenticity of the request before proceeding.

**Endpoint**: `GET /api/v1/users/verify-password-code?token=secret`

**Response**: **200 OK** on success

```json
{
    "message": "OK"
}
```


##### 1.6. User Reset Password  


This API endpoint allows users to update their old passwords with new ones. A valid token is required to authorize the password reset, ensuring the request is tied to the correct user.

**Endpoint**: `POST /api/v1/users/reset-password?token=secret`

**Request Body**:

```json
{
    "password": "NewPass123",
    "confirm_password": "NewPass123"
}

```

**Response**: **200 OK** on success

```json
{
   "message": "Password reset successfully"
}
```

##### 1.7. User Profile

**Endpoint**: `GET /api/v1/users/me`

**JWT Access:** Admin, Reviewer

**Response**: **200 OK** on success

```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "role": 1,
  "email_verified": true
}
```






#### 2. Public API

##### 2.1 List Map API

**Endpoint**: `GET /api/v1/maps/`

**Request Params**:

<table border="1" id="bkmrk-name-value-descripti" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 18.4819%;"></col><col style="width: 48.2642%;"></col></colgroup><tbody><tr><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Name**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Value**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Description**</th></tr><tr><td>start</td><td>YYYY-MM</td><td>Select start month</td></tr><tr><td>end</td><td>YYYY-MM</td><td>Select end month</td></tr><tr><td>compare</td><td>\[\]</td><td>Array of Map ID</td></tr></tbody></table>

**Response**: **200 OK** on success

```json
[
  "current": 1,
  "total_page": 5,
  "total": 99,
  "data": [
      {
        "id": 99,
        "cdi_geonode_id": 112,
        "year_month": "2024-12",
        "published_at": "2024-12-12 08:10:10TZ",
      },
      ...
      {
        "id": 1,
        "cdi_geonode_id": 3,
        "year_month": "2024-01",
        "published_at": "2024-01-31 12:10:10TZ",
      }
  ]
]
```




##### 2.2 Details Map API

**Endpoint**: `GET /api/v1/map/{id}`

**Response**: **200 OK** on success

```json
{
    "id": 99,
    "cdi_geonode_id": 112,
    "year_month": "2024-12",
    "validated_values": [
        {
          "administration_id": 339,
          "value": 0.68,
          "category": "D4"
        },
        {
          "administration_id": 338,
          "value": 2,
          "category": "D3"
        },
        ...
        {
          "administration_id": 330,
          "value": 30,
          "category": "D0"
        },
    ],
    "published_at": "2024-12-12 08:10:10TZ",
    "narrative": "On the basis of the range of indicators monitored above there are no Tinkhundla in the Lubombo region that are in the alert drought phase signalling improvement from the previous month’s index presentation",
    "bulletin_url": "https://example.com/eswatini-drought-map-2024-12.pdf"
}
```

##### 2.3 Export data API  


**Endpoint**: `GET /api/v1/map/{id}/export`

**Request params**

<table border="1" id="bkmrk-name-value-descripti-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 18.4819%;"></col><col style="width: 48.2642%;"></col></colgroup><tbody><tr><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Name**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Value**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Description**</th></tr><tr><td>format</td><td>enum( GeoTIFF, CSV, GeoJSON)  
</td><td>Export format (e.g., GeoTIFF, CSV, GeoJSON).</td></tr></tbody></table>

**Response: 200 OK** on success

```json
{
  "status": "success",
  "download_url": "https://example.com/export/cdi_2024_01_01_2024_12.tif",
  "metadata": {
    "category": "CDI",
    "format": "GeoTIFF"
  }
}
```

##### 2.4 Submit Feedback API

**Endpoint**: `POST /api/v1/feedback/`

**Request Body**:

```json
{
    "message": "The Drought Map Hub website provides an incredibly user-friendly interface, allowing me to easily track and understand drought conditions across different regions, which has been invaluable for my research.",
    "name": "Alice",
    "email": "alice@wonderland.com"
    "tags": ["UI", "good", "User experience"]
}
```

**Response**: **200 OK** on success

```json
{
   "message": "Your feedback has been sent successfully."
}
```




#### 3. Admin API

##### 3.1 Create New Publication Process  


**Endpoint**: `POST /api/v1/admin/publications/`

**<span class="hljs-string">JWT Access: Admin</span>**

**Request Body**:

```json
{
  "cdi_geonode_id": 222,
  "year_month": "2025-01",
  "reviewers": [1,5,7,8,21],
  "message": "Dear <reviewer name>,\nThe CDI Map for the month of <YYYY-MM> is available for review [here](link to map).\n\nPlease submit your review by <YYYY-MM–DD>.",
  "due_date": "2025-01-31",
  "initial_values": [
    {
      "administration_id": 339,
      "value": 0.68,
      "category": "D4"
    },
    {
      "administration_id": 338,
      "value": 2,
      "category": "D3"
    },
    ...
    {
      "administration_id": 330,
      "value": 30,
      "category": "D0"
    },
  ]
}
```

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 100,
  "cdi_geonode_id": 150,
  "year_month": "2025-01",
  "reviewers": [
    {
      "user_id": 1,
      "email": "reviwer1@mail.com"
    },
    ...
    {
      "user_id": 21,
      "email": "reviwer21@mail.com"
    },
  ],
  "message": "Dear <reviewer name>,\nThe CDI Map for the month of <YYYY-MM> is available for review [here](link to map).\n\nPlease submit your review by <YYYY-MM–DD>.",
  "due_date": "2025-01-31",
  "initial_values": [
    {
      "administration_id": 339,
      "value": 0.68,
      "category": "D4"
    },
    {
      "administration_id": 338,
      "value": 2,
      "category": "D3"
    },
    ...
    {
      "administration_id": 330,
      "value": 30,
      "category": "D0"
    },
  ],
  "published_at": null,
  "status": 1,
  "narrative": "",
  "bulletin_url": null
}
```


##### 3.2 Publications list  


**Endpoint**: `GET /api/v1/admin/publications`

**<span class="hljs-string">JWT Access: Admin</span>**

**<span class="hljs-string">Request params:</span>**

<table border="1" id="bkmrk-name-value-descripti-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 18.4819%;"></col><col style="width: 48.2642%;"></col></colgroup><tbody><tr><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Name**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Value**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Description**</th></tr><tr><td>start</td><td>YYYY-MM</td><td>Select start month</td></tr><tr><td>end</td><td>YYYY-MM</td><td>Select end month</td></tr><tr><td>status</td><td>enum:

1 - Pending

2 - In Review

3 - In Validation

4 - Published

</td><td>CDI Map Status</td></tr></tbody></table>

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
[
  "current": 1,
  "total_page": 10,
  "total": 100,
  "data": [
      {
        "id": 100,
        "cdi_geonode_id": 150,
        "year_month": "2025-01",
        "validated_values": null,
        "published_at": null,
        "status": 1,
        "progress_review": "2/8"
      },
      ...
      {
        "id": 1,
        "cdi_geonode_id": 3,
        "year_month": "2024-01",
        "validated_values": [
          {
            "administration_id": 339,
            "value": 0.68,
            "category": "D4"
          },
          {
            "administration_id": 338,
            "value": 2,
            "category": "D3"
          },
          ...
          {
            "administration_id": 330,
            "value": 30,
            "category": "D0"
          },
        ],
        "published_at": "2024-01-31 12:10:10TZ",
        "status": 4,
        "progress_review": 8/8"
      }
  ]
]
```

##### 3.3 Publication Details  


**Endpoint**: `GET /api/v1/admin/publications/{id}`

**<span class="hljs-string">JWT Access: Admin</span>**

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 100,
  "cdi_geonode_id": 150,
  "year_month": "2025-01",
  "due_date": "2025-02-20",
  "reviewers": [
    {
      "id": 8,
      "user_id": 28,
      "name": "John Doe",
      "email": "john.doe@mail.com",
      "status": 1,
    },
    ...
    {
      "id": 1,
      "user_id": 21,
      "name": "Jane Doe",
      "email": "jane.doe@mail.com",
      "status": 2,
    },
  ]
}
```

##### 3.4 Publication Details with Values  


**Endpoint**: `GET /api/v1/admin/publication/{id}/values`

**<span class="hljs-string">JWT Access: Admin</span>**

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
[
  {
    "id": 711,
    "administration_id": 339,
    "value": 0.68,
    "comment": null,
    "suggestions": [
      {
        "reviewer_id": 8,
        "value": 0.7,
        "comment: "string"
      },
      {
        "reviewer_id": 7,
        "value": 0.71,
        "comment: "string"
      },
      {
        "reviewer_id": 6,
        "value": 0.54,
        "comment: "string"
      },
      ...
      {
        "reviewer_id": 1,
        "value": 0.67,
        "comment: "string"
      },      
    ]
  },
  ...
  {
    "id": 691,
    "administration_id": 330,
    "value": 1,
    "comment": null,
    "suggestions": [
      {
        "reviewer_id": 8,
        "value": 0.9,
        "comment: "string"
      },
      {
        "reviewer_id": 7,
        "value": 2,
        "comment: "string"
      },
      {
        "reviewer_id": 6,
        "value": 1,
        "comment: "string"
      },
      ...
      {
        "reviewer_id": 1,
        "value": 0.81,
        "comment: "string"
      },      
    ]
  },
]
```

##### 3.5 Submit validated value

**Endpoint**: `POST /api/v1/admin/publication/{id}/validated`

**<span class="hljs-string">JWT Access: Admin</span>**

**Request Body**:

```json
{
  "publication_id": 100,
  "values": [
    {
      "administration_id": 339,
      "value": 0.68,
      "comment": "Severe Drought"
    },
    {
      "administration_id": 338,
      "value": 0.2,
      "comment": "Exceptional Drought"
    },
    ...
    {
      "administration_id": 330,
      "value": 1,
      "comment": "This area is Normal or wet conditions"
    },
  ]
}
```

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 100,
  "status": 4,
  "values": [
    {
      "id": 439,
      "administration_id": 339,
      "value": 0.68,
      "comment": "Severe Drought"
    },
    {
      "id": 438,
      "administration_id": 338,
      "value": 0.2,
      "comment": "Exceptional Drought"
    },
    ...
    {
      "id": 430,
      "administration_id": 330,
      "value": 1,
      "comment": "This area is Normal or wet conditions"
    },
  ]
}
```

##### 3.7 Publish CDI Map

**Endpoint**: `POST /api/v1/admin/cdi-map/{id}/publish`

**<span class="hljs-string">JWT Access: Admin</span>**

**Request Body**:

```json
{
  "narrative": "<p>The 3-month SPI reflects <b>positive short and medium-term</b> moisture conditions which has a positive impact on <u>vegetation and surface temperature</u> hence promoting vegetation growth and also lowering the the near-surface air temperature.</p>",
  "bulletin_url": "https://example.com/eswatini/cdi-2025-01.pdf",
}
```

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 100,
  "cdi_geonode_id": 150,
  "year_month": "2025-01",
  "initial_values": [
    {
      "administration_id": 339,
      "value": 0.68,
      "category": "D4"
    },
    {
      "administration_id": 338,
      "value": 2,
      "category": "D3"
    },
    ...
    {
      "administration_id": 330,
      "value": 30,
      "category": "D0"
    },
  ],
  "validated_values": [
    {
      "administration_id": 339,
      "value": 3,
      "category": "D3"
    },
    {
      "administration_id": 338,
      "value": 2,
      "category": "D3"
    },
    ...
    {
      "administration_id": 330,
      "value": 15,
      "category": "D1"
    },
  ],
  "published_at": "2025-01-29 08:00:30TZ",
  "status": 4,
  "narrative": "<p>The 3-month SPI reflects <b>positive short and medium-term</b> moisture conditions which has a positive impact on <u>vegetation and surface temperature</u> hence promoting vegetation growth and also lowering the the near-surface air temperature.</p>",
  "bulletin_url": "https://example.com/eswatini/cdi-2025-01.pdf",
}
```

#### 4. Reviewer API

##### 4.1 Review List  


**Endpoint**: `GET /api/v1/reviewer/reviews`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**<span class="hljs-string">Request params:</span>**

<table border="1" id="bkmrk-name-value-descripti-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 18.4819%;"></col><col style="width: 48.2642%;"></col></colgroup><tbody><tr><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Name**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Value**</th><th class="align-left" scope="row" style="background-color: rgb(236, 240, 241); vertical-align: middle;">**Description**</th></tr><tr><td>start</td><td>YYYY-MM</td><td>Select start month</td></tr><tr><td>end</td><td>YYYY-MM</td><td>Select end month</td></tr><tr><td>status</td><td>enum:

1 - Pending

2 - In Review

3 - In Validation

4 - Published

</td><td>CDI Map Status</td></tr></tbody></table>

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
[
  "current": 1,
  "total_page": 10,
  "total": 100,
  "data": [
      {
        "id": 61, 
        "publication_id": 100,
        "year_month": "2025-01",
        "due_date": "2025-02-20",
        "completed_at": null,
        "is_completed": false,
        "progress_review": "2/8"
      },
      ...
      {
        "id": 1,
        "publication_id": 10,
        "year_month": "2024-01",
        "due_date": "2024-02-31",
        "completed_at": "2024-01-31 12:10:10TZ",
        "is_completed": true,
        "progress_review": 8/8"
      }
  ]
]
```

##### 4.2 Review Details  


**Endpoint**: `GET /api/v1/reviewer/reviews/{id}`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 100,
  "cdi_geonode_id": 150,
  "year_month": "2025-01",
  "due_date": "2025-02-20",
  "initial_values": [
    {
      "administration_id": 339,
      "value": 0.68,
      "category": "D4"
    },
    {
      "administration_id": 338,
      "value": 2,
      "category": "D3"
    },
    ...
    {
      "administration_id": 330,
      "value": 30,
      "category": "D0"
    },
  ],
  "suggestion_values": null,
  "is_completed": false,
  "updated_at": "2025-01-19 18:22:00TZ",
  "completed_at": null,
}
```

##### 4.3 Publication Details Suggestions values  


**Endpoint**: `GET /api/v1/reviewer/review/{id}/suggestions`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
[
  {
    "id": 811,
    "administration_id": 339,
    "value": 0.68,
    "value_suggestion": 0.61,
    "comment": null,
    "approved": false
  },
  {
    "id": 810,
    "administration_id": 338,
    "value": 0.68,
    "value_suggestion": null,
    "comment": null,
    "approved": true
  }
  ...
  {
    "id": 891,
    "administration_id": 330,
    "value": 1,
    "value_suggestion": 0.98,
    "comment": "Abnormally Dry actually",
    "approved": false
  }
]
```

##### 4.3 Submit value suggestion

**Endpoint**: `POST /api/v1/reviewer/review/{id}/values`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**Request Body:**

```json
{
  "administration_id": 339,
  "value_suggestion": 0.61,
  "comment": "This area is moderate drought"
}
```

<span class="hljs-string">**Response: 201 Created** on success</span>

```json
{
  "id": 811,
  "publication_id": 111,
  "administration_id": 339,
  "value": 0.68,
  "value_suggestion": 0.61,
  "comment": "This area is Moderate Drought",
  "approved": false
}
```

##### 4.4 Update value suggestion and approved status

**Endpoint**: `PUT /api/v1/reviewer/review/{id}/value/{value_id}`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**Request Body:**

```json
{
  "administration_id": 339,
  "value_suggestion": 0.7,
  "comment": "This area is slightly moderate drought",
  "approved": true
}
```

<span class="hljs-string">**Response: 200 OK** on success</span>

```json
{
  "id": 811,
  "publication_id": 111,
  "administration_id": 339,
  "value": 0.68,
  "value_suggestion": 0.7,
  "comment": "This area is slightly moderate drought",
  "approved": true
}
```

##### 4.5 Submit review (Finalize the review)

**Endpoint**: `PUT /api/v1/reviewer/review/{id}`

**<span class="hljs-string">JWT Access: Reviewer</span>**

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```json
{
  "id": 61,
  "publication_id": 111,
  "year_month": "2025-01",
  "is_completed": true,
  "updated_at": "2025-01-19 18:22:00TZ",
  "completed_at": "2025-01-20 10:31:01TZ",
}
```

#### 5. Settings API

##### 5.1 Technical Support Contacts  


**Endpoint**: `GET /api/v1/settings/tsc`

**<span class="hljs-string">JWT Access</span>**<span class="hljs-string">: Admin</span>

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```julia
{
  "status": "success",
  "data": {
    "email_addresses": "support1@example.com, support2@example.com, support3@example.com"
  },
  "message": "Email addresses retrieved successfully."
}
```

##### 5.2 Admins Contacts  


**Endpoint**: `GET /api/v1/settings/dha`

**<span class="hljs-string">JWT Access</span>**<span class="hljs-string">: Admin</span>

**<span class="hljs-string">Response: 200 OK</span>**<span class="hljs-string"> on success</span>

```julia
{
  "status": "success",
  "data": {
    "email_addresses": "admin1@example.com, admin2@example.com"
  },
  "message": "Email addresses retrieved successfully."
}
```

### Data Storage

This section outlines where static maps and CDI outputs are stored within the system.

#### 1. Static Maps

- **File Type**: TopoJSON
- **Location**: Stored in the `source` directory within the backend container.
- **Details**: The `eswatini.topojson` file is used for geospatial visualization and is a critical part of the static map data.

#### 2. CDI Output

- **File Type**: GeoTIFF
- **Location**: Stored in the `source/GeoTiffs` directory within the backend container.
- **Details**: All CDI output files (GeoTIFFs) are saved here to ensure organized access for processing and visualization.

#### 3. Development Setup

The `source` directory is mounted into the development Docker container to streamline data access and integration during development workflows.

### Error Handling

#### 1. Application

##### 1.1 Account Creation

- **Duplicate Email:**
    - Check both the Droughtmap backend and GeoNode before creating the user.
    - Return a user-friendly error message if the email is already in use.
- **GeoNode API Failures:**
    - If the GeoNode user creation fails, roll back the Droughtmap backend operation.
    - Log the error for further debugging.

#### 2. CDI Jobs

In case of an error at any stage of the automation process, the cron job for that month is not executed anymore.

**Message Types**

<table border="1" id="bkmrk-message-type-message" style="border-collapse: collapse; width: 100%; height: 445.273px;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><th class="align-left" scope="row" style="height: 29.7969px; background-color: rgb(236, 240, 241); vertical-align: middle;">**Message Type**</th><th class="align-left" scope="row" style="height: 29.7969px; background-color: rgb(236, 240, 241); vertical-align: middle;">**Message Detail**</th></tr><tr style="height: 204.414px;"><td style="height: 204.414px;">Data is Missing</td><td style="height: 204.414px;">- Recipient: DroughtHub Admins
- Subject: CDI-E Automation - YYYY-MM - Mission data
- Body:
    
    
    - Datetime of execution
    - “The following datasets have not yet been updated. Another attempt will be done in XX days.”
        
        
        - List the datasets for which the data is missing

</td></tr><tr style="height: 211.062px;"><td style="height: 211.062px;">Error</td><td style="height: 211.062px;">- Recipient: Technical Support Contacts
- Subject: CDI-E Automation - YYYY-MM - Execution Error
- Body:
- Datetime of execution
- “The CDI automation has failed for month YYYY-MM. See the attached log file for details.”


**Attachment: Log file**

</td></tr></tbody></table>

YYYY-MM refers to the month for which the CDI computation was attempted.

## Testing Strategy

#### Testing Framework and Tools

The DroughtMap Hub employs a comprehensive testing strategy to ensure the reliability, functionality, and quality of both its back-end and front-end components. The testing strategy encompasses different levels of testing, including back-end testing with Django Test, front-end testing with Jest, and container network testing with HTTP (bash). Here is an overview of the testing strategy for the DroughtMap Hub:

**Back-end Testing with Django Test**

- The back-end testing of the DroughtMap Hub is conducted using Django Test, a testing framework provided by Django.
- Django Test enables the creation of test cases and test suites to evaluate the functionality and behavior of the back-end components.
- Back-end testing focuses on unit tests, integration tests, and API tests to validate individual modules, their interactions, and the API endpoints.
- Test cases cover various scenarios, including positive and negative input cases, edge cases, and boundary conditions to ensure robustness and accuracy.

**Front-end Testing with Jest**

- The DroughtMap Hub's front-end testing is performed using Jest, a JavaScript testing framework widely used for testing React applications.
- Jest facilitates the creation of unit tests, integration tests, and component tests to assess the behavior and functionality of the front-end components.
- Front-end testing focuses on validating the UI components, user interactions, and the correctness of the application's logic and state management.
- Test cases cover various scenarios, including rendering components, user actions, and expected outcomes to ensure the desired user experience and functionality.

## Deployment Strategy

## Considerations

### Design Considerations

- **Data Model:** Carefully design the database schema to ensure efficient data storage and retrieval.
- **API Design:** Create well-defined and documented API endpoints to enable seamless integration with other systems.
- **User Interface:** Design a user-friendly and responsive interface that provides clear visualizations and intuitive interactions.

### Performance Considerations

- Optimize Data Processing: Use efficient algorithms and data structures to minimize processing time for CDI computation and data retrieval.
- Caching: Implement caching mechanisms to reduce the load on the database and improve response times for frequently accessed data.
- Load Balancing: Distribute traffic across multiple instances of the application to ensure high availability and responsiveness.

#### Swagger

**Purpose**: Generate and host interactive API documentation for the backend.  
**Deployment Strategy**:

- **Generation**: Use the `<span class="hljs-attribute">drf-yasg</span>` library (or an equivalent tool) to generate Swagger documentation from the Django REST Framework APIs.
- **Hosting**: 
    - Deploy Swagger UI as a part of the DroughtMap backend application.
    - Make the Swagger documentation accessible at a dedicated route (e.g., `<span class="hljs-regexp">/api/</span>docs`).
- **Automation**: Integrate Swagger generation as a build step in the CI/CD pipeline to ensure updated API documentation with every deployment.

#### Read the Docs

**Purpose**: Host comprehensive technical documentation for developers and administrators.  
**Deployment Strategy**:

- **Content**: Write documentation using Sphinx (reStructuredText or Markdown) for tutorials, setup guides, and system architecture overviews.
- **Integration**: 
    - Configure the `readthedocs.yml` file for automated builds and hosting.
    - Link Read the Docs with the project's GitHub repository to trigger builds on documentation updates.
- **URL**: Deploy under a consistent subdomain (e.g., `docs.droughtmaphub<span class="hljs-meta">.org</span>`).

#### DBDocs

**Purpose**: Visualize and document the database schema for improved collaboration.  
**Deployment Strategy**:

- **Schema Generation**: 
    - Use tools like `<span class="hljs-attribute">DBML</span>` (Database Markup Language) or `<span class="hljs-type">SQL</span> ex<span class="hljs-keyword">port</span>` to define and generate database schema documentation.
    - Automate the schema generation in the CI/CD pipeline to ensure it stays in sync with the database.
- **Hosting**: 
    - Host the schema documentation using `<span class="hljs-attribute">DBDocs</span>` (e.g., `<span class="hljs-symbol">https:</span><span class="hljs-comment">//dbdocs.io/eswatini-droughtmap-hub</span>`).
    - Link the schema documentation in the Read the Docs and Swagger UI for centralized access.