Mapeo Support Materials
English
English
  • Introduction
  • Overview
    • About Mapeo
      • Mapeo tools
      • Peer-to-peer & Mapeo sync
      • How Mapeo is being used
    • Is Mapeo right for me?
    • FAQs
  • Quick start guide
    • Getting started
    • Mapeo Mobile
    • Mapeo Desktop
  • Complete Reference guide
    • Welcome – Introduction
    • 🗒️Essentials for a successful Mapeo project
      • Planning a Mapeo project
        • What is the project goal?
        • What outputs do you want?
        • What information to collect?
          • Data types within Mapeo
        • Who should be involved and how?
        • What are the parameters?
      • Security & risk assessment
      • Creating user protocols
    • ✔️Will Mapeo work out-of-the-box for me?
      • Default configuration
      • Default background map
    • ⚙️Customization options
      • Translating Mapeo & default configurations
      • Custom configurations
        • Creating custom configurations
          • Planning configuration & data structure
            • Categories
            • Icons
            • Details fields
          • Coding configuration
            • Adding icon files
              • Creating and exporting SVG files using Adobe Illustrator
              • Creating and exporting SVG files using Inkscape
            • Creating details fields
            • Creating categories
            • Defining geometry defaults
            • Adding a project key
            • Adding project name and version
            • Building configuration file
              • Via the command line
              • Using GitHub Actions
          • Testing and iterating
      • Custom background maps
        • Creating custom background maps
          • Generating map files in .mbtiles format for the experimental Background Maps feature
    • 📱Mapeo Mobile installation & setup
      • Installing Mapeo Mobile
      • Choosing Mapeo Mobile settings
      • Experiments: Turning on experimental features
        • Directional Arrow
        • P2P (peer-to-peer) App Updates
        • Background Maps
        • Security
          • App Passcode
          • Obscure Passcode
      • Importing configurations into Mapeo Mobile
      • Adding custom background maps to Mapeo Mobile
      • Updating Mapeo Mobile
    • 📱Mapeo Mobile use
      • Activating GPS and viewing current location
      • Creating observations
      • Viewing observations
      • Editing and deleting observations
      • Sharing data externally
      • Syncing data via Wi-Fi
    • 💻Mapeo Desktop installation & setup
      • Installing Mapeo Desktop
      • Choosing Mapeo Desktop language
      • Importing configurations to Mapeo Desktop
      • Adding custom background maps to Mapeo Desktop
      • Updating Mapeo Desktop
    • 💻Mapeo Desktop use
      • Mapeo Desktop for managing Mapeo Mobile data (Observations mode)
        • Synchronizing data
          • Synchronizing via Wi-Fi
          • Synchronizing with a file
        • Viewing observations
        • Editing and deleting observations
        • Exporting data & sharing externally
      • Mapeo Desktop for creating territory data (Territory mode)
        • Navigating around the map
        • Creating and editing territory data
        • Changing background maps in Territory mode
        • Importing and using external geospatial data
        • Exporting and syncing data
      • Synchronizing data with Mapeo Desktop
    • 💡Mapeo trainings
      • Defining goals and format
      • Structuring a training
        • Best practices for planning a training
        • Structuring the agenda, content and activities
          • Suggestions for the different sections of a training event
          • Tips and suggested activities for training key features of Mapeo
          • Materials and resources available for the training event
      • Preparing equipment and supplies for a training
        • Recommended equipment and supplies
        • Tech preparation before doing in-person training
    • 🔧Troubleshooting
      • I can't start Mapeo
      • Mapeo closes automatically
      • I have problems with the GPS in Mapeo
        • GPS is not activated in Mapeo
        • My GPS signal is very weak
      • I have problems with the camera in Mapeo
        • I get a black screen when using the camera
      • I want to update Mapeo Mobile permissions
      • I have sync issues
        • I want to connect to Wi-Fi
        • I want to create local Wi-Fi networks
          • With a portable router
          • With a smartphone
        • The device I want to sync with does not show up on my Synchronize screen
        • I get an error when I try to sync with another device
        • I can't sync with the sync file
        • The person I want to sync with has deleted valuable data
      • Sharing files between devices
      • Saving and printing Mapeo reference materials
      • How do I back up Mapeo Desktop data?
    • Glossary & quick reference sheets
      • Glossary of Mapeo related terms
      • Overview of Mapeo Desktop Territory mode screen
  • For developers
    • Mapeo architecture overview
    • Mapeo repositories
    • Localization
  • Support
  • Additional references
  • Digital Democracy website
Powered by GitBook
On this page
Export as PDF
  1. For developers

Mapeo architecture overview

PreviousOverview of Mapeo Desktop Territory mode screenNextMapeo repositories

Last updated 3 years ago

We are currently redesigning Mapeo's core architecture and will relese updated documentation once changes are complete.

Behind the scenes of the user interfaces for working with mapping and monitoring data, you'll find Mapeo's core infrastructure. This document is a work in progress.

Schema

  1. Observation. Mapeo extends the OpenStreetMap specification to add 'Observations' -- a new data type that is like a node or point, but with extra metadata and media.

  2. Field. Called a 'question' (ODK) or 'tag' (OSM), a Field is how we structure metadata about Observations and OSM Elements.

  3. Preset. Called a 'Category' in the Mapeo interface, but in code we call this a 'preset.' This type defines a set of Fields and an Icon.

  4. Filter. An expression that can be applied on the values in one or more Field across a set of observations.

Database

KappaDB is one of the fundamental primitives of Mapeo Core that handles indexing of data that isn't media (i.e., it does not handle images). KappaDB is a flexible database for peer-to-peer applications that we developed in 2018, and is considered stable. If you haven't yet, go ahead and to familiarize yourself with how it works.

Configuration

Each 'project' has a set of configuration files. It is identified by a project key which is a shared secret amongst all devices. It authorizes devices to read and write to the database. There is no way at this time to revoke a configuration from a device remotely.

For more on configurations, see Custom configurations.

Discovery

Each device announces itself on the local network using MDNS. It announces itself using a hash of the project key, which is also called a discovery key. This means that 3rd-party observers will not be able to discern the project key.

Replication

Replication requires advance knowledge of the project key. Replication will be refused if a peer's project key is not the same.

Media

Clients can provide filters for which files they want to accept on either end; by default, Mobile to Mobile sync does not send original images, only preview and thumbnail sizes. Original images are always syncronized from Mobile to Desktop.

is the module that manages replication across multiple Mapeo devices. It depends upon , a distributed append-only log. Hypercore only allows one writer; multifeed syncronizes a set of hypercores -- by a variety of authors -- across all devices with the same project key. This forms the basis for creating a view of a single dataset that incorporates changes from multiple writers across multiple feeds.

A project also contains media files which are handled separately from the multifeed module, which concerns itself primarily with structured data (e.g., json, protobuf, etc). Media files are replicated using . This is a simple module that announces the list of files available on both sides of a duplex stream, and then replicates the files that are missing.

Multifeed
hypercore
blob-store-replication-stream
try the workshop
Architecture Diagram September, 2020