Table of contents

Project Overview

Husika is an early warning system prototype focusing on efficient communication between civil servants and communities in the Horn of Africa region. The system enables civil servants to validate raw threat information and create broadcasts to inform communities about potential hazards, while collecting structured feedback from recipients.

Project Goals (Govstack)

1. Create Blueprint and Foundation:

   • Build a working example solution for Husika

   • Serve as foundation for future GovStack cases

   • Build reusable technical components

   • Support similar initiatives in the future

   • Demonstrate practical implementation

   • Provide foundation for Husika 2.0

2. Enable ICPAC and Bunifu:

   • Improve positive impact through early warnings

   • Build reliable warning system

   • Reach target audience effectively (citizens in HoA)

System Goals (Husika Platform)

Core Objectives:

1. Enable civil servants to monitor threats effectively

2. Facilitate clear communication about potential hazards

3. Collect and organize community responses

4. Support multi-language broadcasts

Key Functionalities:

1. Threat monitoring and validation

2. Structured broadcast creation

3. Response collection

4. Jurisdiction-based access control

Timeline & Team Activity Resources

Timeline

...

Architectural Workshop

On 22 Aug 2024 and 08 Sep 2024 we had two architectural workshops with the following goals:

...

The workshop material and results can be found here:

...

Initial Challenges

1. Research & Documentation Gaps

• There's a need for foundational user research

• Initial documentation could use some improvement

• It would be great to have a clearly defined scope

2. User & System Structure

• User personas are still undefined

• Role definitions could be clearer

• Jurisdictional requirements are a bit complicated

3. Design & Interface

• We don't have established design patterns yet

• We're starting from the ground up

• It's important to handle complex processes intuitively

• Multi-language support is a requirement

4. Communication Flow

• A structured approach to broadcast creation would be helpful

• Systematic feedback collection is needed

• Implementing a clear threat monitoring system is essential

Methodology

With limited time and resources, our approach focused on quickly capturing essential functionalities and user needs, using an agile, iterative workflow.

Essential steps of GovStack methodology had to be skipped for this demo application due to resource and time constraints, i.e. As-Is User Journey, To-Be User Journey and Service Blueprint. What we managed to accomplish during research and design phase:

Market Research

To further inform our design decisions and contextualize our project within the broader industry landscape, we conducted a quick market analysis of multi-hazard early warning systems. This research provided valuable insights into current best practices, user expectations, and feature sets in similar solutions, which helped shape our approach.

Direct BPMN Model Creation

We initiated the project by developing a Business Process Model and Notation (BPMN) model to map out the system's core workflows. This decision stemmed from our need to quickly visualize the structure of the system, given the time constraints. Our BPMN model was based on initial customer meetings, assumptions, and available documents. Since we couldn't access the existing system directly, we leveraged screenshots from their presentations to understand the current flow and identify gaps.

Wireframe Development and Ideation

After establishing the BPMN model, we transitioned to the ideation phase to create initial wireframes. Throughout this phase, we worked closely with the development team to verify that our design ideas aligned with technical constraints and current capabilities. This frequent communication allowed us to iterate rapidly, ensuring that our designs were both practical and aligned with the project's technical requirements.

Prototype Creation and Iteration

After refining our wireframes based on feedback from stakeholders and technical input, we developed the first prototype. This prototype embodied the initial assumptions and evolved requirements, serving as the foundation for further testing and validation.

Design Solutions

Clear Information Structure:

• Dashboard with key metrics

• Recent threats overview

• Broadcast creation and tracking

• Response collection and organization

User-Focused Approach:

• Intuitive navigation

• Step-by-step broadcast creation

• Clear status indicators

• Easy access to critical information

Communication Tools:

• Template-based broadcast creation

• Multi-language support

• Structured response options

• Clear feedback organization

Key Design Decisions

Decision 1: Use of MUI (Material-UI) for Component Library

Context and Challenge

https://mui.com/

Given the project's tight timeline, we needed to streamline the design and development process as much as possible. Although a custom component library would allow for more tailored, case-specific design solutions, building this from scratch would require extensive time and resources.

Solution and Rationale

To expedite the design process without compromising functionality, we decided to use MUI (Material-UI) as our component library. MUI offers ready-made set of components that adhere to industry-standard Material Design principles. This choice provided a balance between speed and design quality, allowing us to focus more on flow and usability rather than component creation.

Impact on Flow and Users

Using MUI significantly reduced development time and ensured consistency in the UI. While custom components would offer greater design specificity, MUI allowed us to achieve a professional and polished interface that meets general user experience standards. This decision, however, may require customization or future adjustments to better align with case-specific needs as the project matures.

Decision 2: Limiting User Layers for Prototype

Context and Challenge

The original system had multiple user roles and complex hierarchies. For the prototype, we needed to simplify the user structure while maintaining core functionality.

Solution and Rationale

We limited the system to two primary user types:

• Administrators (civil servants managing the system and working based on the jurisdiction)

• Recipients (people receiving broadcast messages)
  This simplified approach allows us to focus on core functionalities and user flows without getting caught in complex role management. In addition, due to lack of documentation regarding various role this approach would be optimum solution within our limited time.

Impact on Flow and Users

This decision dramatically simplified the user experience and development process, allowing us to focus on the core interactions between administrators and recipients. While this may need expansion in future versions, it provides a solid foundation for testing and validating the main system concepts.

Decision 3: New Flow

Context and Challenge

Starting from scratch, we needed to create intuitive user flows that would make complex emergency communication processes manageable and effective.

Solution and Rationale

We developed a streamlined flow focusing on two main areas:

• Threat monitoring and validation

• Broadcast creation and distribution while collecting responses
  Each area was designed with clear steps and logical progression, minimizing confusion and user error.

Impact on Flow and Users

The new flow provides a clear path for users to follow, making complex tasks more manageable. It reduces cognitive load while ensuring all necessary steps are completed in the right order.

Decision 4: New Terminology

Context and Challenge

Clear communication required consistent, understandable terminology that accurately reflected system functions while avoiding confusion.

Solution and Rationale

We developed a simplified terminology framework. These terms were chosen for clarity and directness, avoiding technical jargon.

• "Threats" for potential hazards being monitored

  • Threat: Raw information regarding a warning or potential hazard. This is what admins (civil servants) see and use to create broadcasts. 

• "Broadcasts" for communications sent to recipients

  • Broadcast: Information that is shared with a group of end-users. These are created based on threats and distributed to affected people.

• "Feedbacks" for responses

  • Feedbacks: Messages received in response to broadcasts or about ongoing situations. We have two primary different Feedback.

    • Feedback to ICPAC: which is mainly responses conducted for validation purposes towards threat.

    • Feedback to Broadcast: which is responses that is collected through the broadcast.

Impact on Flow and Users

Consistent terminology helps users quickly understand system functions and reduces confusion. It provides a common language for all users while maintaining professional standards. Used terminologies should be clearly documented also for the future.

Decision 5: Quantitative and Qualitative Feedback Collection System

Context and Challenge

The system needed to collect both structured and unstructured feedback from recipients of broadcasts. We needed a way to gather quantifiable data for quick analysis and validations while also allowing for detailed, contextual information from the community.

Solution and Rationale

We implemented a two-tier response system:

1. Validate Status: Simple Yes/No responses for quick, quantifiable feedback

2. General Response: Open-text format for detailed information
   This approach allows for both statistical analysis and rich, contextual feedback while keeping the response mechanism simple for end-users.

Impact on Flow and Users

This decision simplified data collection and analysis while maintaining flexibility in feedback gathering. The validate status option provides immediate, measurable insights, while the general response option allows for more detailed community input when needed.

Decision 6: Jurisdiction-Based Access Control

Context and Challenge

Users needed to see threats across multiple locations for better situational awareness, but broadcast capabilities needed to be restricted to appropriate jurisdictional areas to maintain proper authority structures and prevent unauthorized communications.

Solution and Rationale

We implemented a hybrid approach where:

• Threats are visible across multiple locations

• Broadcast capabilities are restricted to user's jurisdiction

• Clear indication of jurisdictional limitations in the interface
  This balanced the need for widespread threat awareness with controlled communication channels.

Impact on Flow and Users

This approach provides users with comprehensive threat visibility while maintaining appropriate control over broadcast creation. The clear distinction between viewing and action capabilities helps users understand their roles and responsibilities within the system.

Decision 7: Template-Based Broadcast Creation

Context and Challenge

Creating effective emergency communications requires consistency in messaging while allowing for situation-specific details. We needed to balance standardization with flexibility in broadcast creation.

Solution and Rationale

We implemented a template system for broadcasts that:

• Provides pre-structured formats

• Allows for customization

• Supports multiple languages

• Includes specific response collection options
  This approach ensures consistency in communication while maintaining flexibility for different situations.

Impact on Flow and Users

Templates streamline the broadcast creation process while ensuring important information isn't overlooked. This makes the system more efficient for civil servants while maintaining message quality and effectiveness.

Key Technical Decisions

#1 (Micro)service-based architecture according to GovStack Building Blocks

The (micro)service-based architecture of GovStack is designed to enhance the modularity, scalability, and interoperability of digital government services. This architecture is structured around specific building blocks that facilitate efficient service delivery. The GovStack Building Block specifications can be found here.

Advantages of the Architecture

• Modularity: Each service can be developed, deployed, and scaled independently, allowing for rapid updates and maintenance.

• Interoperability: Services can easily communicate and share data, promoting collaboration across different government platforms.

• Scalability: The architecture supports scaling services based on demand, optimizing resource utilization and enhancing performance.

Implementation Considerations

• Governance: Establish clear guidelines for service development and integration to ensure compliance with standards.

• Monitoring and Maintenance: Implement tools for monitoring service performance and health to quickly address issues.

• User Feedback: Incorporate mechanisms for collecting user feedback to continuously improve services.

This architecture not only supports the immediate goals of the GovStack initiative but also lays the groundwork for future innovations in digital governance, ensuring that services remain relevant and effective in meeting the needs of citizens. For more detailed specifications, you can refer to the GovStack Building Blocks documentation.

#2 Software choice for Messaging Building Block: RapidPro

RapidPro is a robust messaging platform chosen as a software option for the Messaging Building Block within the GovStack framework. It is designed to facilitate effective communication between government services and citizens, enabling timely and relevant interactions.

...

RapidPro is acting as a GovStack building block software, meaning it is a modular solution designed to be reused across different government services and digital infrastructure projects. It has the potential to be leveraged in various GovStack implementations to streamline communication, citizen engagement, and service delivery across digital platforms.

RapidPro SaaS offerings:

• RapidPro (UNICEF)

• TextIt - The Leading Bot Platform

RapidPro deployment experience:

We explored three different approaches:

...

The RapidPro team suggested adjusting the database connection pool, but this solution is problematic.
It requires us to decompose the application, dive into the source code, and have a deep understanding of the internal workings of the system.

#3 Software choice for Information Mediator Building Block: Kafka

Kafka is a powerful distributed event streaming platform selected for the Information Mediator Building Block within the GovStack framework. It is designed to facilitate the seamless exchange of data between various services, ensuring interoperability and efficient data flow.

#4 Software choice for Registry Building Block: Postgres (over Baserow)

PostgreSQL, commonly known as Postgres, is the chosen database management system for the Registry Building Block within the GovStack framework. It is favored for its robustness, flexibility, and advanced features that support the complex data requirements of digital government services.

Further information on initial Baserow investigation, conducted by Vuk Damjanovic

Overall findings
Baserow as a standalone database/storage/registry solution is excellent. It provides a package of technologies combined in a way that allows non technical person to manage databases on their own in a, somewhat, intuitive way. The advantage of the Baserow over a traditional database is the UI, and package of technologies ready to cover various data storage scenarios out of the box using Docker or Helm charts.

...

investigate if running migration scripts is possible → No feasible due to too complex structure of the tables. In order to create one table with three columns and three values using conventional SQL language (which is used in migration files run with liquibase) it’s needed to cover over 15+ tables. Inserting one field in the table requires inserting data into more than 10 tables.

#5 Frontend technology of choice: React with Material UI

React, a popular JavaScript library for building user interfaces, is the chosen frontend technology for the demo. When paired with Material UI, a robust component library that implements Google’s Material Design, it provides a powerful framework for creating responsive and visually appealing applications.

...

• Pre-Built Components: Material UI offers a wide range of pre-designed components, such as buttons, forms, and navigation elements, which adhere to Material Design principles. This accelerates development and ensures consistency across the application.

• Customizability: While providing a solid design foundation, Material UI allows for extensive customization, enabling developers to tailor components to meet specific branding and functional requirements.

• Responsive Design: The library supports responsive layouts, ensuring that applications look great on various devices, from desktops to mobile phones.

#6 Backend technology of choice: Java Spring Boot

Java Spring Boot is the selected backend technology for the demo, chosen for its robustness, flexibility, and ability to streamline the development of microservices. It simplifies the process of building production-ready applications by providing a comprehensive framework that integrates various components seamlessly.

Java Spring Boot is an ideal choice for the backend of the GovStack architecture due to its ease of use, scalability, and strong community support. Its capabilities align well with the goals of the initiative, enabling the development of efficient, secure, and maintainable digital government services that can adapt to evolving needs.

Technical Documentation

BPMN

Demo BPMN (v1.6, reflecting the final demo application):

...

For reference, this was the originally envisioned BPMN (v1.1) for the demo:

GitHub repositories

The repositories can be accessed here:

How to up and run the demo locally

Prerequisites: node and yarn and docker

Backend services

(for each service)

1. up and run docker

2. create a new network in Docker using the command docker network create shared_network

3. up and run Information mediator using the docker file

4. clone/Download each service in a new folder (if downloaded, unzip the folder)

5. start each service by opening the service folder in a new terminal

6. run the command docker-compose up --build

Frontend

1. once backend services are running, clone the frontend repository

2. open a terminal and open on it the root folder of the frontend repository

3. copy the .env.example  to .env. This can be done with this command:

   • cp .env.example .env

4. verify that the values in .env are correct. They will be if they haven't modified anything while starting the microservices.

5. next step is to install the frontend dependencies. this can be done, again with the terminal and again in the root folder, by executing this command: yarn install

6. after all of this, they are ready to start the project. to do that they can, again in root folder and with the terminal, run this command: yarn dev

7. once they have ran that command, they can open their browser and open the url http://localhost:3000/

8. this will open the login page, default credentials are:

   • user: firstUser@test.com

   • password: asdf1234

Something similar is mentioned in frontend's readme: https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-frontend/blob/main/README.md

Port mapping

Database Schema

Threat Table

Broadcast Table

Country Threat Table

County Country Table

Flow & Key Functionalities

This section outlines the core user flows and key functional capabilities of the Husika early warning system, as envisioned in the Figma design mockups.

...

Figma Documentation:

...

Core User Flows

The three core user flows are described in detail below, based on the Figma designs:

Threat Monitoring

Design:

• The Threat Monitoring functionality is accessible from multiple entry points in the system:

  • The Dashboard provides an overview of active and high-priority threats, which users can click through to access the full Threats view.

  • The Threats page serves as the central hub for monitoring and managing threats, offering a comprehensive tabular listing.

• On the Threats page, users can view all threats across their jurisdiction but also other areas too, Users can see:

  • The threats list based on criteria such as threat status, location, severity, and more.

  • Quickly identify high-priority threats through visual cues like color-coded severity indicators.

• The threats table includes the location information for each threat, displayed with an icon to indicate whether the threat is within the user's jurisdiction or outside of it.

• Clicking on a specific threat in the Threats list opens the Threat Details view, which includes:

  • A map-based visualization showing the geographic location of the threat.

  • A timeline of events and associated metadata for the threat.

  • The ability for users to submit structured feedback to the ICPAC (IGAD Climate Prediction and Applications Centre) through a dedicated feedback form.

...

• For the prototype, the Threat Monitoring functionality is limited to only the Kenya jurisdiction.

• The "See other affected Locations" section on the Threat Details page is not implemented in the current prototype.

• The map visualization on the Threat Details page is a placeholder and does not reflect the actual geographic location of the threat. The map functionality is not implemented in the prototype.

Broadcasting

Design:

• The Broadcasting flow enables users to create and send alerts to their stakeholders such as citizens or organizations.

• The broadcast creation process is divided into three steps:

  1. Configuration: Users select the communication channels (email, SMS, WhatsApp, Telegram), target languages, and recipients.

     1. Recipients can be Whole population within Jurisdiction

     2. Organizations within Jurisdiction

     3. Or custom recipients, such as certain user group that is created beforehand. (pastoralist within certain area)

  2. Content Creation: Users craft the broadcast message, optionally select a pre-made template, and configure response options (validation, general feedback or none).

  3. Preview & Review: Users review the broadcast details, estimated reach, and content preview before finalizing and sending the broadcast.

• The broadcast creation interface supports multi-language editing and file attachments.

• Users can track the status of their broadcasts (draft, processing, sent, failed) in the Broadcasts page.

...

• For the prototype, only the SMS channel is implemented for broadcasting. Other communication channels like email, WhatsApp, and Telegram are not available.

• The prototype supports only two languages for broadcast content: English and Swahili. Additional language options are not implemented.

• The prototype limits the broadcast recipients to only the population within the user's jurisdiction. Functionality for selecting custom recipient groups or organizations is not implemented.

• The broadcast creation process includes the "Validate Status" response option, but the "Estimated reach" section is a placeholder and does not display actual reach estimates.

• The template-based broadcast creation functionality described in the design is not implemented in the prototype.

• Within the Quick Action, Create Broadcast button on the Dashboard and broadcasts page does not actually initiate the broadcast creation flow.

• The success dialog or confirmation screen after sending a broadcast is not implemented in the current prototype.

Feedback Collection

Design:

• The Feedback Collection flow supports two main feedback channels:

  1. Threat Feedback to ICPAC:

     • From the Threat Details page, users can submit structured feedback to the IGAD Climate Prediction and Applications Centre (ICPAC) regarding a specific threat.

     • This feedback is focused on the threat details, accuracy, and other relevant information.

  2. Broadcast Feedback:

     • The Feedback page provides a comprehensive list of all responses and feedback received for the user's broadcasts.

     • There are two types of broadcast feedback: a. Validation Responses: Structured feedback from recipients about the accuracy and relevance of the broadcast content. b. General Responses: Free-form feedback and comments from recipients.

• Administrators can view analytics on the validation responses, including visual representations of the feedback data.

• Users can also submit their own administrative feedback about a broadcast, which is tracked separately from the recipient responses.

...

• The feedback collection functionality described in the design is not implemented at all in the current prototype. Users are unable to submit feedback to ICPAC regarding threats or provide feedback on broadcasts through Rapidpro.

Key Features

Dashboard

Design:

• The Dashboard provides users with a high-level overview of the key metrics and activities within the early warning system.

• The dashboard includes the following sections:

  • Threats: Displays the number of active threats and high-priority threats across the user's jurisdiction.

  • Broadcasts: Shows the number of broadcasts that have been sent and are currently pending.

  • Feedbacks: Indicates the total number of received feedbacks and the number of feedbacks received today.

• Each of these overview sections can be clicked to navigate to the corresponding detailed view (Threats, Broadcasts, Feedbacks).

• The Dashboard also includes a "Recent Threats" section, which lists the most recent threats within the user's jurisdiction. This section provides a quick snapshot of the current threat landscape.

• Users can easily access key actions from the Dashboard, such as creating a new broadcast.

...

• The "Latest Broadcasts" section on the Dashboard is not clickable in the current prototype. Users cannot navigate to the Broadcasts page from this section.

• The "Quick Actions/New Broadcast" button on the Dashboard does not initiate the broadcast creation flow as described in the design. This functionality is not implemented in the prototype.

• The banner numbers displayed on the sidebar (for Threats, Broadcasts, and Feedbacks) are placeholder values and do not reflect the actual real-time data in the system.

Threat Details

Design:

• The Threat Details page provides a comprehensive view of a specific threat, accessible by clicking on a threat from the Threats list.

• The page includes the following key elements:

  • Location: A map visualization showing the geographic area affected by the threat, with clear indication of the user's jurisdiction.

  • Threat Details: Detailed information about the threat, including type, severity, period, and associated metadata.

  • History Timeline: A chronological timeline of events related to the threat, from when it was first created to its current status.

  • ICPAC Feedback: A dedicated section where users can submit structured feedback to the IGAD Climate Prediction and Applications Centre (ICPAC) regarding the threat.

• Broadcast List: A table displaying all broadcasts that have been created in relation to the selected threat. This includes:

  • Title of the broadcast

  • Language of the broadcast content

  • Communication channel used (e.g., Telegram)

  • Date the broadcast was sent

  • Status indicators (e.g., Sent, Processing)

• Users can easily navigate back to the Threats list or access other core functionalities like creating a new broadcast from the Threat Details page.

• The page layout and design provide a clear, comprehensive view of the threat and associated broadcasts to support effective monitoring and response.

...

• The Threat History timeline displayed on the Threat Details page is a placeholder and does not reflect the actual chronological events related to the threat.

• The "Other Affected Locations" section, which was mentioned in the design, is not implemented in the current prototype.

• The map visualization on the Threat Details page is a placeholder and does not show the actual geographic location of the threat. The map functionality is not fully implemented.

Broadcast Creation

Design:

• The broadcast creation functionality allows users to create, send, and track the feedbacks for their broadcasts.

• The broadcast creation process is divided into three main steps:

  1. Configuration:

     • Users select the communication channels they want to use, such as email, SMS, WhatsApp, and Telegram.

     • They can select and edit the target languages.

  2. Content Creation:

     • Users craft the broadcast message, with the option to select a pre-made template.

     • They can configure the type of response they want to receive, such as validation responses or general feedback.

  3. Preview & Review:

     • Users can review the details of the broadcast, including the estimated reach.

     • They have the opportunity to preview the content in the selected languages before finalizing and sending the broadcast.

• Once a broadcast is sent, users can track its status (e.g., draft, processing, sent, failed) on the Broadcasts page.

• The broadcast creation interface supports features like multi-language editing and file attachments to enhance the communication capabilities.

• User can also track Feedbacks related to the broadcast through here.

...

Implementation Notes:

• Please check: https://govstack-global.atlassian.net/wiki/spaces/DEMO/pages/919764994/Husika+Hando-over+x+GovStack+Sandbox+Demo+handover+documentation#BroadcastingBroadcasting/implementation notes section.

...

Feedbacks

Design:

• The system provides comprehensive feedback management capabilities, supporting two distinct feedback channels:

...

Implementation Notes:

Please check https://govstack-global.atlassian.net/wiki/spaces/DEMO/pages/919764994/Husika+Hando-over+x+GovStack+Sandbox+Demo+handover+documentation#Feedback-Collection Feedback collection- Implementation notes section.

Lessons Learned

Starting with clear documentation and importance of user research etc.

Critical Considerations for Future Development

1. User Research Imperatives

   • Conduct comprehensive user interviews and observations

   • Develop detailed user personas

   • Map user journeys across different scenarios

   • Understand contextual use cases in different regions

   • Analyze user pain points and needs systematically

   • Research local communication preferences and patterns

2. Service Design Requirements

   • Develop detailed service blueprints

   • Map end-to-end service interactions

   • Create comprehensive stakeholder maps

   • Identify all touchpoints in the service journey

   • Design for service scalability

   • Consider offline and online service components

   • Plan for service maintenance and support

3. Design Process Recommendations

   • Implement proper discovery phase

   • Conduct usability testing

   • Create prototype testing plan

   • Develop measurement metrics for success

   • Plan for iterative improvements

   • Document design decisions and rationales

4. Contextual Considerations

   • Research local infrastructure limitations

   • Understand cultural communication norms

   • Study existing emergency response systems

   • Analyze regional technology adoption patterns

   • Consider accessibility needs

   • Research local language nuances

5. Stakeholder Engagement

   • Plan regular stakeholder workshops

   • Create feedback collection mechanisms

   • Establish clear communication channels

   • Develop stakeholder engagement strategy

   • Plan for continuous stakeholder input

   • Document stakeholder requirements systematically

6. Responsive Designs

   1. Mobile integration

...