Technical documentation

This is the main documentation for eRouška project.

Terminology

FUID

Firebase User ID, unique for each phone number, generated by Firebase Authentication after sign-in, 28 chars or more.

BUID

Broadcasted user ID, unique for each registration, generated by Firebase function after registration, 10 bytes

TUID

Transmitted user ID, actually transmitted over Bluetooth, each BUID gets about 100 TUIDs after registration, client picks a different one every hour or so, privacy measure to prevent tracking individual device/user, 10 bytes

Data format

Firebase Firestore

Firestore is not readable or writable to user, only Functions.

Collection users

• Key: FUID

Attributes:

• createdAt (timestamp of creation)
• registrationCount (number of BUIDs)

Collection registrations

• Key: BUID

Attributes

• fuid
• platform (android/ ios)
• platformVersion (system version, e.g. 10.0.4)
• manufacturer (phone manufacturer, e.g. Samsung)
• model (phone model, e.g. Galaxy S7)
• locale (phone language, e.g. cs_CZ)
• createdAt (timestamp of creation)
• pushRegistrationToken (push token from Firebase Cloud Messaging)

Collection tuids

• Key: TUID

Attributes

• fuid
• buid
• createdAt (timestamp of creation)

Firebase Storage

User can only upload data about his FUID, can't read other data.

Collection proximity

• Key: FUID/BUID
• Filename: $timestamp.csv

Metadata

• version (version of CSV model, current 4)

CSV columns

• tuid
• timestampStart (millis)
• timestampEnd (millis)
• avgRssi (average signal strength)
• medRssi (median signal strength)

Firebase Functions

Main API for the app and other parts of the system, scales automatically, region: europe-west3

Input and output are dictionaries. Functions doesn't return anything, unless specified here (but can throw error).

registerBuid

Creates a new registration after authentication.

Input

• platform: string (android/ ios)
• platformVersion: string (system version, e.g. 10.0.4)
• manufacturer: string (phone manufacturer, e.g. Samsung)
• model: string (phone model, e.g. Galaxy S7)
• locale: string (phone language, e.g. cs_CZ)
• pushRegistrationToken: string (push token from Firebase Cloud Messaging)

Output

• buid: string (created BUID)
• tuids: string[] (list of TUIDs)

deleteUploads

Deletes all CSVs for one BUID.

Input

• buid: string

deleteBuid

Deletes all data related to BUID.

Input

• buid: string

deleteUser

Deletes all data related to FUID, including phone number in Firebase Authentication.

changePushToken

Changes push token for BUID.

Input

• buid: string
• pushRegistrationToken: string

isBuidActive

Checks if FUID and BUID still exists

Input:

• buid: string Output:
• boolean (active/inactive)

Firebase Remote Config

Contains constants which we can changed later without updating the app.

Default values

Processes

Device Registration

1. App asks the user to enter the phone number.
2. App sends the phone number to Firebase Authentication.
3. Firebase sends back SMS with verification code
4. User verifies the device registration by entering the verification code from the SMS into the app (This is done automatically on most devices.)
5. After a successful authorization, the app finishes the registration by calling the registerBuids function.

Integration with Smart Quarantine (Chytrá karanténa)

1. An epidemiologist asks the user for the permission to use the data from eRouška and asks to upload the data.
2. User gives permission by tapping "Upload data" in the eRouška. CSVs can be uploaded only once per 15 minutes. The file is saved in Firebase Storage in the collection proximity.
3. Every 30 minutes Keboola creates a phones.csv file with phone numbers in a dedicated AWS S3 bucket.
4. Epidemiologist uses a web GUI to see a data for a particular phone number:
   1. Web app fetches a FUID related to the phone number.
   2. A blob is loaded for the particular FUID from the Firebase Storage.
   3. After the raw data is analysed, the TUIDs of people the person met are loaded from the blob, with:
      • their respective phone numbers from the collection users
      • a flag representing whether the person met was in close contact or not
      • their respective device names
   4. Epidemiologist contacts the possibly newly infected.