Engineering Documentation

Overview

Kotlin and Koin

Work in progress

Data and Entity Model

The data stored by Treetracker app on the device is structured as Entities used by the Room persistence framework. The following is the list of these entities with brief description.

PlanterInfoEntity - Stores planter information when user registers on a device
PlanterCheckInEntity - Stores the check-in log of a planter
TreeCaptureEntity - Stores the details of a tree tracking activity
TreeAttributeEntity - Stores additional attributes of a tree during a tracking activity
LocationDataEntity - Stores the GPS data of the device when planter is taking the picture of a tree

Entity relationship diagram

The following diagram gives an overview of the entities and their relationship with each other.

Entity data definition

All the entities, the fields and their description are tabulated below

planter_info

Holds the user information when planter registers on a device. A device may have multiple users and thus this table might have more than one record in a device.

column	Description
`_id`	The primary key for the table
`identifier`	string variable that stores `email address` or `phone number` to uniquely identify a planter. Note that this uniqueness constraint is not defined in the entity definition but in the application code.
`first_name`	first name of the planter
`last_name`	last name of the planter
`organization`	An optional field that stores the name of the organization the user or planter registered on the device belongs to.
`phone`	Currently not being used in the app
`email`	Currently not being used
`latitude`	GPS location data of the registering user
`longitude`	GPS location data of the registering user
`uploaded`	A flag to identify whether the registered user info has been uploaded or not
`created_at`	Unix time at which the user registered
`bundle_id`	Usage yet to be determined Note
`record_uuid`	This UUID is only for detecting duplicate inserts later in the greenstand pipeline, it has no significance in identifying the planter.

Note: <a name="Usage-Note"/> This attribute must have been added
earlier for some reason that the document creator has not yet determined.

planter_check_in

Holds the details of each check-in of a planter logging the time and reference to the planter_info id and a photo url. This entry is used as a reference by the tree_capture entity to associate the tree tracking entries to identify the planter.

column	Description
`_id`	Autogenerated primary key of the table
`planter_info_id`	The reference to the `planter_info` record to associate this check-in to a specific planter
`local_photo_path`	Stores the path of the picture of the planter taken during a check-in
`longitue`	GPS location data of the planter during check-in
`latitude`	GPS location data of the planter during check-in
`created_at`	Unix time at which the planter checked in
`photo_url`	Usage yet to be determined Note

tree_capture

Holds the details of each individual tree tracked by the app. Each record has associated planter_check_in reference identifying the planter tracking the individual tree.

column	description
`_id`	Autogenerated primary key of the table
`uuid`	A UUID for the new tree tracker acitivity logged in the device
`planter_checkin_id`	A reference to the record in `planter_check_in` associated with this tree tracker activiy
`local_photo_path`	The path of the tree image taken during a tree tracking activity
`photo_url`	Usage yet to be determined Note
`note_content`	Holds any note taken during the tree tracker activity
`latitude`	GPS location of the tree obtained at the time of capturing its picture
`longitude`	GPS location data of the tree obtained at the time of capturing its picture
`accuracy`	GPS location accuracy metric from `android.Location` class
`uploaded`	A flag to denote whether a specific record in the table has been synced with the greenstand services for verifying tree growth and attributing the work to a planter
`created_at`	Unix time at which the tree tracking activity was created
`bundle_id`	Usage yet to be determined Note

tree_attribute

Holds one or more optional attributes of a specific tree associated with a record in tree_capture if capturing such attributes are enabled in the app. One such example is the height of a tree which is a feature that can be enabled in the app.

column	description
`_id`	Autogenerated primary key of the table
`key`	A value for the name of the tree attribute
`value`	The value for the tree attribute
`tree_capture_id`	A reference to the specific tree tracking activity recorded in `tree_capture` and thus associates this tree attribute to the specific tree tracked.

location_data

In addition to the GPS data stored along in tree_capture for each tree, additional location data is stored during the process where the planter initiates the "Add Tree" and is taken to the camera screen. From this moment when the camera is activated and until the time where an actual image of a tree is captured, any stream of location data streamed by the device is captured in this table. The location stream is triggered only when there is a detectable change in location by the device. This additional data is for improving the verification process at Greenstand in ascribing the planters work of tracking a tree and its growth.

The base64 encoded json data is obtained from the LocationData data class in the org.greenstand.android.TreeTracker.usecases.CaptureTreeLocationUseCase.kt class. This json contains the planterCheckInId attribute associating a checkin to the location data thus making it unnecessary to track the planter_check_in in the table.

Importantly, this table has no functional value for the treetracker application except for data collection for analysis.

column	description
`_id`	Autogenerated primary key of the table
`base64_json`	A base64 encoded json data containing location information of the device when the tree image capture is in progress. The json format is derived from the data class `LocationData` in `org.greenstand.android.TreeTracker.usecases.CaptureTreeLocationUseCase` class
`uploaded`	A flag to denote whether the location data has been uploaded to green stand services or not
`created_at`	Unix time at the time location data is recorded