- 1 List of group members
- 2 Task
- 3 Summary of requirements
- 4 Architecture and implementation
- 5 Time schedule
- 6 Dividing tasks within the group and organizing work
- 7 Screenshots and screen flows
- 8 Documented learning during project
- 9 Suggested improvements to APIs etc
- 10 Repository and downloads
List of group members
- Morten K. Dybo
- Tobias Messenbrink
- Ákos Pap
E Health Facility Registry
App providing an interface to the health facilities in a country (e.g. the Sierra Leone or Trainingland demo databases). The add should make it possible to search and list organisation units and see these in a map, along with relevant details regarding each facility such as type, the district it belongs to etc.
Some inspiration can be found in the Kenya Master Health Facility List
Place names with coordinates for the whole world can be found using MapZen
Summary of requirements
A "one-page webapp" to view and manage health facilities (OrgUnits) in the DHIS2 system.
Main functionality / Use-cases
Search / View
- User can enter facility name in search box. System zooms map to area level, displays marker on map and info box with facility data.
- User can enter area name in search box. System zooms to area, displays lower level items as markers/polygons and info box with area information and list of underlying items (facilities or sub-areas).
- If there are no matching OrgUnits, the system notifies the user about this.
- User can navigate upwards in the hierarchy using the breadcrumbs.
The list of OrgUnits that match the query are displayed in a list (in addition to being displayed on the map).
In addition to the basic free-text search, there is an option to further narrow the query by specifying Groups and/or Programs that an OrgUnit must have.
Add / Edit
- User can click “Edit” in the Info box to edit the currently selected Facility. Info box turns into editor mode.
- User can add a new OrgUnit under the currently selected Level 3 OrgUnit.
Architecture and implementation
The system will consist of components which are responsible for a well-defined functionality.
This is the root component. Contains all other components, and controls them via props.
Responsible for querying the API, maintaining a list of OrgUnits and other data, and providing these to the other components.
Responsible for providing the search UI and constructing the query details (executed by the App component).
Contains an always visible toolbar with the free-text input.
Can be expanded to show advanced controls: Group multi-selector, Program multi-selector.
Responsible for displaying the search results in a list. OrgUnits in the list can be selected, which notifies the App component.
Can be collapsed to a toolbar to improve visibility of the map.
Responsible for displaying the details of an OrgUnit.
Provides UI to switch to editing mode for the selected OrgUnit.
Responsible for editing the details of an OrgUnit and for filling out the details of a new OrgUnit.
MapController and Map
Two tightly connected components, responsible for displaying and manipulating the map and the OrgUnits on it.
Responsible for displaying the ancestors of the selected OrgUnit.
An app-wide toolbar for displaying a title and function buttons.
- React: React is used as the main framework for the application.
- LeafletJS: Leaflet is used as the map engine, for displaying the map, showing and grouping markers.
- Material-UI: Material-UI is responsible for consistently styled components and widgets.
- Webpack: Webpack is the packaging framework, that creates a single file of all our scripts.
We tried a new approach to querying the API: incremental loading of results. This means, that two queries are issued simultaneously:
- For Level 2 and Level 3 units, that match the free-text criteria (ignoring other criteria)
- For Level 4 units, using all criteria, requesting only the first N results (pagination). Then if there are more pages, those are subsequently fetched.
Upon each query response, the results are added to the global list, which results in a smoother user experience by showing results as early as possible.
Due to a bug(?) in earlier DHIS2 servers (see Piazza discussion), adding a filter on Programs to an OrgUnit query results in returning all OrgUnits stored in the system. This breaks this new approach to querying, so we created an alternative release, while keeping the main release stable on all servers. See Repository and downloads section.
|October 28||Update project Wiki|
|October 28 - November 27||Development|
|November 4||Working prototype of main app components|
|November 27||App final delivery|
|December 7-9||Group presentation|
Dividing tasks within the group and organizing work
|Morten K. Dybo||React developer (Listbox, Infobox)|
|Tobias Messenbrink||React developer (Map, Header, Footer), Design/ HTML,CSS|
|Ákos Pap||React developer (Main app, Filtering)|
In the beginning, each member works on their own branch. Conflicts are discussed and resolved at weekly meetings.
Later, we switch to issue-based branches and create pull-requests which are reviewed and merged into the master branch.
Screenshots and screen flows
Mockups of the app from the planning stage can be found here: https://github.com/tobiasgm/inf5750-uncharted/tree/master/wireframes (private)
Documented learning during project
The project uses the "Issues" and "Wiki" functionality on Github for detailed documentation during development. Please refer to those pages in the project repo to view the current state of the project as well as reasoning for some choices we made.
What we have learned so far:
- Working together on a non trivial project: We all knew about pull requests, branches and issue managers, but none of us has used them in real. In this project, using a trial-and-error approach, we learned how to organize work around issue-specific branches and corresponding pull requests. There is still room for improvement, but probably this is the most important take-away from this project.
- React: React was completely unknown for most of us. During the project we learned some best practices, got to know some libraries (e.g. Material-UI, Leaflet) and noticed some quirks of React, which we had to find a workaround for.
Suggested improvements to APIs etc
- Documentation (or usability thereof): Getting started was a lot more difficult than I'd have expected. Since Postman is free and widely used and recommended, maybe it would be worth creating one or more collections, showing the usage of the API (it could even test it!).
- Speed? Maybe it is the nature of such huge APIs, or it stems from the high degree of genericity of the DHIS2 system, but most queries, even if they are returning only a handful of results, take a significant time to load. Looking at the Timeline in the Chrome Developer tools, we see that most of this time is spent waiting for the response from the server.
- Some quirks: When doing a patch request we receive a 200 response with empty body. Shouldn`t this be a 204-no content or return something? We had also some trouble with the sample data using wrong annotations for multi-polygons and polygons (all objects where actually multi-polygons).
- This wiki: Increase the auto-logout timeout, as most of the edits I did I couldn't save, because clicking save in the dialog just waited, and then didn't do anything. After a full page reload, and redoing the changes (luckily I had them copied), it worked.
Repository and downloads
Link to the repository: https://github.com/tobiasgm/inf5750-uncharted (private)
The stable release of the app can be downloaded from https://github.com/tobiasgm/inf5750-uncharted/releases/tag/v1.1 (private)
There is also an alternative release, see Architecture and implementation -> Alternative release. Available from https://github.com/tobiasgm/inf5750-uncharted/releases/tag/v1.1-alt (private)