> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/sanitation/community/community-project-vehicle-tracking/architecture/vehicle-tracking/low-level-design.md). # 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](https://docs.google.com/document/d/139o9uT-7lR3L9TP8nwKKdwKtwxfKPUlcD-vrRCNRlsU/edit#heading=h.4xc9v8n4mj). #### 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 ![](https://lh7-us.googleusercontent.com/OfXKaYJ2rTfneZQ114ODl-m-33VSXln_Fy7PDYwE4EMBZh3bPJ2QPcSSU7pYi_EkwutGJ1ecrZvo_JBj38Mgj1Ovd7K_v9zGYbW04YcQHEa11dTD6bBwG0qUNBLJ6xjp3W-NKebeG9xZ6XS2gJDRXP8) [PlanUML link with source](https://www.plantuml.com/plantuml/uml/ZLBDYjim4BxhAKIEXhn0MPPTsh0OKYSallHKL6lOJAiV8OrAmsxVlPApHd5id5vq6Cqtty_CKo3XAMh5mYyqJdYXkK83T7R0hQUJPIUKm3lqdGB6m13IcQ_skth5trY5ad_Y17-8Fpp4YFBnaQtNh5As4uJMD4B3HmEh4XN5KFh1H9twgymrhGe5dahvPx0cbsC0Nm-ah78sO2RQMpIvE-bgsbBUeicZjtMpERQ7kdcvHgZpgpKzPlljPTUmlyNUmKQ25LzmsEUMM2UV5HWvMpV_aqLo0Lw3H46GfeHx0LnfRZswfPtux2aZ5uLP1rwGzLFYnFiRE_XivLqROv7b79xpJgUURapilNtr4CAI6KfzCrxS1_G0pde2sQA6qbGVTz-_FBURjlwwISrZaVEND0nS7AG5TIV8Mx-LD3QtlOxXSbrTIVFY2qd1p7AFb_3RiuFL3Ovdu7Y9KVqOdGXBPlZx-tfjttX_sgn_Xr8EdUMd5CeMMA4U0qPkXfz4DF-H8Ld6BCKJ61cr-WS0) Rule management schema ![](https://lh7-us.googleusercontent.com/WG3_TTmDoWf1j3KLI2E3J8fbcy-BrVcJYYTZgjtTEY-VE6GIwWPdg6rlalViAmm0a4hbELV1EUi-zYGCKKwq1DHx4WdrZUw4hLmaubKiyM29hmK6wPP-PaO7utPytIwSbu3wN3zM2PJUXvUmzUr9Gkw)
[PlantUML link with source](https://www.plantuml.com/plantuml/uml/RO_1QiD034Jl-WhXey4_K4m8zDH3Bsr-OF4AHtIjNMHjgKdwxxNQqgHERcAOcQVPpnRKwfHWVcCfGSE4YOLiAOHPxPZXo95mO1qI0P0OsuBDIqtKu0bQNO_7l3eUqEZ3eEkWZJGFoiKuow-CqF9KaXl_bC__RS-X59QnGM_bkDfOZ4PIxFjGBNSZ2MamYhkTKpPaHnX947kA5sKcVUVXshR57fJBzn1RZqkqxsjb9zqTkDdYdTw5vtFNvHDUpRdHdGUlFsyTbd8tuvwR3En9OftI5m00) **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) ![](https://lh7-us.googleusercontent.com/p6nDG2sGhJCdaIsCGGtGYVDKpOQOrfwBQpCOAnnuFJcyMUEjZHN3hcjeGDGJuF1MIWt8gU6xM4opvUxKyZVkNXNwvUChsTt97PED-MB45Rzu6gnZyh8UBeLpVO57EYjfmSMxGKYQR97I8I0MIPC8H7c) [PlantUML link](https://www.plantuml.com/plantuml/uml/dL9DZzCm4BtdLunwu5HlilrGQQM51QqgSIW7kk9K2Jds91cHs9OzYSI_nsu8jAk2W9CzdkStRsRUOs3fkU_QJ2gs7hId0JraBhwI8YSDWtGEP83PmPRKOWfdL_dFpyUNyTFxyuzu0orPbZBWzP_zuNX6f3EW7qX5G5PxspkOFL5mhVm6xCa580FTHUKV2iMR5C8ESkae7vPv0kTV0aglcYob8YBLtu7ikM7x5SryQe_q71XD4a8wIwW8Jb9si4TMJQ9kIKacQy3qNOa-d4nbFN23lqWoOnd1Kztm3Xfc5tPvtXkg2BNGEDnfgedlhA_pAdJvS3_fUpiM_w0VN7adEqySf3-PLoDpV5QgMcsthvN0ZQp42bTQoEsc4kkjMj-NPRLQu_gMxZG4qCYIsW2LZPpSuArk_a7wW0sf5iS1N_GGkMztuR52RnH-jE7XljY8_V4W5iLYAOgjM2n4KHJBnNB-kyngwcjSRwgQzZLUZEnm3e4bzs5-CcVpGessjMDxyKrZO3Bdw38pMM8SSIJ-XC5P4p13etywxvW8nr9_ijs5loQrPzE_uBBk_wakjdl5-fm8dRUrnn2WTreoXjbV2NhNekVa3bHf8hC9UVjJzXYFlck_0m00) ### 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 \ | 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 \ | 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


| \
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digit.org/sanitation/community/community-project-vehicle-tracking/architecture/vehicle-tracking/low-level-design.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.