Status update

A quick summary of what we've built so far, as well as a roadmap for possible directions we could take, going forward. I also included a bit of background info about the architecture of the platform, for further reading.

My apologies for this being a fairly lengthy and technical document. Please let me know if you have any questions, or need further clarifications.

These are the parts that are technically functional, but this doesn't mean they're also fully operational already. Some features may not appear on the website yet.

We started the project by developing a system to match community needs with possible donations in the wake of a disaster. During this phase, we stumbled upon the Offers & Needs Market a couple of times, and it makes perfect sense. Mobilize your local community, express your needs, share what you can offer, and try to match the 2 together.

So this is what we're currently doing on the website too, through 2 web forms: one to request for help, and one to offer help.

The submissions are collected in a backend manager, where moderators can approve the requests after validation. Requests can also be manually added here, or edited for clarity.

For a short video walkthrough of the process, see the Demo section.

On the website, people can directly offer help for a specific need.

Next to assisting in immediate disaster relief, we also saw the need for better preparation beforehand, and longer term support for the recovery afterwards. To facilitate this in the platform, we started by mapping the participants of our meetings through a web form.

This data is also accessible in the backend manager. For each entry, you are able to capture contact details and location data, as well as relevant images and links (if needed). Such an entry is called a node.

Next to adding nodes, this component also has the ability to add new networks to the platform. This means that you can collect nodes in networks of your own choosing, making it very easy to compile data from different sources. Currently, some data has been imported already from the Permaculture PH map and the Community Kitchens project. Mainly for testing purposes, but the system is ready to scale to as many network partners as needed.

All location data can be layered on a map. And maps can be created as needed in the backend manager. This means: we're not limited by having only a single map to output data. We can make as many maps as we like, with just the data we select.

In the manager, it looks like this:

Each row in this table represents a layer on the map. As you can see, there is a data field that accepts GeoJSON data. This can be copy/pasted directly (in case you quickly want to display some external data), but it's better to create a MODX element containing the logic to fetch the data (referenced inside the square brackets). This requires some coding, but an experienced developer should be able to adapt the existing elements to fit additional requirements.

On the map itself, these layers can be toggled on and off, and the markers (optionally) show a popup when clicked. Next to displaying some basic info, this popup could also link to more detailed information about the location. This again would require some customization.

The map view is just one way of presenting data in the browser. There are also options for generating grid views and tables with information.

The system is very flexible in creating other views, or variations on existing views. Most of the time, with only minor adjustments. You just need to know where to look (ask me!!!).

Data entry

We set out with 2 important goals: keep data entry as frictionless as possible, and make it work offline. This resulted in the following functionality.

The platform itself provides a form builder, which allows us to construct our own forms with a drag & drop block editor (nicknamed FormBlocks). Additional coding is still required to make the forms save the submitted data to our custom database tables.

This currently works fully for Needs and Offers. For Nodes it is a work in progress.

The webforms require an active internet connection to function. To be able to collect data offline, we offer the option to use the Kobo application. This is mature software and widely adopted in humanitarian settings, so we decided not to reinvent that wheel (for the moment).

Data can be submitted through an Android app, which has the ability to store the data locally and send it whenever the user is back online.

The data is stored in the database of Kobo itself, but can be exported programmatically. There is an import script available for transferring Offers and Needs data into our own database. This is a one-way transfer. Mutations in the Releaf platform can not be written back to Kobo. But if I recall correctly, mutations in Kobo can still be applied to previously imported data in the Releaf database.

The system used to create the platform, MODX, comes with tools and plugins to create grids for managing data. Think of these grids as Excel sheets on steroids. You can create, rearrange, update and delete data this way, without having to worry about messing up the database.

For each external data entry option that we offer, there is also an internal grid available in the MODX manager. Some basic training would be preferable, in order to locate these grids and learn how to operate them.

Each individual connected to the platform is registered as a Person. Persons are technically the users of the platform, but I tend to avoid that term as it suggests the person might be addicted to the software.

Persons can be added to a group, giving them certain access permissions and privileges. The platform currently has the following groups:

Organizations - The SEC registered partner organizations. Mappers - Anyone who has ever created a Need or a Node. Donors - Persons that have pledged to make an offer. Moderators - This group is able to access the MODX backend and view the submitted data. Editors - This group can also edit content of the website itself. Developers - This group has access to all the technical stuff too. Administrators - This group can access everything, everywhere, all at once.

For more info, see EarthBrain user management.

The platform offers fine-grained privacy controls.

For each type of data, there is an option to mark it as public or private.
Private data can only be viewed by appointed moderators and administrators.
Public doesn't automatically mean that it will be visible to the outside world (the platform will always remain cautious with that). It merely indicates that the person has explicitly granted permission to share the data.
Location data can be obfuscated, so the exact location is never exposed (even though the location is marked as public).
All data is marked as private by default.

Below is an incomplete shopping list of technical features that would benefit the platform. I am (in theory) able to develop each of them, but help would be much appreciated.

Currently, there a few forms scattered around the platform, which people can use to submit data.

It would be great if all data entry options can be bundled in an app-like dashboard. I started prototyping this already at app.releaf.community It's still in very early (alpha) stage, but I'm building it as a progressive web app (PWA). This means it could install certain parts of the application on the device of the user, so it still performs well in poor internet conditions, or can even be used completely offline.

Currently, people need to enter their address as their location when using the web forms. This is then geocoded into coordinates in the backend.

It would be great to have a form input field on the frontend already, that displays a map with marker for the location (similar to Kobo). It would need to geocode the address via AJAX. Bonus points for letting the visitor pick a location on the map with the cursor!

Currently, all options to collect location data require the user to fill up a form. Either a given address is geocoded into coordinates, or the user has to pick or share their device location (Kobo).

It would be great if we can extract the geo coordinates from images instead. When taken with a modern smartphone, most devices embed the current location in the image EXIF data. If we can provide an upload option for users to share their images (needs to be the original!), then they could be spared from having to fill in location data in a form each time, greatly simplifying the process.

Currently, we can import data from the webforms on the site, from the Kobo platform, and from GeoJSON input.

It would be great if we can add the ability to import Excel sheets or CSV files too! The tricky part is matching the columns with the correct database objects in the platform, because surely every excel we receive will be formatted differently. Can you help us figure this out?

And while you're at it, can you make an export function too?

Currently, GeoJSON is used to load data into the Leaflet maps.

If would be great if we can also offer this data as download in common mapping formats, so they can be imported in external applications (such as QGIS, OSM, Android map apps, etc). This way, it can also be accessed in offline scenarios.

Currently, stored data is only available for display inside the platform.

It would be great if we can make all public data available through an API. I have experimented already with a tool called Directus, which can be attached to the existing MODX database and used as a kind of instant API. But writing a native REST application for MODX is also an option.

Currently, we're able to display data in different layers on the map. This is done with an open source library called Leaflet.

It would be great if we can expand the functionalities of Leaflet a little, by adding a search feature to look for entries in your region, for example. And we need to tweak the display of the layers in the map, because all markers look the same now.

Currently, requests for aid that are submitted to the platform are listed individually. Although this fine for providing a basic overview of what's needed, and where, it makes it a bit difficult for donors to decide who they want to help. After a disaster, many needs are more or less the same (food, clothes, blankets, etc).

It would be great if we can bundle the need requests at some point, and start campaigning for all the needs at once. A campaign could be tied to a natural disaster (or other hazardous event), or to a region... The aim is to simplify the donation process, but it would require a team to sort out the final distribution of the aid.

Currently, all data is displayed in a similar format. Mostly just black text on a white background.

It would be great if we can define a few overarching categories and label each of them with a distinct color. This way, each category can easily be visually traced throughout the platform.

As a suggestion for the categories:

Food sovereignty
Water and sanitation
Health and wellbeing
Shelter and appropriate tech
Coordination and collaboration

Phase 2 of this feature could make it possible to filter content per category.

Currently, there is an active Mailchimp account, but I don't know where and if it's being communicated anywhere.

It would be great if we can collect a list of email addresses already, in anticipation of sending out some (hopefully more and more frequent) status updates in the future.

Currently, there is very little technical documentation available online. I have a little more on my own computer, but it's very scattered and unstructured.

It would be great if we can collect information about how to use the platform (both as user and as developer) somewhere online.

Currently, the platform is completely web based. This of courses poses immediate problems in case of accute disruptions to local internet connectivity.

It would be great if we can provide communication services that work offline, or with low tech equipment (such as SMS or radio transmitters). In addition, it is also extremely important that you can trust the people (and tools) you are communicating with in times of disaster.

Some ideas:

Use Kobo Toolbox for collecting data when offline
Provide offline datasets for mobile mapping apps
Create secure, invite-only communication circles inside communities
Use SMS or even data mules to reach people without internet access
Organize local trainings to (re)learn how to use low-tech communication tools

I am experimenting with setting up our own Matrix server. Matrix is an open protocol for decentralised, secure communications. It can be used with apps specifically for Matrix (such as Element), but it can also be "bridged" with existing apps (such as Facebook or Telegram). This means people can form communities without having to choose a specific app or platform for communicating. People can choose to use a Matrix-based app, or keep using their preferred social media platforms.

The use of this server could also be offered to other organizations as a service.

The Releaf.Community platform was not built from scratch. It uses an open source CMS (MODX) and a library that I've developed on top of that (Romanesco, also open source). Below, I'll outline briefly what these systems do, and how our platform utilizes them.

MODX (MODular and eXtensible) is a content management framework written in PHP. It connects to a MySQL database through a library called xPDO. This library provides a bridge for interaction with the database via PHP, saving you the trouble of having to write complex SQL queries. On top of this, MODX offers a lot of plugins that let you perform common tasks with PHP and xPDO, making it possible to retrieve information from the database without having to write complex code. And on top of that, MODX provides very flexible mechanics for caching, theming, routing and user management, making it a breeze to develop fast and reliable websites and applications.

While MODX takes care of what we call the "backend" in development slang, by default, it doesn't provide anything to generate a "frontend" for your application. The frontend is the code responsible for displaying your app in the browser, and interacting with it (usually HTML/CSS/Javascript). The lack of a frontend is by design. There are so many libraries, platforms, tools and techniques available, and each developer prefers his or her own "stack", making it impossible to fabricate something that fits all. So it's up to you to choose whatever you want for presenting your content in the browser. MODX calls this Creative Freedom.

Now I love freedom! But I don't really like repeating myself.. So what I ended up doing over the years, is collect the components that I've built in MODX into a library of my own (Romanesco). This library contains common elements (headings, images, buttons, etc) and lets you reuse them in different projects. Another MODX extra (ContentBlocks) provides the ability to create layouts with these components via a drag & drop interface.

The Releaf.Community platform also uses Romanesco, so any improvements to the core library are also applied to the Releaf platform after each update.

The machinery for storing the platforms custom data into the database is contained in 2 separate packages (a package being an installable MODX extra).

The first one is called EarthBrain and contains common data types such as user, taxonomy and location data. By separating this from the more specific data inside the project itself, EarthBrain can be used in other projects too, serving different goals with a unified data structure, and thus the possibility to exchange components again.

One sister project also using EarthBrain is ForestBrain, a kind of bookkeeping software for plants and trees.

The second package is used for data that's really specific to the Releaf.Community platform, such as the needs and offers data. By maintaining it as an installable package, we do keep the option open to have different installations at some point (for example in other countries) with the same functionalities.

The code of all these libraries is open source, and freely available on Gitlab.

Status update

Current features

Needs & Offers

Networks & Nodes

Layered map

Data views

Data entry

Web forms

Kobo Toolbox

Backend manager

User management

Privacy settings

Ideas / roadmap

App dashboard

Location picker

Extract location from images

Excel / CSV import

KML / GeoJSON export

API

Additional map functionality

Bundle Need requests

Color coded categories

Mailing list

Documentation

Releaf.Network

Architecture

MODX and xPDO

Romanesco

EarthBrain

ReleafBrain

Source code