Mapper frontend implementation discussion

[spwoodcock]

I am away for a few weeks. @charliemcgrady and @NSUWAL123 are planning to work on the mapper frontend implementation.

Following on from PR: #1760

Live Updates

We have two important elements it would be very useful to have 'live update' for the mapper:

• The task areas in the FMTM database.
• The Entity geometries (within the task areas) in the ODK database.

The Task Areas

Currently we are using Electric-SQL to serve the task areas from our database:

• It's a lightweight wrapper to provide an API directly to the task_history database table.
• We can track entries to the task_history table and display them real-time in the users browsers.
• The task areas geometries displayed on the map can then be coloured based on their mapping status: READY: white, MAPPED: green, INVALID: red, etc.

The Entity Geometries

(shown in red in the screenshot. The task area must be clicked to display them)

• This one is more complicated.
• The Entities are stored in the ODK database, but not as a standard relational database format.
• As the Entity properties (such as a status field) are set by the user, they are stored as JSON in the ODK database.
• Regardless, we cannot rely on accessing this database directly. While we bundle ODK with the dev and stage instance, prod uses an external ODK instance. We wanted to provide flexibility for users to re-use their organisation ODK instance.
• So in summary we probably can't have live updates of the individual geometries using this method. (open to suggestions - would prefer not to use websockets for each mapper connection though).

Decisions Taken

• Opted to create a separate Svelte frontend application, to be more lightweight, fast, and a separation of concerns with the main React frontend.
  • As a side goal I wanted to reduce the React app complexity with the goal of maybe migrating to HTMX for the project creation and visualisation dashboard, but this is another topic...
• The Svelte frontend is routed to via the Nginx web proxy that sits in front of FMTM. Only the URL pattern DOMAIN/mapnow/{projectId} will be routed here, the rest goes to the React app.
• I opted to use Electric-SQL as I believe this is one of the best tools in the local-first movement.
  • Again probably too much to delve into here, but this should hopefully aid our long term goals.
  • Performance should be greatly enhanced by hosting a browser-based local database and interacting with that.
  • Database updates are synced with the central database on a server and changes between users are reconciled.
  • The advantages: we can have real-time data sync, but also support for fully offline use of the application, without relying on PWA endpoint caching etc. We actually read and write to the local database as needed, and it syncs when the user comes back online again.
• Also decided to the MapLibre, as the most performant mapping application. Specifically the svelte-maplibre wrapper which are a nicer way to use the library.
  • There has been some discussion / setup to wrap the svelte components in web components (customElement), to make this library much more versitile. I believe this is a very nice approach, building off the work of an already very well put together library with multiple contributors.

UI Prerequisites

• The UI is using Shoelace.style Web Components. This is the library we selected to build @hotosm/ui, which in theory should be used in all HOTOSM tools. More on this in a later section.
• The @hotosm/ui UI library is still in early stages!
• As a per-requisite to completing the mapper frontend, we probably need to finalise the 'Header' component in this library.
• Existing logic for OSM login should be migrated to this component, allowing us to use the header in our mapper frontend.
• HOWEVER, we can:
  • Add the auth etc as the last part here, so hopefully it's not a blocker.
  • Could temporarily replace the usage of @hotosm/ui Header with something else until we get that complete.

[spwoodcock]

Page Layout

I opted for a bottom-sheet like layout, with 4 tabs:

• Map page: the main page for mappers to lock tasks, mark complete, etc.
• Details page: provides task_history / a list of events. Filtered if a task area is selected.
• Offline page: present to help the user prepare for fully offline usage. Allows for the basemap download. Will also cache required files offline in Origin Private Filesystem (OPFS):
  • A raster PMTiles basemap.
  • A flatgeobuf file of the feature to map.
• QRCode page: the user must scan or download this QRCode when they first start on the project, loading it into ODK Collect.

Map Page

• The goal was to make the UI as simple as possible here.
• The task areas are displayed on a map, coloured based on their mapping status.
• Clicking on a task brings up a button in the center screen to progress the mapping flow:
  • RELEASED_FOR_MAPPING --> LOCKED_FOR_MAPPING --> MARKED_MAPPED --> (optional, to revert) RELEASED_FOR_MAPPING.
  • This should be reflected by simple icons that represent what we want to do: lock task = a padlock, mark mapped = checkered flag, release = reset icon? (open to ideas here on what is most intuitive!)
• Once a task area is locked, it should be possible to click on the feature to map, then map in ODK.
  • Clicking on a feature should show an ODK logo, to represent mapping in ODK.
  • Clicking this loads the intent URL like this: odkcollect://form/${xformId}?feature=${entityUuid}
  • ODK Collect with be opened with the feature pre-selected in the form.
• Recent task_history / events are displayed at the top right as a notification bar.
• The map should have geolocation to show the current users location.
• The map should have the capability to tilt to show a 20-30° perspective (easier for mappers).
• The map should rotate with the users phone orientation, like any mapping app!
• There should be a simple layer selector to allow displaying the downloaded PMTiles layer in OPFS. Or the user can select OSM, Overture, Bing Satellite.

Details Page

• Should simply show the task_history entries in chronological order, paginated ideally.
• When the user has clicked on a task area on the map already, this will filter down the entries for only that task ID.
• Clicking on a an entry will zoom to the related task on the map.

Offline Page

• Basemaps are managed in the React management UI (it should remain this way):

  

• On this page users should be able to download pre-generated mbtile files.

• There should be a button like 'Go Offline' which will download a PMTiles basemap and flatgeobuf map features, to OPFS storage for offline usage.

QR Code Page

• A simple page to display the QRCode.
• Either to download or scan via ODK Collect an start the project.

[spwoodcock]

Setting Up Locally

Build the images

docker compose build

Run the services

• Unfortunately it's not so easy to develop using the frontend only, as we rely on a few different services to support the API, like ODK Central, Minio S3, Electric-SQL.
• It's pretty simple to run via docker-compose though:

cp .env.example .env
docker compose up -d

Seed the db with projects

• Run the e2e test to create a new project

  docker compose \
    -f docker-compose.yml \
    -f contrib/playwright/docker-compose.yml \
  run --rm --service-ports ui-test \
  'npm run test:e2e-report -- ./e2e/01-create-new-project.spec.ts'

• Run multiple times for multiple projects

[spwoodcock]

Linking Between The Two Frontends

• We probably need a link in the management React dashboard to 'Map Now', which will open the mapnow/{project_id} URL.
• We could possibly link from the mapper frontend to the React one, but in the spirit of keeping things as minimal as possible, let's consider this later on 👍

[spwoodcock]

@NSUWAL123 reports he can build and run the PR I made, so I'm planning to merge into develop so it can be built on top of.

It will introduce quite a few errors, due to a change from using SQLAlchemy to raw SQL in some places.
The test suite has a couple of failures I didn't have time to fix.

Project creation works at least, along with task locking, so you can do that and get testing the frontend👍

[NSUWAL123]

Our current project-details need to be fixed I guess as there are no button to update task after locking it. But you don't have to worry. I'll address any bugs raised on our current React app tomorrow firstly then continue with the svelte.

[charliemcgrady]

The team had a meeting today to discuss priorities for next week. The first coding tasks will be:

1. Adding icons to the task boundaries using a SymbolLayer
2. Simplified flow for claiming the task, redirecting to ODK, and resolving the task. Resolving task will be mocked since backend API is not working currently.

Design team will be proving icons and the UX for #2.

[spwoodcock]

Proposed user flow

Pt1: Open Mapper Frontend

1. Either:
   • User is on existing project management frontend (the existing react frontend)
   • OR has been sent a link to the mapper frontend (say via whatsapp)
2. User clicks button or link to open mapper frontend for a specific project URL
   • The URL format is like: https://fmtm.hotosm.org/mapnow/{projectId}.
3. User is prompted to log in (they have the option of OSM or temp login)
   • Note we can remove temp login from the project management frontend after this is done.
   • Also note we should probably defer caching and loading of WASM bundles until after the login stage has been complete.
4. After login the user is redirected back to the project page they wanted to view.

Pt2: Setup Wizard

1. User is presented with a 'wizard' when they first load the project page.
2. First they are asked to scan or import the QR code into ODK Collect
   • The user still has the option to view the QR code again via the QR Code tab.
   • The same component can be displayed in the modal and bottom-sheet tab to avoid duplication.
3. Next they are asked if they need to go offline, or need to download a basemap layer for navigation offline.
4. If yes, we handle offline setup for them:
   • Download the PMTiles into OPFS storage for using FMTM offline.
   • Download the .mbtiles and present to the user to store on their device.
     • The options to download should be presented from already generated tile archives.
     • A simple dropdown showing the available tiles will do.
   • Option 1: download multiple flatgeobuf files (less optimal)
     • Task geometries.
     • Entity geometries (features to map).
   • Option 2: Create a second PMTiles archive on the task geometries and entities on demand (this would require something like bundled tippecanoe and backend updates though).
   • As with the QR Code, the user can do the same things via the 'Offline' tab if needed afterwards.
5. On the final page we should provide some instructions for how to map in the next stage, with images to demonstrate.

One time only

• After user dismisses popup / clicks to confirm they have set up the project, we can add a key to local storage in the browser.
• The key could be of format fmtm-project-{id}-setup=true.
• If this key is present when the project page is loaded, we can skip showing setup wizard modal.

Pt3: Mapping

Two workflows, below:

(A) Mapping new features

1. A button should be shown somewhere prominent and be easily identifiable that it is to add a new geometry.
2. Clicking this button will simply open ODK Collect with the form started up and ready to fill out.
3. We have already injected the questions into the XLSForm to handle this case: the user creates a new geopoint in ODK Collect and fills out the survey.

(B) Mapping existing features

1. The user clicks on a task area.
   • We remove all UI elements to allow locking the task area.
   • We remove all UI elements to allow opening ODK at this point (the user must select a geometry to open ODK).
   • More on this below (Note on task locking).
2. The geometries within the task are presented to them.
3. Clicking on a geometry opens a dialog / shows a button to 'Map In ODK'.
4. Clicking this opens an ODK form with the geometry pre-selected.

Note on task locking

• I don't think we necessarily need the user to explicitly lock tasks.
• It would much a much nicer user experience if this is done automatically.
• When the user clicks 'Map in ODK' for a geometry, an API call is made to lock the task the geometry is within.
  • If the task is already locked, then this does not happen.
  • The map is updated instantly on all users devices to show the task area is locked (colour change).
• There should be two buttons available when clicking on a task area that is already locked:
  • Mark task area as complete.
  • Unlock task area to inform others it's not complete.

Note that part of this workflow should also include auto-unlocking of tasks.
If a task is locked and not marked complete for 1hr, it should be unlocked again.
This can be handled in the database via pg_cron.

At the end of the ODK workflow, the user returns to FMTM to select another geometry for mapping.

[spwoodcock]

The wizard idea if probably a bit heavyweight for what we need (possibly consider in future if needed).

Instead we opted to simply show the QRCode tab on first load, then using a localStorage key, we don't show this again (go to the map page as normal):

Also added a prompt to 'select a task for mapping':

[spwoodcock]

Copying notes from Ramya on Slack for the proposed mapper frontend flow

1.Mapper Frontend Access:
The mapper accesses the FMTM via a mobile-friendly web frontend, optimized for mobile devices. A project list is displayed, allowing the mapper to quickly select a project.
2. Project Page with Task Overview:
After selecting a project, the mapper is taken to the project page, which includes a project summary (description, objectives, area covered) and a “Start/Resume Mapping” button. This button leads directly into the task selection process.
3. Task Selection Page with Filtering Capabilities:
The “Start Mapping” button navigates to the task page, featuring a map view displaying task boundaries. Tasks are categorized by status:
• Available (ready for mapping)
• Locked (in progress, differentiated by red lock icons for tasks locked by the mapper themselves and standard lock icons for tasks locked by others)
• Invalidated (tasks that need to be redone)
• Completed (submitted and validated)
Mappers can filter tasks by status using drop-down menus or checkboxes, allowing them to focus on specific tasks like those requiring a resurvey. Task details, including the number of features and task-specific instructions, are displayed when a task boundary is selected. The mapper can then lock an available task for mapping.
4. Feature Selection for Mapping:
Once the task is locked, the mapper is presented with two options:
• Load the entire task area with all its features into ODK for a comprehensive survey.
• Advanced Feature Selection: The mapper can apply filters to focus on specific features within the task. Filters include:
Survey Status: Fresh survey needed, Survey completed, Resurvey needed, Survey completed and approved.(
Future Extension) Feature Type: Map features such as buildings, roads, and points of interest can be filtered.
(For future team-level mapping) The mapper can choose to lock individual features, ensuring that features are not double-surveyed if the task is shared among multiple mappers.
5.Task and Feature Loading into ODK:
Based on the filters applied, the task is sent to ODK with a subset of features. FMTM provides a preview, allowing the mapper to confirm the selection before proceeding.
6.Switch to ODK for Field Data Collection:
Once the task is loaded into ODK, the mapper follows the standard ODK workflow for collecting field data, such as GPS points, photos, and field notes.
7.Task Submission and Status Update in FMTM:
After completing the field survey, the mapper submits the data via ODK. Upon returning to the FMTM frontend, the mapper is prompted to update the task status by either marking it as completely surveyed or selecting stop surveying if the task is incomplete or additional work is needed. Validation tasks can be managed separately by expert mappers or supervisors.
8.Post-Survey Review and Validation:
After data submission, mappers or validators review the submitted data in both FMTM and ODK Central. They can either approve the data or request a resurvey for specific features. The status is synchronized between FMTM and ODK

[spwoodcock]

1. The mapper frontend does not have a project summary page. Either the user comes from the management dashboard (a button to 'Start Mapping', or opens the URL directly for a project from e.g. whatsapp.

2. (+3) imo there is too much navigation here. We shouldn't have a project detail page and a task page separately. The mapper frontend was designed as a single page - the map the users will navigate on.

3 (+4). We should definitely have filtering capability and a good legend for the task / feature statuses.

• We should translate these enum values to more user facing labels in the frontend:

  • UNLOCKED_FOR_MAPPING = Available for the user.
  • LOCKED_FOR_MAPPING = Locked for the user.
  • UNLOCKED_FOR_VALIDATION = Complete
  • BAD = Issue

• There should be a filter dropdown on the map to filter by:

  • My Tasks
  • Survey required (UNLOCKED_FOR_MAPPING )
  • Survey complete (UNLOCKED_FOR_VALIDATION)
  • Survey in progress (LOCKED_FOR_MAPPING)
  • Resurvey required (BAD)

a. 'Load the entire task area with all its features into ODK for a comprehensive survey.' While this is possible, it negates most of the advantage of using FMTM? We could simply load all geometries into an ODK Central project and never use FMTM for task locking etc. FMTM would simply be a management dashboard then.

b. Should we really enable locking of individual features? I think restricting the user can potentially cause issues if there are bugs and doesn't benefit much. Instead we just indicate the building is currently being mapped (with a colour), and let them decide if they want to proceed to map (perhaps the mapper forgot to submit the survey and the building entitiy did not auto-unlock, so it still needs mapping).

5. Not sure what this means @ramyaragupathy ! (the part about a preview)

6. Back and forth between ODK and FMTM seems to be unavoidable here 🦖

7. Definitely 👍

• The mapper should have options to update the task:
  • Mark as fully mapped, with a prompt if not all building entities are marked mapped yet.
  • Stop mapping and reset the task to available.

8. If validation fails, the task state is marked as BAD and this will be reflected as 'Resurvey required' on the mapper frontend.

[spwoodcock]

A Workflow Around Entities

The proposed flow is still very task-centric, when I would argue it should be entity-centric (about the buildings).

Locking Tasks

• I think we should remove the option to select a task area when it is unlocked, meaning we also remove this popup:

  

• Users should only be able to select Entities instead. The popup should simply say: 'Map This Feature'.

• Clicking 'Map This Feature':

  • Sends a 'MAP' event, causing the task status to update to 'LOCKED_FOR_MAPPING'.
  • Update the Entity state to OPENED_IN_ODK = 1.
  • Open ODK by intent with the feature preselected.

• This will cause the area to be coloured as locked, and the building entity to be coloured as in progress.

Marking Tasks As Complete

• Once a task area is locked for mapping, it should be selectable.

• This popup should display:

  

• However, we should remove the 'Open In ODK' button, and only show the options to Cancel Mapping or Complete Mapping.

• There should also be the additional prompt to say 'Are you sure?' when all building entities are not mapped and the user tried to mark complete (the same as the React frontend).

Updating the Entity Status

• As mentioned in Create small Postgres NOTIFY/LISTEN webhook service for ODK Central #1841 we will have a longer term solution with webhooks to immediately update the building entity status to SURVEY_SUBMITTED = 2 in FMTM.
• For now the statuses are only synced every time someone opens the management or mapper frontend project detail pages.
• We could possibly consider an additional button in the interim, when the user selects a building, to 'Check Current Status' and sync the ODK status immediately.