from

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:

  2. Enable ICPAC and Bunifu:

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

image-20241107-094800.png

Architectural Workshop

On and we had two architectural workshops with the following goals:

The workshop material and results can be found here:

https://www.figma.com/board/Fjduw0yzzvrSuczncQNdyG/Architectural-Workshop?node-id=380-516&t=zesoubbYSWUCBws2-4

Initial Challenges

1. Research & Documentation Gaps

2. User & System Structure

3. Design & Interface

4. Communication Flow

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:

User-Focused Approach:

Communication Tools:

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:

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:

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.

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:

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:

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

Implementation Considerations

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 an open-source platform developed by UNICEF that enables users to design, scale, and manage communication workflows using channels like SMS, Telegram, and WhatsApp. It provides a user-friendly, visual interface for building interactive messaging services, widely used in sectors like health, education, and disaster response. Key features include flow creation, contact management, real-time analytics, and multi-channel communication.

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 deployment experience:

We explored three different approaches:

  1. Deploying the app on a bare virtual privet server or personal laptop: This involved manually installing all dependencies, but it failed due to dependency conflicts and difficulties of managing/cleaning dependencies.

  2. Creating custom Kubernetes manifests: We attempted to build our own manifests based on the provided Dockerfiles. However, this approach also failed because some internal variables were hardcoded, making it impossible to override them externally. Potential work require good internal knowledge of the system.

  3. Using the provided docker-compose file (intended for development): Initially, it seemed to work, but when we started integrating it with our system, it failed.

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.

Mentioning Docker and Helm charts, Docker is a preferred way for deployment. Both official instructions and hands on experience are heavily leaning toward Docker as a preferred deployment approach. Helm charts are an alternative, however, not an easy one. In order to up and run Baserow with Helm charts, official chart and instructions were not sufficient to achieve this. In order to make it up and running we had to resort to a chart made by a different user, on top of that the amount of time and people involved in this process was substantially higher compared to the Docker approach.

Going outside of the scope of the standalone approach makes Baserow quite complicated to work. If the goal of the Baserow is to be used as an alternative to the traditional open-source databases (like PostgreSQL/MySQL), it seems like an over-engineered approach and there's no clear benefit that would cover for the amount of work needed to make Baserow to do what a simple instance of a traditional DB would do. Moreover, mentioned traditional technologies combined with open-source DB UI client (DBeaver Community for example) covers 80% of the Baserow benefits. The only loss is that user isn’t really able to use it as easy as Baserow without having SQL knowledge.

One of technologies within the Baserow is a PostgreSQL instance.
Baserow is adding a lot of abstractions on top of it, and working with it it’s like working with a black box. These are additional hoops needed to be jumped trough in order to make Baserow do what a traditional DB is doing from a development point of view.
For instance, connecting Baserow with a SpringBoot app (or something even more complicated like X-Road) takes massive amount of time, it’s more verbose and it’s quite prone to errors and potential issues which are not the case with conventional DBs. When using Baserow trough UI there's many automated actions that are happening in the background, which are needed to be executed manually in sequence when working with Baserow via APIs.
To wrap up the overall view on the Baserow, it’s excellent as a standalone product, but not that good (over-engineered)as a traditional DB for the same purpose.

Suitable for production Husika?
Suitable for POC demo from GoFore?

I would say no. What Husika is currently using (MySQL) and what is expected from the production DB, traditional DBs are more suitable in this case. We could make Baserow to do what a conventional DB does and make Baserow to be a go-to solution for Husika, but with a massive investment of time and effort which seems unnecessary and could be a potential waste of time which we need in other areas. In terms of POC, still the traditional DB solves all our problems. Of course, if it’s absolutely a must to use Baserow to follow the philosophy of using the mentioned GovStack BBs then we can do it, but with the mentioned costs from above.

Additional note

There’s a possibility to run Baserow in a way that each technology inside of it can be run as a separate container. This opens potential capability of reusing them in a way it would suit us. For example, use the PostgreSQL and Redis directly as a standalone app within the Baserow. However, this is something that has to be tested and confirmed if it works this way.

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.

Key Features

Material UI Integration

#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

Architecture diagram

BPMN

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

20241116-bpmn-1.6.png

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

GitHub repositories

The repositories can be accessed here:

Service

GitHub Repository

threat service

https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-threatservice

user service

https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-userservice

data ingestion service

https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-dataingestionservice

communication service

https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-communicationservice

frontend app

https://github.com/GovStackWorkingGroup/sandbox-usecase-earlywarning-frontend

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:

  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:

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

Port mapping

Service

Port

User service

8080

Threat service

8081

Communication

8082

Data ingestion

8083

Information mediator

Connected to services on 29092

Database Schema

Threat Table

Name

Type

Description

id

BIGINT

Primary key, auto-incremented.

threatUUID

UUID

Unique identifier for the threat.

type

VARCHAR(255)

Type of the threat.

severity

VARCHAR(255)

Severity level of the threat.

range

VARCHAR(255)

Range of the threat.

notes

VARCHAR(255)

Additional notes about the threat.

periodStart

TIMESTAMP

Start time of the threat period.

periodEnd

TIMESTAMP

End time of the threat period.

createdAt

TIMESTAMP

Timestamp when the threat was created.

Broadcast Table

Name

Type

Description

id

BIGINT

Primary key, auto-incremented.

broadcastUUID

UUID

Unique identifier for the broadcast.

threat_id

BIGINT

Foreign key referencing the threat table.

title

VARCHAR(255)

Title of the broadcast.

status

VARCHAR(255)

Status of the broadcast. DRAFT, PUBLISHED

notes

VARCHAR(255)

Additional notes about the broadcast.

englishMsg

TEXT

Message in English.

swahiliMsg

TEXT

Message in Swahili.

createdAt

TIMESTAMP

Timestamp when the broadcast was created.

initiated

TIMESTAMP

Timestamp when the broadcast was initiated.

Country Threat Table

Name

Type

Description

id

BIGINT

Primary key, auto-incremented.

threat_id

BIGINT

Foreign key referencing the threat table.

countryId

BIGINT

Identifier for the country.

countryName

VARCHAR(255)

Name of the country.

County Country Table

Name

Type

Description

id

BIGINT

Primary key, auto-incremented.

country_threat_id

BIGINT

Foreign key referencing the country_threat table.

countyId

BIGINT

Identifier for the county.

countyName

VARCHAR(255)

Name of the county.

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.

The system is designed to support three primary user flows:

  1. Threat Monitoring

  2. Broadcasting

  3. Feedback Collection

These flows are supported by a set of integrated features and an information architecture that enables users to effectively manage threats, communicate with stakeholders, and collect valuable feedback.

In the following sections documenting the core user flows and key features, the design details are based on the Figma mockups provided. However, it's important to note that the actual implemented functionality of the Husika early warning system may differ from the Figma designs.

To capture these differences accurately, each subsection will include an "Implementation Notes" area where the specific variations between the design and the live system will be documented. This approach ensures the documentation reflects the current state of the implemented system, while also preserving the original design intent as envisioned in the Figma prototypes.

Figma Documentation:

https://www.figma.com/design/IgZ8v70JKM7okPHFE8rl0l/MHEWS?node-id=69-4253&t=tWUTyCRjSXJvO11I-1

Core User Flows

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

Threat Monitoring

Design:

Example Flow/Visualization:

image-20241112-124921.png

Implementation Notes:

Broadcasting

Design:

Example Flow/Visualization:

image-20241112-132232.png

Implementation Notes:

Feedback Collection

Design:

Example Flow/Visualization:

Feedback to Icpac Flow:

image-20241112-145518.png

Broadcast Feedbacks:

image-20241112-145355.png

Implementation Notes:

Key Features

Dashboard

Design:

Visualization:

image-20241112-132638.png

Implementation Notes:

Threat Details

Design:

Visualization:

image-20241112-132927.png

Implementation Notes:

Broadcast Creation

Design:

note

Template name: [Validation] Urgent Flood Alert - Short (WhatsApp or Telegram)

Content:

English:

🚨 FLOOD ALERT STATUS CHECK Is your area experiencing flooding?

  • Rising water level

  • Flooded roads or buildings

  • Overflow from rivers

Please respond: YES - if you observe any of these conditions NO - if your area is currently unaffected


(Google Translate)Swahili:

🚨 TAARIFA YA HALI YA MAFURIKO

Je, eneo lako linaathiriwa na mafuriko?

  • Kiwango cha maji kinapanda

  • Barabara au majengo yamefurika

  • Mafuriko kutoka kwenye mito

Tafadhali jibu: YES - ikiwa unaona mojawapo ya hali hizi NO - ikiwa eneo lako halijaathirika kwa sasa

Template name: [Validation] Urgent Flood Alert - Short (WhatsApp or Telegram)

Content:

English:

🚨 FLOOD ALERT STATUS CHECK Is your area experiencing flooding?

  • Rising water level

  • Flooded roads or buildings

  • Overflow from rivers

Please respond: YES - if you observe any of these conditions NO - if your area is currently unaffected


(Google Translate)Swahili:

🚨 TAARIFA YA HALI YA MAFURIKO

Je, eneo lako linaathiriwa na mafuriko?

  • Kiwango cha maji kinapanda

  • Barabara au majengo yamefurika

  • Mafuriko kutoka kwenye mito

Tafadhali jibu: YES - ikiwa unaona mojawapo ya hali hizi NO - ikiwa eneo lako halijaathirika kwa sasa

note

Template name: [Validation] Urgent Drought Alert - Short (WhatsApp or Telegram)

Content:

English:

🚨 DROUGHT STATUS CHECK

Is your area experiencing water shortage?

  • Dry water sources

  • Limited drinking water

  • Non-functioning water points

Please respond: YES - if your area is affected NO - if your area has water supply


Swahili version:

🚨 TAARIFA YA HALI YA UKAME

Je, eneo lako lina uhaba wa maji?

  • Vyanzo vya maji vimekauka

  • Maji ya kunywa ni haba

  • Vituo vya maji havifanyi kazi

Tafadhali jibu: YES - ikiwa eneo lako limeathirika NO - ikiwa eneo lako lina maji

Template name: [Validation] Urgent Drought Alert - Short (WhatsApp or Telegram)

Content:

English:

🚨 DROUGHT STATUS CHECK

Is your area experiencing water shortage?

  • Dry water sources

  • Limited drinking water

  • Non-functioning water points

Please respond: YES - if your area is affected NO - if your area has water supply


Swahili version:

🚨 TAARIFA YA HALI YA UKAME

Je, eneo lako lina uhaba wa maji?

  • Vyanzo vya maji vimekauka

  • Maji ya kunywa ni haba

  • Vituo vya maji havifanyi kazi

Tafadhali jibu: YES - ikiwa eneo lako limeathirika NO - ikiwa eneo lako lina maji

note

Template name: [General Response] Urgent Flood Alert - Short (WhatsApp or Telegram)

Content:

English:

Due to rising water levels, immediate action required:

SAFETY INSTRUCTIONS:

  • Move to higher ground

  • Avoid crossing flooded areas

  • Stay away from rivers and streams

  • Use designated evacuation routes

EVACUATION CENTERS: [Location 1] [Location 2] [Location 3]

📞 Emergency Contact: [NUMBER]

Please reply with your current situation or any urgent needs.


Swahili version:

🚨 TAADHARI YA MAFURIKO - [ENEO]

Kutokana na kupanda kwa kiwango cha maji, hatua za haraka zinahitajika:

MAAGIZO YA USALAMA:

  • Nenda maeneo ya juu

  • Epuka kuvuka maeneo yaliyofurika

  • Kaa mbali na mito na vijito

  • Tumia njia zilizotengwa za kuondoka

VITUO VYA KIMBILIO: [Eneo la 1] [Eneo la 2] [Eneo la 3]

📞 Nambari ya Dharura: [NAMBARI]

Tafadhali tuma ujumbe kuhusu hali yako ya sasa au mahitaji yoyote ya dharura.

Template name: [General Response] Urgent Flood Alert - Short (WhatsApp or Telegram)

Content:

English:

Due to rising water levels, immediate action required:

SAFETY INSTRUCTIONS:

  • Move to higher ground

  • Avoid crossing flooded areas

  • Stay away from rivers and streams

  • Use designated evacuation routes

EVACUATION CENTERS: [Location 1] [Location 2] [Location 3]

📞 Emergency Contact: [NUMBER]

Please reply with your current situation or any urgent needs.


Swahili version:

🚨 TAADHARI YA MAFURIKO - [ENEO]

Kutokana na kupanda kwa kiwango cha maji, hatua za haraka zinahitajika:

MAAGIZO YA USALAMA:

  • Nenda maeneo ya juu

  • Epuka kuvuka maeneo yaliyofurika

  • Kaa mbali na mito na vijito

  • Tumia njia zilizotengwa za kuondoka

VITUO VYA KIMBILIO: [Eneo la 1] [Eneo la 2] [Eneo la 3]

📞 Nambari ya Dharura: [NAMBARI]

Tafadhali tuma ujumbe kuhusu hali yako ya sasa au mahitaji yoyote ya dharura.

Implementation Notes:

image-20241112-142053.png

Feedbacks

Design:

  1. Threat Feedback to ICPAC:

  2. Broadcast Feedback:

image-20241112-143558.png

image-20241112-143402.png

Implementation Notes:

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

Lessons Learned

DRAFT

Starting with clear documentation and importance of user research etc.

Critical Considerations for Future Development

  1. User Research Imperatives

  2. Service Design Requirements

  3. Design Process Recommendations

  4. Contextual Considerations

  5. Stakeholder Engagement

  6. Responsive Designs

    1. Mobile integration

These foundational elements were limited in the prototype phase but are crucial for full-scale implementation and long-term success of the system