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 :
Ensuring the vehicle / person took the designated route
Checking if all pickup/dropoff locations are visited
Monitoring if a restricted location is visited
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.
Client side devices may have network bandwidth constraints, hence the communication between client and Tracking service should be optimized on data.
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.
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
Rule management schema
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)
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
|
Last updated
