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:

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.
  
• LST (MOD21): Land surface temperature data from MODIS, used to track heat stress and evapotranspiration anomalies linked to drought conditions.
  
• NDVI (MOD13): The vegetation greenness index from MODIS indicates plant health and detects agricultural drought through changes in vegetation cover.
  
• SM (Soil Moisture): Soil water content data, is essential for assessing water availability, hydrological drought, and crop stress.

To check these external datasets, we need to store all download URLs for each dataset and then proceed to the next step to verify that the data is up to date.

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. Export CDI Map:
   The CDI Map in the DroughtMap Hub can be exported in multiple formats, including images (.png, .jpg), tabular data (.csv), and raw geospatial data (GeoJSON). This export process runs asynchronously in the background, and users will receive a notification once the export is complete and ready for download.
   

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 PNG and SVG formats. The sources also suggest a bonus feature for shapefile (.shp) download. Users can select elements like titles, legends, and annotations to customize downloaded maps for easier integration into knowledge products.
• 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. 

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

1. Review Step

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:

Inkhungla	Initial Value	Reviewer 1	Reviewer 2	Reviewer X	Validated Value
		Value + rationale			Value + rationale

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

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 or username 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., GeoTIFF, CSV, GeoJSON).
     • Area of interest (bounding box or predefined region).
     • Time range.
     • Resolution (if applicable).
4. Submit Export Request:
   • User confirms the request, and the system starts processing.
5. 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 name, email, and feedback message.
   • Optionally, the user rates their experience (e.g., using stars).
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 "User Management" from the dashboard 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.
     • Reset user passwords.
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.

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. Select New publication item.
   
3. Add desired reviewers.
4. Set a due date.
5. Write a message.
6. Send Review request.
   
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 inkhudla.
   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 & comments values from all reviewers in the table.
4. Add a validated value for each inkhudla 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.

Role Model

• Relationship: The Role model defines the permissions and access levels available in the system. It is associated with the UserRole model to assign roles to users.
• Functionality:

  • Facilitates the creation and management of roles.

  • Provides an interface to assign and update permissions for specific roles.

UserRole Model

• Relationship: The UserRole model acts as a bridge between the SystemUser and Role models, enabling many-to-many relationships.
• Functionality:
  • Manages role assignments for users.
  • Allows retrieval of roles associated with specific users.

3. CDI Map Publication

CDIMap Model

• Relationship: The CDIMap model serves as the primary entity for drought map publications and is linked to the CDIMapValues model for storing detailed map data. It also interacts with the ReviewAssignment model for review workflows.
• Functionality:
  • Supports the creation and management of CDI maps.
  • Provides access to associated map data and review processes.

CDIMapValues Model

• Relationship: The CDIMapValues model is tightly linked to the CDIMap model. It stores granular data points for specific maps.
• Functionality:
  • Enables adding and updating detailed data points for maps.
  • Ensures geographic and contextual accuracy of map values.

ReviewAssignment Model

• Relationship: The ReviewAssignment model connects CDI maps with reviewers, coordinating the review process. It references the Reviewer model to manage assignments.
• Functionality:

  • Facilitates assigning reviewers to specific maps.

  • Tracks review progress and assignments.

Reviewer Model

• Relationship: The Reviewer model is linked to the SystemUser model and is referenced by the ReviewAssignment model. It represents users with expertise in specific domains.
• Functionality:
  • Supports the addition and management of reviewers.
  • Links reviewers with their areas of expertise and assignments.

Review Model

• Relationship: The Review model references the ReviewAssignment model, connecting reviews to specific assignments. 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. User/Visitor Feedback Management

Feedback Model

• Relationship: The Feedback model interacts with the SystemUser model for user-submitted feedback while also supporting anonymous submissions. It aggregates feedback for analysis.
• Functionality:
  • Collects and stores feedback from users and visitors.
  • Supports filtering and retrieval of feedback for analysis and reporting.

5. 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

Class Name	Class Notes
Administration	Administration(id, parent_id, code, name, admin_level)
SystemUser	SystemUser(id, name, email)
Role	Role(id, name, description)
UserRole	UserRole(id, user, role)
CDIMap	CDIMap(id, geonode_id, year_month, geotiff, geojson, published_geojson, published_at, status, narrative, bulletin_url)
CDIMapValues	CDIMapValues(id, cdi_map, administration, initial_value, value)
ReviewAssignment	ReviewAssignment(id, cdi_map, due_date, message)
Reviewer	Reviewer(id, cdi_map, user, status, approved_at)
Review	Review(id, cdi_map, user, administration, value, comment, approved)
Feedback	Feedback(id, user, email, name, message, tags, status, submitted_at)
Jobs	Jobs(id, task_id, type, status, attempt, result, info, user, created, available)
Task	Task(id, name, func, hook, args, kwargs, result, group, started, stopped, success, attempt_count)

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. CDI Map Table: Stores metadata for CDI maps, including GeoNode ID, file paths for GeoTIFF and GeoJSON, and workflow status (e.g., Pending, In Review, In Validation, Ready to Publish, Published).
   
4. CDI Map Values Table: Stores CDI values with map ID, administration ID and drought index values.
   
5. Reviews Table: Stores comments and feedback provided by reviewers and admins during the data approval process, linked to specific inkhundlas and time periods.

Relationship Diagrams

Source: https://drive.google.com/file/d/1utQVWFxQchvs0_D2lfy1951gwnIg6RlL/view?usp=drive_link

Sequence Diagrams

Manual Run of CDI Map Automation

Data Flow Diagrams

Source: 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.
8. Echarts: Echarts, a powerful charting library, is integrated into the DroughtMap Hub to generate various data visualizations. With Echarts, the platform can display charts, graphs, and other visual representations of data, enabling users to gain insights and make informed decisions.

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.
3. Sphinx: Generate comprehensive and user-friendly documentation. Sphinx facilitates the creation of structured documentation, including API references, code examples, and user guides. It streamlines the documentation process, making it easier for developers and users to understand and utilize the platform's features and functionalities.

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 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.

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

pos	column	null	dtype	len	default
1	id	No	int		system_user_id_seq
2	name	No	character varying	100
3	email	No	character varying (unique)	255
4	password	No	character varying	128
6	created_at	No	timestamp		current_datetime
7	updated_at	Yes	timestamp
8	deleted_at	Yes	timestamp

2. Roles

pos	column	null	dtype	len	default
1	id	No	int		roles_id_eq
2	name	No	character varying (unique)	100
3	description	Yes	character varying	255
4	created_at	No	timestamp		current_date
5	updated_at	Yes	timestamp

3. User Roles

pos	column	null	dtype	len	default
1	user_id	No	int
2	role_id	No	int
3	assigned_at	No	timestamp		current_date

4. Administrations Table

pos	column	null	dtype	len	default
1	id	No	int		administration_id_seq
2	code	No	character varying	50
3	name	No	character varying	50
5	admin_level	Yes	int
7	created_at	No	timestamp		current_datetime
8	updated_at	Yes	timestamp

5. CDI Map Table

pos	column	null	dtype	len	default
1	id	No	int		cdi_map_id_seq
2	geonode_id	No	int
3	year_month	No	character varying	10
4	geotiff	No	character varying	255
5	geojson	No	character varying	255
6	published_geojson	Yes	character varying	255
7	published_at	Yes	timestamp
8	status	No	int	5
9	narrative	Yes	text
10	bulletin_url	Yes	character varying	255
11	created_at	No	timestamp		current_datetime
12	updated_at	Yes	timestamp

6. CDI Map Values Table

pos	column	null	dtype	len	default
1	id	No	int		cdi_map_id_seq
2	cdi_map_id	No	int
3	administration_id	No	int
4	initial_value	No	decimal
5	value	Yes	decimal
6	created_at	No	timestamp		current_datetime
7	updated_at	Yes	timestamp

7. Review Assignments Table

pos	column	null	dtype	len	default
1	id	No	int		review_assignments_id_seq
2	cdi_map_id	No	int
3	due_date	No	date
4	message	No	text
5	created_at	No	timestamp		current_datetime
6	updated_at	Yes	timestamp

8. Reviewers Table

pos	column	null	dtype	len	default
1	id	No	int		reviewers_id_seq
2	assignment_id	No	int
3	user_id	No	int
4	status	No	int
5	created_at	No	timestamp		current_datetime
6	updated_at	Yes	timestamp
7	approved_at	Yes	timestamp

9. Review  Table

pos	column	null	dtype	len	default
1	id	No	int		reviewers_id_seq
2	cdi_map_id	No	int
3	user_id	No	int
4	administration_id	No	int
5	value	Yes	decimal
6	comment	Yes	character varying	255
7	approved	Yes	boolean
8	created_at	No	timestamp		current_datetime
9	updated_at	Yes	timestamp

10. Feedback Table

pos	column	null	dtype	len	default
1	id	No	int		feedbacks_id_seq
2	user_id	Yes	int
3	message	No	text
4	name	No	character varying	100
5	email	No	character varying	100
6	tags	Yes	JSON
7	status	No	ENUM "New" "Reviewed" "Resolved"		New
8	submitted_at	No	timestamp		current_datetime

11. Jobs Table

pos	column	null	dtype	len	default
1	id	No	int		jobs_id_seq
2	task_id	No	character varying
3	user_id	No	int
4	type	No	int	5
5	status	No	int	5
6	attempt	Yes	int	5
7	result	No	JSON
8	info	Yes	character varying	255
9	created_at	No	timestamp
10	updated_at	Yes	timestamp

API Design

A. Classes & Utilities

A.1. Custom Pagination Class

Response Structure

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

Class Structure

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:

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

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

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

1.2. 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:

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

Response: 200 OK on success

1.3. 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

{
    "message": "OK"
}

1.4. 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:

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

Response: 200 OK on success

{
   "message": "Password reset successfully"
}

1.5. User Profile

Endpoint: GET /api/v1/users/me

JWT Access: Admin, Reviewer

Response: 200 OK on success

{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
}

2. Public API

2.1 List Map API

Endpoint: GET /api/v1/maps/

Request Params:

Name	Value	Description
start	YYYY-MM	Select start month
end	YYYY-MM	Select end month
compare	[]	Array of Map ID

Response: 200 OK on success

[
  "current": 1,
  "total_page": 5,
  "total": 99,
  "data": [
      {
        "id": 99,
        "geonode_id": 112,
        "year_month": "2024-12",
        "geojson": "/cdi/maps/published/2024-12-12.geojson",
        "published_at": "2024-12-12 08:10:10TZ",
      },
      ...
      {
        "id": 1,
        "geonode_id": 3,
        "year_month": "2024-01",
        "geojson": "/cdi/maps/published/2024-01-31.geojson",
        "published_at": "2024-01-31 12:10:10TZ",
      }
  ]
]

2.2 Details Map API

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

Response: 200 OK on success

{
    "id": 99,
    "geonode_id": 112,
    "year_month": "2024-12",
    "geojson": "/cdi/maps/published/2024-12-12.geojson",
    "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

Name	Value	Description
format	enum( GeoTIFF, CSV, GeoJSON)	Export format (e.g., GeoTIFF, CSV, GeoJSON).

Response: 200 OK on success

{
  "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:

{
    "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

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

3. Admin API

3.1 Create CDI Map Publication Request

Endpoint: POST /api/v1/admin/cdi-maps/ 

JWT Access: Admin

Request Body:

{
  "geonode_id": 222,
  "year_month": "2025-01",
  "geotiff": "https://example.geonode.com/datasets/geonode:cdi_2024_11_tiff/dataset_download",
  "geojson": "https://example.geonode.com/datasets/geonode:cdi_GEOJSON_2024_11_tiff/dataset_download",
}

Response: 200 OK on success

{
  "id": 100,
  "geonode_id": 150,
  "year_month": "2025-01",
  "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
  "geojson": "/cdi/maps/2025-01.geojson",
  "published_geojson": null,
  "published_at": null,
  "status": 1,
  "narrative": "",
  "bulletin_url": null
}

3.2 List CDI Map

Endpoint: GET /api/v1/admin/cdi-maps 

JWT Access: Admin

Request params:

Name	Value	Description
start	YYYY-MM	Select start month
end	YYYY-MM	Select end month
status	enum: 1 - Pending 2 - In Review 3 - In Validation 4 - Published	CDI Map Status

Response: 200 OK on success

[
  "current": 1,
  "total_page": 10,
  "total": 100,
  "data": [
      {
        "id": 100,
        "geonode_id": 150,
        "year_month": "2025-01",
        "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
        "geojson": "/cdi/maps/2025-01.geojson",
        "published_geojson": null,
        "published_at": null,
        "status": 1,
        "progress_review": "2/8"
      },
      ...
      {
        "id": 1,
        "geonode_id": 3,
        "year_month": "2024-01",
        "geojson": "/cdi/maps/2024-01.geojson",
        "published_geojson": "/cdi/maps/published/2024-01-31.geojson",
        "published_at": "2024-01-31 12:10:10TZ",
        "status": 4,
        "progress_review": 8/8"
      }
  ]
]

3.3 Details CDI Map for Admin

Endpoint: GET /api/v1/admin/cdi-map/{id} 

JWT Access: Admin

Response: 200 OK on success

{
  "id": 100,
  "geonode_id": 150,
  "year_month": "2025-01",
  "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
  "geojson": "/cdi/maps/2025-01.geojson",
  "published_geojson": null,
  "published_at": null,
  "status": 1,
  "narrative": "",
  "bulletin_url": null,
  "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 Details CDI Map Values for Admin

Endpoint: GET /api/v1/admin/cdi-map/{id}/values 

JWT Access: Admin

Response: 200 OK on success

[
  {
    "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 Send CDI Map Review Request

Endpoint: POST /api/v1/admin/cdi-map-review/ 

JWT Access: Admin

Request Body:

{
    "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",
    "cdi_map_id": 100,
}

Response: 200 OK on success

{
   "message": "Your review request has been sent successfully."
}

3.6 Submit validated value

Endpoint: POST /api/v1/admin/cdi-map/{id}/validated 

JWT Access: Admin

Request Body:

{
  "cdi_map_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"
    },
  ]
}

Response: 200 OK on success

{
  "id": 100,
  "geojson": "/cdi/map/2025-01-24.geojson",
  "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 

JWT Access: Admin

Request Body:

{
  "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",
}

Response: 200 OK on success

{
  "id": 100,
  "geonode_id": 150,
  "year_month": "2025-01",
  "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
  "geojson": "/cdi/maps/2025-01.geojson",
  "published_geojson": "/cdi/map/published/2025-01-29.geojson",
  "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 List CDI Map

Endpoint: GET /api/v1/reviewer/cdi-maps 

JWT Access: Reviewer

Request params:

Name	Value	Description
start	YYYY-MM	Select start month
end	YYYY-MM	Select end month
status	enum: 1 - Pending 2 - In Review 3 - In Validation 4 - Published	CDI Map Status

Response: 200 OK on success

[
  "current": 1,
  "total_page": 10,
  "total": 100,
  "data": [
      {
        "id": 61, 
        "cdi_map_id": 100,
        "year_month": "2025-01",
        "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
        "geojson": "/cdi/maps/2025-01.geojson",
        "published_geojson": null,
        "published_at": null,
        "status": 1,
        "progress_review": "2/8"
      },
      ...
      {
        "id": 1,
        "cdi_map_id": 10,
        "year_month": "2024-01",
        "geotiff": "/cdi/geotiff/cdi_2024-01.tif",
        "geojson": "/cdi/maps/2024-01.geojson",
        "published_geojson": "/cdi/maps/published/2024-01-31.geojson",
        "published_at": "2024-01-31 12:10:10TZ",
        "status": 4,
        "progress_review": 8/8"
      }
  ]
]

4.2 Details CDI Map for Reviewer

Endpoint: GET /api/v1/reviewer/cdi-map/{id} 

JWT Access: Reviewer

Response: 200 OK on success

{
  "id": 100,
  "geonode_id": 150,
  "year_month": "2025-01",
  "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
  "geojson": "/cdi/maps/2025-01.geojson",
  "status": 1,
  "updated_at": "2025-01-19 18:22:00TZ",
  "approved_at": null,
}

4.3 Details CDI Map values for Reviewer

Endpoint: GET /api/v1/reviewer/cdi-map/{id}/values 

JWT Access: Reviewer

Response: 200 OK on success

[
  {
    "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/cdi-map/{id}/values 

JWT Access: Reviewer

Request Body:

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

Response: 201 Created on success

{
  "id": 811,
  "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/cdi-map/{id}/value/{value_id} 

JWT Access: Reviewer

Request Body:

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

Response: 200 OK on success

{
  "id": 811,
  "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/cdi-map/{id} 

JWT Access: Reviewer

Response: 200 OK on success

{
  "id": 61,
  "cdi_map_id": 100,
  "year_month": "2025-01",
  "geotiff": "/cdi/geotiff/cdi_2025-01.tif",
  "geojson": "/cdi/maps/2025-01.geojson",
  "status": 2,
  "updated_at": "2025-01-19 18:22:00TZ",
  "approved_at": "2025-01-20 10:31:01TZ",
}

5. Settings API

5.1 Technical Support Contacts

Endpoint: GET /api/v1/settings/tsc

JWT Access: Admin

Response: 200 OK on success

{
  "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

JWT Access: Admin

Response: 200 OK on success

{
  "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

Message Type	Message Detail
Data is Missing	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
Error	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

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 drf-yasg 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., /api/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.org).

DBDocs

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

• Schema Generation:
  • Use tools like DBML (Database Markup Language) or SQL export 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 DBDocs (e.g., https://dbdocs.io/eswatini-droughtmap-hub).
  • Link the schema documentation in the Read the Docs and Swagger UI for centralized access.