Low Level Design

Overview

Urban Local Bodies (ULB) and other government agencies provide citizen centric services. Some of these services involve/require movement of people or assets(eg : vehicle, equipment etc). Below is a sample list of such services:

• Pickup of Fecal sludge from a citizen’s premises and offloading at a designated place

• Garbage pickup truck visits multiple collection points and deposits the load at a designated waste segregation yard

• ULB assigns a drinking water tanker to supply water to schools in a particular area. The water tanker visits the assigned schools and supplies the required amount of water.

• Fumigation to contain mosquitoes spread involves an operator moving in a 2-wheeler from one street to another.

• Medicines have to be moved from district headquarters to mandal level villages.

Key challenges in the above scenarios are :

1. Ensuring the vehicle / person took the designated route

2. Checking if all pickup/dropoff locations are visited

3. Monitoring if a restricted location is visited

4. Tracking of live location

Challenges listed above are solved with a new tracking service component. This document captures the technical design of such a tracking service. For functional use cases related to a specific citizen service (Fecal Sludge Management), please refer to this doc.

Design guidelines

Tech design for Tracking service addresses following key design goals. These goals are derived from DIGIT’s view of how a service should evolve and also the constraints arising from the usage of client side application.

1. Client side devices may have network bandwidth constraints, hence the communication between client and Tracking service should be optimized on data.

2. Tracking service should be generic enough to handle any kind of citizen services that involve movement of assets or service delivery by an operator on move. Type of service being rendered decides the monitoring rules (alerts, notifications) that are applied to the trip.

3. Within the DIGIT platform, event based models processing should be used so that newer applications can be plugged in by consuming the event messages.

Tech design

Components

Below is the list of entities, actors and tech components involved in tracking service.

Entities

• Point of Interest (POI) - Latitude, longitude coordinates of various locations. Types of locations include citizen pickup point, intermediate points, destination location, polygons to identify larger areas and tags to identify anomalies (like illegal dump yards).

• Designated route - A sequence of POIs which indicate the route an operator should take.

• Trip - Created for each service delivery involving an operator. It is either created based on request or through an automatic scheduler. Trip is made up of operator details and designated routes. Actual route taken by the operator is also associated with the trip.

Actors

• Supervisor - Individual is responsible for making configuration level changes. These can be two separate roles or just one

• Operator - Travels from source to destination of a trip as part of service delivery.

• System - Tracking service has the intelligence to take some actions on its own.

Tech components

• Mobile App - User facing application to manage routes, trips and POIs

• Tracking service - Stores entities, applies automated rules and generates alerts.

Low level design

Tracking service

Controller classes

• ConfigController, PoiController, RouteController, TripController

Service classes

• ConfigService, POIService, RouteService, TripAlertService, TripService

Data access

• ConfigDao, PoiDao, RouteDao, TripAlertDao, TripDao, TripProgressDao

Service access

• POISao, TripSao

Model

• FsmApplication, FsmVehicleTrip, TripAlert

Trip monitoring module

Monitoring logic

Trip data store

Database schema

PlanUML link with source

Rule management schema

PlantUML link with source

3.4.6 Use case to API mapping (with FSM integration)

Vehicle tracking system (VTS) and FMS are the two systems that provide these APIs

Driver use cases (mobile app)

PlantUML link

Appendix

Appendix A - REST APIs for client applications

Note -

(i) Additional attributes will be added to cater to integration with other entities within the DIGIT ecosystem. For example, Tenant Id, User Id, ULB id/name, auth token etc

(ii) All API requests will include timestamps and other information necessary for auditing.

a.1. /poi/_create (Implemented)

Request message

Name	Type	Mandatory?	Comments
locationName	Text	Yes
locationDetails	Array	Yes	List of locations that are part of a POI. This can be a single LatLong or group of LatLongs (line, polygon)
locationDetails -> lattitude	Decimal	Yes
locationDetails -> longitude	Decimal	Yes
alert	Array of Strings	No	One or more alert codes can be mapped to the point of interest. This is optional and can be set only in cases where the POI is related to some illegal dump yard etc
userId	Text	Yes	DIGIT user id of the individual performing the create operation

Response message

Name	Type	Mandatory?	Comments
responseCode	Text	Yes
responseMessage	Text	Yes
id	Text	No	GUID of the POI created on success

a.2. /poi/_update (Implemented)

Request

Name	Type	Mandatory?	Comments
id	Text	Yes	POI to be updated
status	Text	No	Can be set to active or Inactive
locationName	Text	No
userId	Text	No	DIGIT user id of the individual performing the create operation

Response

Name	Type	Mandatory?	Comments
responseCode	Integer	Yes
responseMessage	Text	Yes
id	Text	No	GUID of the POI updated

a.3. /poi/_search

** Additional search filters will be added to restrict the results to ULB, user role and other related restrictions.

Request

Name	Type	Mandatory?	Comments
poi_id	Text	No
poi_status	Text	No
location_name	Text	No
location_lattitude	Decimal	No
location_longitude	Decimal	No
geofence_radius	Integer	No
illegal_dumpyard	Boolean	No

Response

An array of below objects will be returned for the POIs matching with search criteria.

Name	Type	Mandatory?	Comments
poi_id	Text	Yes
poi_status	Text	Yes
location_name	Text	Yes
location_details	Array	Yes
location_details -> location_lattitude	Decimal	Yes
location_details -> location_longitude	Decimal	Yes
location_details -> geofence_radius	Integer	Yes
location_details -> illegal_dumpyard	Boolean	Yes

b.1. /designated_route/_create

Request

Name	Type	Mandatory?	Comments
designated_route_name	Text	Yes
designated_route_status	Boolean	No	This will be used to inactivate a route when needed Default value is true.
start_poi_id	Text	Yes
intermediate_poi_id	Array <Text>	No	Defaults to null
end_poi_id	Text	Yes
designated_route_traversal_time	Integer	No	Estimated time to complete a trip on this route. Default value is 0.

Response message

Name	Type	Mandatory?	Comments
response_code	Numeric	Yes
response_message	Text	Yes
designated_route_id	Text	No	GUID of the Designated route created on success

b.2. /designated_route/_update

Request

Name	Type	Mandatory?	Comments
designated_route_id	Text	Yes
designated_route_name	Text	No
designated_route_status	Boolean	No
start_poi_id	Text	No
intermediate_poi_id	Array <Text>	No
end_poi_id	Text	No
designated_route_traversal_time	Integer	No

Response

Name	Type	Mandatory?	Comments
response_code	Integer	Yes
response_message	Text	Yes
designated_route_id	Text	No	GUID of the Designated route updated

b.3. /designated_route/_search

** Additional search filters will be added to restrict the results to ULB, user role and other related restrictions.

Request

Name	Type	Mandatory?	Comments
designated_route_id	Text	No
designated_route_name	Text	No
designated_route_status	Boolean	No
start_poi_code	Text	No
intermediate_poi_code	Text	No
end_poi_code	Text	No
start_poi_name	Text	No
intermediate_poi_name	Text	No
end_poi_name	Text	No

Response

An array of below objects will be returned for the designated routes matching with search criteria.

Name	Type	Mandatory?	Comments
designated_route_id	Text	Yes
designated_route_name	Text	Yes
designated_route_status	Boolean	Yes
start_poi_code	Text	Yes
intermediate_poi_codes	Array	No
end_poi_code	Text	Yes
start_poi_name	Text	Yes
intermediate_poi_names	Array	No
end_poi_name	Text	Yes
designated_route_traversal_time	Integer	No

c.1. /trip/_create (Implemented)

Request

Name	Type	Mandatory	Comments
routeId	Text	Yes	Predefined route id, which has the list of POIs for that the trip should follow
serviceCode	Text	Yes	Type of service the trip is performing
status	Text	Yes	Client passes “created” value initially
operator	Object
operator -> id	Text	No	DIGIT user id of the operator delivering this service
operator -> name	Text	No
operator -> email	Text	No
operator -> contactNumber	Text	No
operator -> vehicleNumber	Text	No
plannedStartTime	Text	No
plannedEndTime	Text	No
userId	Text	Yes	DIGIT user id of the person performing this create activity

Response

Name	Type	Mandatory?	Comments
responseCode	Text	Yes
responseMessage	Text	Yes
id	Text	No	GUID of the trip created on success

c.2. /trip/_update

Request

Name	Type	Mandatory	Comments
trip_id	Text	Yes
trip_designated_route_id	Text	No
trip_expected_start_time	Text	No
trip_expected_end_time	Text	No
trip_current_status	Text	Yes

Response

Name	Type	Mandatory?	Comments
response_code	Integer	Yes
response_message	Text	Yes

c.3. /trip/_progress

Request

Name	Type	Mandatory	Comments
trip_id	Text	Yes
location_details	Array	Yes	Array is used to support bulk updates in case the device comes online after being offline during a trip.
location_details -> location_lattitude	Decimal	Yes
location_details -> location_longitude	Decimal	Yes
location_details -> progress_timestamp	Text	Yes

Response

Name	Type	Mandatory?	Comments
response_code	Integer	Yes
response_message	Text	Yes

c.4. /trip/_search

** Additional search filters will be added to restrict the results to ULB, user role and other related restrictions.

Request

Name	Type	Mandatory	Comments
operatorId	Text	No	DIGIT id of the person to whom a trip is assigned
tripName	Text	No	Partial name search is supported
status	Text	No
userId	Text	No	DIGIT id of the person who created the trip

Response

Array of trips is returned

Name	Type	Mandatory?	Comments
id	Text	Yes	Trip id
routeId	Text	No
serviceCode	Text	No
status	Text	No
operator	Object	No
operator -> id	Text	No	DIGIT user id of the operator delivering this service
operator -> name	Text	No
operator -> email	Text	No
operator -> contactNumber	Text	No
operator -> vehicleNumber	Text	No
plannedStartTime	Text	No
plannedEndTime	Text	No
userId	Text	No	DIGIT user id of the person performing this create activity
actualStartTime	Text	No
actualEndTime	Text	No
locationAlerts	Text	No	Alerts are assigned by backend service, in case the operator takes a path that triggers an alert

c.5. /trip/_search/{tripId} (Implemented)

Request

Name	Type	Mandatory	Comments
id	Text	Yes	Trip id to be searched for

Appendix B - Event data examples

Event type = LocationUpdate

Event data

{

“latitude” :

“longitude” :

“update_time” :

“trip_id” :

}

Event type = TripAnomaly

Event data

{

“anomaly_poi_id” :

“duration_at_poi” :

“update_time” :

“trip_id” :

}

Event type = TripComplete

Event data

{

“update_time” :

“completion_time” :

“trip_id” :

}

Appendix C - API to Database mapping

Mobile app

Use case	VTS database fields
User login functionality	VTS is not used. DIGIT user login API is invoked
List of trips assigned to driver	VTS API is called but all data is retrieved from FSM vehicle trip APIs. Additional details stored in VTS db: Trip.status Trip.id Trip.routeId Route.Id Route.startPoi Route.endPoi
Trip details	Trip details are fetched from FSM vehicle trip API. VTS does not store trip details in its db
Trip progress once vehicle moves	VTS db stores trip progress information: TripProgress.id TripProgress.tripId TripProgress.progressReportedTime TripProgress.userId TripProgress.positionPoint TripProgress.progressTime
Illegal dumpyard creation	Illegal dumpyard details are stored in VTS db: POI.id POI.locatioName POI.type POI.positionPoint POI.positionLine POI.positionPolygon POI.alert

FSM portal

Use case	VTS database fields
Trip details	Fields in VTS db: Trip.id Trip.status Trip.actualStartTime Trip.actualEndTime TripAlert.id TripAlert.tripId TripAlert.alert TripAlert.alertDateTime
Trip actual route details	Fields in VTS db: TripProgress.id TripProgress.tripId TripProgress.progressReportedTime TripProgress.userId TripProgress.positionPoint TripProgress.progressTime