Application services

Edit me

Logistics service

Logistics service is the core service of this platform providing most of the Supply chain and logistics management services, which includes Inventory management, Order management, Master data, configuration and supporting services. This is a monolithic application, orchestrating the SCM functionality listed below. This service provides rich REST APIs with JSON payload. Service is usually deployed in a tomcat web server, and run inside a Docker container. Tomcat is a web server and a Servlet/Java server pages container. It is often used as an application server for web based applications but does not support entire suite of Java Enterprise Edition specification. Tomcat is a stable and popular open source product.

Internal composition of this service is based on a layered approach. A layer is a logical partition to separate concerns of the system. Each layer is assigned its unique responsibility in the system. Each layer as logically separated from one another, and loosely coupled with the adjacent layer. The service architecture can be represented as layers illustrated by the diagram below:

API layer

Spring MVC controller framework is utilised in building the REST APIs. Request, Response and Error handling is taken care of by the framework. This allows the developers to delegate the request to Service layer with ease, and where there is a need to compose complex objects this layer relies on builder pattern.

Business object layer

The Business layer implements the business rules for the application. It hosts the business service components as well as business objects. These Business Services include the BO’s include the dependent JAVA classes that will provide service API’s to the business rules and operations required by the application. Business components are software units, and process business logic.

The business components implement the following:

• Business rules, such as calculations and validations

• Interfaces between the user interface and the resource layer

The business logic layer runs under the “Application Server” environment. Application Servers provide support for transaction control, thread management and other run-time services that make application development much simpler and more reliable. Business components are generally computation-intensive. They use Data Access objects (DAO) to communicate with the database. The Business layer will constitute of:

• Java Beans and Java Classes: Java Beans are used to manage the data flow between the layers. Java classes on the other hand are simple java objects that provide utilities to the application. They may also contain business logic and provide other supporting services

Data access layer

Data Access Objects using Java Data Objects (JDO) will manage the interface to the database. JDO is Object Relational mapping framework. Persistence can be complex in large applications using protocols like JDBC. Neither the client nor the business component needs to be aware of this complexity. Moreover there are many forms of storage from databases, to flat files. Decoupling the persistence logic from the business components and client allows for a flexible, easy to maintain application. The Data Access Object (DAO) pattern allows for the abstraction of the persistence from the business component. The Data Access Object manages the connection to the data source to obtain and store data. It encapsulates all access to the data store.

Components

Logistics service constitutes of different components. It primarily exposes REST APIs that can be consumed by all client tier applications. Figure below shows the tier wise components along with their interactions in a nutshell. Subsequent sections talk about each component in brief.

Security filter

This is the entry point of the application configured as the filter in web application. All requests would first land on this filter before being forwarded to corresponding route implementor as defined in web.xml or Spring’s dispatcher. It ensures user is authenticated to the application. It doesn’t perform authorisation. Authorisation will be the responsibility of the individual Spring controllers. It also ensures that appropriate version of web application is being used by the client.

Spring MVC

REST API implementation relies on the Spring’s MVC framework. Spring MVC defines a neat framework via configuration and annotations to define controllers that receive the request and a mapping between request and controller using the dispatcher servlet configuration. All controllers use annotations to defined the route they process and for which method type. It also provides a simple mechanism to convert the request json data to a model object on server and vice versa. GSON based http converter will be configured for this purpose.

Servlets

Servlets have been derived from the old logistics application which did not have the spring MVC framework. To ease the migration effort, Servlets which provide mobile application APIs and background task jobs like SMS notifications will continue to remain. Routing to the servlets and security is controlled via the web.xml and Security filter.

Authentication and authorisation

Authentication module provides basic authentication using the username and password , and stores the authenticated users details to the current session. This can be later retrieved from the Session manager to detect whether user’s session is authenticated. It also provides API tokens for users, along with clean up tasks to revoke user token or revoke a user session.

Authorisation part of this module utilises the other modules to check whether User has access to a Kiosk or a domain etc depending on the user’s role.

Configuration

Configuration module provides CRUD operations on domain and system configuration. It uses JSON to store the domain configuration. It also provides services to push configuration to all child or parent domains. It only support look up by domain id or configuration type at this time, no querying capabilities yet.

Master data

Master data modules include the ones for Users, Kiosks, Materials, Domains and Assets. They all provision basic CRUD operations on domains along with ensuring an integrity constraints and applying business rules to mange these objects.

Orders

This module provides functionality related to the Order management. Some of the functions it support are CRUD of Order, payment updates , querying demand data etc. It also invokes Transactions/Inventory module to update them when the Order status changes. Accouting information also gets updates when payments or posted or cancelled.

Inventory

This modules provides functionality related to Inventory management. It will support operations for CRUD of Inventory items, Posting transactions to update the inventory, managing the inventory log, tracking the abnormal stock events.

Accounting

Accounting module captures the payable and receivables of Kiosks and across domain via orders.

Assets

Assets module in logistics application provides functionality to manage assets registered to entities , and display temperature status of the assets in the application. It consumes and posts data to asset management service.

Reports

Reports module will provide access to the reporting/aggregating data. Reports include inventory trends, transaction counts, login counts, order response times etc.

Entities

The Functional Module on Entity models real-world Kiosks (also called Entities or Stores in other parts of this literature), and encapsulates the services and utilities built around it. It represents any entity that holds inventory (e.g. retail store, warehouse, distributor, transporter).

Materials

Material module encapsulates services and utilities for managing the master material data.

Users

This module is responsible for managing the users along with their roles. It supports functionality to specify routes for users, disabling and enabling users etc.

Domains

A domain represents an administrative boundary within a supply chain, wherein a set of entities are managed or administered by a particular user or set of users. A domain can be linked to another domain (i.e) it can be added with in a domain. The top level domain is called parent domain and the inner domains are called child domains. The users are visible only in their domain. The entities, materials, transactions and orders created at child domains are made available at parent domains.

This module will encapsulate all services related to managing the domains, from CRUD operations to creating links and managing permissions of the domains.

Events

Events can be generated by many operations by the application , as defined in the notifications configured for the domain. For example: Inventory updated, Stock went to zero, Order updated. This module is responsible for generating events based on rules defined in notifications.

Crons

Cron jobs module is responsible for executing scheduled , repetitive tasks configured. Common uses are for scheduling aggregations, custom reports and daily exports. It also handles fail over in the event of failure of master service.

Caching

Application will use Redis as caching layer. This module abstract the interaction between application and the caching. It will use Jedis library to connect to Redis server using sentinels.

Media Storage

Storage service layer in application abstracts the interaction between the Hadoop file storage. This will be leveraged to store generated custom reports, exports, media files etc.

Callisto client

A Callisto java client to get data of registered queries and reports in Callisto.

Tasks & Exports services

Logistics service is also run as task and export service in production environments in separate instances, so as to not impact the users using the application. This service when run in tasks mode accepts tasks from ActiveMQ and execute those. System supports a wide range of tasks, some examples include daily emails, SMS notifications, Inventory optimisation, Prediction tasks. When run in exports mode, It consumes all exports and custom reports exports jobs from the ActiveMQ. Custom report generation uses Apache POI, which is memory intensive to generate excel files. This impacts even the background tasks running, and hence needs to be run separately.

Asset monitoring service

Asset management is the systematic process of managing the lifecycle of assets, typically equipment and infrastructure (in our context; but different in financial context), contained within an organisation. It is the systematic process of deploying, operating, maintaining (including repairing), upgrading and disposing assets cost-effectively. This service handles complete lifecycle of assets, and provides APIs in two level, one is device facing APIs and another one is application APIs. Device APIs are used to record the asset temperature, alarms, stats, device ready and configuration pull and this APIs are used by temperature loggers. Application facing APIs are used by Logistics Service(LS) to create, manage assets.

Components

Play framework

Play Framework makes it easy to build web applications with Java & Scala. Play is based on a lightweight, stateless, web-friendly architecture. Asset management service was originally built to run on Heroku cloud. Play provides a web container with configurable routes to map request URLs to methods.

JPA

The Java Persistence API (JPA) is a Java specification for accessing, persisting, and managing data between Java objects / classes and a relational database. Application uses Hiberante implementation of JPA spec to connect with databases.

Infrastructure services

AMS also leverages the common infra structure services similar to that of Logistics application for running cron jobs, background tasks etc.

Authentication and Authorisation

AMS as such doesn’t have human users. This service is primarily designed for consumption of Logistics application and sensor devices. The authentication is simpler for this reason. It manages the API passwords via system configuation which is shared with the applications. Password is accepted as a basic digest in request header.

Mobile API Gateway

API Gateway is a type of service in a micro services architecture which provides a shared layer and API for clients to communicate with internal services. The API Gateway routes requests, transform protocols, aggregate data and implement shared logic like authentication. This is entry point to our micro services world.

Forces for using an gateway service in a micro services system

• APIs provisioned by different micro services are often too granular for client apps to consume.

• Different clients need different data, web apps might need full inventory details along with search, where as a mobile app might fetch only meta information.

• Services might use a diverse set of protocols.

• Clients would need to collate data from multiple micro services, a gateway simplifies.

API Gateway is implemented in NodeJS for the following reasons

• Easy and quick to develop APIs, using express framework.

• Native support to perform async operations, handling large number of client requests.

Locations service

Locations service manages Geo information like Countries and their administrative divisions including state/provinces in a country, districts/county in state, taluks in a district and cities defined within using HTTP requests. A Spring boot based micro service using Maria DB storage and Redis caching.

Collaboration service

Collaboration service provides all features related to social and community features, which include Likes, Comments, Conversations, and so on. A Spring boot based micro service using Maria DB.

Event summarisation service

Event summarisation is a capability that summarises key events in the system. Summary is generated a text templates using Velocity template engine. This service acts as a bridge between the event summary analytics, and Logistics service to compose the text. A Spring boot based application that uses velocity templates, Callisto service and other services to build summary text in multiple languages on demand.

Approvals service

Approvals service allows to orchestrate approval workflows with features to expire, escalate requests, comment and state transitions of the approval. Orders module in Logistics service leverages approvals service to enable the Order approval workflows, specifically the following use cases. Orders (sales/purchases/transfer orders) may need to be approved by a designated authority, before the order becomes valid and visible to the relevant stakeholders. The designated authority would review the quantities or terms specified, and possibly communicate with relevant stakeholders before making it a valid order. In other words, the store manager would make an “approval request” (or “requisition”) for order approval to his/her approving authority, who in turn may review the terms (quantities, pricing, etc.) and approve the requisition. Once approved, the order becomes a valid order in the system and is visible externally. A Spring boot based micro service using Maria DB.

TL SMS API service

Most Temperature loggers can communicate via SMS channel, when data network is not available. These SMS messages are sent to a gateway number, which are then routed to the TL SMS API service. This service acts as a port which translates the incoming SMS messages, constructs API requests that are sent to Asset monitoring service. The SMS protocol and the commands supported by the device usually vary by vendor. Some devices support two way communication which include sending temperature updates, accepting remote configuration commands, and query requests. This API service uses play framework for exposing REST APIs to be used by the SMS Gateway, and communicates to SMS Gateway directly when there are commands to be sent from the server.

Logistimo presently supports RelyON, Nexleaf, Nimble wireless, Berlinger, and more.

Callisto service

Callisto is a data engine, which simplifies generating REST APIs for querying and fetching data from analytics and other master data sources. This service provides a REST interface to register queries and databases, execute a queries registered. It contains a powerful query engine that allows one

• to specify filters on the registered queries dynamically

• to mix queries of multiple datasources

• to apply custom functions on the response

• to paginate the data

A Spring boot micro service which uses Mongo for storing queries and dashboards, connects with Logistics, assets and analytics database to generate reports data.