Firestore

We use the Firebase Cloud Firestore as the central element in our architecture to save processed data from Twilio and make it accessible to the Android and iOS apps.

Data structure

Most of the data stored is linked to the locale (country) that it was generated in. Thus we separate the data in different locale based collections. Within each of the locale based collections the structure of the data is the same.

As a general naming scheme for all collections, documents and fields we use the all_lower_case scheme where multiple words are separated by an underscore.

Each of the collections in our Firestore database has its own section below explaining its content. The structure of each document within a collection is defined by naming the key of a field, as well as its type and an explanation of how to interpret the contents of the field. Since a NoSQL database does not enforce the structure of its data, all clients working with the database must ensure that they stick to the structures defined below.

Locale collection

The locale collection is used to separate the following data based on a locale. It contains one document per country, which in turn holds collections for our data. The documents are named based on the ISO 3166-1 alpha-2 country codes.

Document structure

A locale document mostly contains other collections. The only data stored directly in the document it self is listed here.

• phone_prefix (String)
  The prefix used for all telephone numbers in the country. Including the "+" at the beginning.

Example

For Germany the country code is de. Thus the path to all data based in Germany starts with /locale/de. The documents content will look like this (JSON representation of the data):

{
  "phone_prefix": "+49"
}

Order collection

The order collection stores the orders that have been made via our Twilio bot. It is a sub-collection of a locale document. The names of the documents are auto generated by Firestore. Each order also has a sub-collection to store a log.

Document structure

The data stored in an order document has the following fields.

• type (String)
  The type defines what kind of order this is. There is a set of predefined types that all clients should be aware of: medicine, groceries, other. All other string values should be interpreted as other to allow future expansion of this list.
• urgency (String)
  The urgency defines how fast an order should be handled. There is a set of predefined values that all clients should be aware of: asap, today, tomorrow. Any other values are not allowed. If there are other values regardless, they should be interpreted as the least urgent type.
• name (String)
  The complete name of the caller.
• phone_number (String)
  The phone number of the caller. This number has to be internationally valid and thus has to include the country based prefix (e.g. +49 for Germany).
• address (Map)
  The address map contains all information about the address of the caller.
  • street (String)
    The name of the street of the address. This is an UTF-8 encoded string.
  • house_number (String)
    The house number of the address. This is an UTF-8 encoded string. Numbers are not sufficient here, since there are house numbers that contain letters.
  • zip (String)
    The postal code of the city in the address. This is an UTF-8 encoded string. Numbers are not sufficient here, since there are zip codes that start with a 0.
  • city (String)
    The name of the city in the address. This is an UTF-8 encoded string.
• location (Map)
  The location map contains all information about the location that the order is needed at.
  • gps (GeoPoint)
    These are the GPS coordinates that correspond to the callers address. They are used to display the order on the map.
  • geohash (String)
    The geohash of the GPS coordinates. These are required to efficiently request orders from the database based on the users current location.
• extras (Map)
  The extras map contains additional information about the order. The exact values given in the map depend on the type of the order. All clients should make sure to implement default states for the fields given in this map, as they might not always be given.
  • car_necessary (Boolean)
    Defines whether a car is necessary, or at least recommended to execute the order. Assume false if this field is missing.
  • prescription (Boolean)
    Defines whether the user has to get a prescription from the caller before executing the order. Assume false if this field is missing.
• raw (Map)
  This map contains the raw data that have been gathered by the bot. They are only for debug purposes and should not be used by the apps.
• status (String)
  The status of the order. There is a set of predefined stati:
  • open: The order is open for users to execute.
  • in_progress: A user is currently executing the order.
  • closed: The order has been executed. The caller no longer needs help.
  • invalid: There are some inconclusive data, or there was an error while processing the bots data. Clients should not display orders with this state
  • Any other string values are not allowed. If however there are other values, they should be interpreted as invalid.
• account_id (String)
  The id of the account of the user that is currently executing the order. This field is only valid while status == in_progress.

Example

An example document /locale/de/order/abcdefgHijk5mnopqrsT could look like this (JSON representation of the data):

{
  "type": "groceries",
  "urgency": "today",
  "name": "Jane Doe",
  "phone_number": "+49123456789",
  "address": {
    "street": "Adalbertstraße",
    "house_number": "5a",
    "zip": "36039",
    "city": "Fulda"
  },
  "location": {
    "gps": [50.55856° N, 9.676204° E],
    "geohash": "u0yzs5vuzys"
  },
  "extras": {
    "car_necessary": true,
    "prescription": false
  },
  "status": "in_progress",
  "account_id": "abcdefghi6KLmn0pqrst"
}

Log collection

TBD

Document structure

TBD

Example

An example document /locale/de/order/abcdefgHijk5mnopqrsT/log/1585743824590 could look like this (JSON representation of the data):

{
  "timestamp": 2020-04-01 14:23:44,
  "account_id": "abcdefghi6KLmn0pqrst",
  "message": "assigned"
}

Feedback collection

TBD

Document structure

TBD

Example

TBD

Account collection

TBD

Document structure

TBD

Example

TBD

Access control

TBD