However, as teams and products scale, managing a single staging environment becomes complex.

Multiple features being tested on a single staging environment might see different behavior in production when one of them goes into production. Finding the root cause of bugs becomes harder and ensuring that new code wouldn't conflict with the current state of the staging environment becomes a daunting task, as shown in the following image:

Hence, it becomes important to create feature-specific disposable testing environments that are cost-efficient, scalable, easily manageable, and robust.

Here is how we, at Shipsy, built an ECS-EC2 Sandbox for UAT testing at scale and unlocked up to 70% of cost savings at the same time!

Sandbox - Design, and Architecture

A sandbox refers to a testing environment that isolates the production environment from untested code changes and direct experimentation.

Shipsy

The entire cluster, config files, branches, services, etc., are selected from the Sandbox dashboard, and this entire data goes to the backend server once the user clicks on the deploy button.

This data deployment kicks two actions - the entire data gets stored in the database and the backend server triggers a corresponding Jenkins Job that triggers the deployment script over the SSH.

Once the Jenkins job gets executed, it sends the build URL and updated deployment log to the database for visibility over the front end.

Configuring AWS Resources

We used the following AWS resources for Sandbox deployment:

Amazon ECS

Amazon ECS is a fast and highly scalable container management service that can be used to run, stop, and manage containers on a cluster. We use it for application deployment and scaling.

ECR

It is the storage of docker images on AWS. ECS pulls images from ECR to deploy.

ALB (Application Load Balancer)

We use the application load balancer to distribute incoming traffic among EC2 instances.

Security Group

This is used to control incoming and outgoing traffic for our EC2 instances.

DNS & Load Balancers

The Domain Name System (DNS) turns domain names into IP addresses, which browsers use to load internet pages.

Load Balancer acts as a reverse proxy and distributes the incoming traffic across multiple targets, such as EC2 instances, containers, and IP addresses.

We have a specific domain name convention that we have optimized for our use case:

https://<sandbox-name>.<service-name>.shipsy.io

We have also created a wildcard subdomain in AWS Route 53, where our DNS zone is present:

*.demoprojectxsandbox2.shipsy.io

This DNS record is mapped to its corresponding application load balancer DNS name. Then the load balancers forward the request to AWS Target Group using HTTP/HTTPS listener rules.

HTTP/HTTPS listener rules examples:

Next, we use the Target Group to route requests to one or more registered targets, in our case EC2 instances. This Target Group has all the information such as the IP address of the EC2 instance, port, health check status, etc.

Load balancers have a listener rules limit and we have set the number of load balancers for our demo sandbox according to our use case.

The entire conversation flow goes like this:

DNS record → Application Load Balancer → Target Group → EC2 instance → Container

Take a look at the following image for a better understanding:

Deployment - Behind the Scenes

We have already mentioned that the backend server inserts user deployment data into the database and triggers Jenkins job with the parameter - newly created demo deployment log id.

Then, the Jenkins Pipeline executes the deployment script over SSH with the parameter - recently received log id, so that we can fetch necessary user deployment data from the database.

Next, we discuss the deployment script steps in detail.

1. Generate Code Folder

Here, we are generating the code folder in two ways:

• We clone the repository for an entirely new deployment
• We pull the latest custom branch of that repo in case of redeployment

const codePath = `${branchPath}/code`;
 if (!fs.existsSync(codePath)) {
   fs.mkdirSync(codePath);
   shellChangeDirectory(codePath);

   try {
     console.log(
       `git clone git@${repository}:shipsy/${repository}.git ${codePath}`
     );
     shellExecuteCommand(
       `git clone git@${repository}:shipsy/${repository}.git ${codePath}`
     );
   } catch (e) {
     throw `Couldn't clone the repository`;
   }

   try {
     shellChangeDirectory(codePath);
     compareProdLatestCommitWithCustomBranch(repository, branch);
     shellExecuteCommand(`git checkout ${branch}`);
   } catch (e) {
     if (e === errorCheck.HEAD_COMMIT_NOT_FOUND) {
       try {
         console.log(
           `Branch not up to date, trying to auto pull ${prefillDefaultBranch[repository]} branch`
         );
         shellExecuteCommand(
           `git pull origin ${prefillDefaultBranch[repository]}`
         );
         shellExecuteCommand(`git push origin ${branch}`);
         console.log(`Auto pull and push succeeded!`);
       } catch (err) {
         try {
           shellExecuteCommand(`rm -rf ${branchPath}`);
         } catch (error) {
           throw `Invalid branch ${branch}`;
         }
         throwErrorMsgForCommitDiff(repository);
       }
     } else {
       try {
         shellExecuteCommand(`rm -rf ${branchPath}`);
       } catch (e) {
         throw `Invalid branch ${branch}`;
       }
       throw `Invalid branch ${branch}`;
     }
   }
}

2. Generate Config Files

Here, the main challenge was ensuring individual service deployment with its correct config files which point to the deployed URL for deploying the entire cluster.

We overcame this by having the standard naming convention and by figuring out the number of rules needed for any deployment. We keep on looping through all the available sandbox load balancers and check for availability of all the rules in this single load balancer.

Hence, now we know that all the services are to be deployed on the same load balancer and we can easily predict the generated domain name for all services.

if (rulesNeeded !== 0) {
     for (const [index, arn] of httpsListenerARNs.entries()) {
       // taking lock on current alb and increment reserved rules
       const { existingRulesReserved } = await updateReservedRules(
         deploymentLogId,
         arn,
         rulesNeeded,
         "increment"
       );

       const httpsListenerRuleLimitExceeded = await isListenerRuleLimitExceeded(
         {
           loadBalancerClient,
           listenerARN: arn,
           rulesNeeded: existingRulesReserved
         }
       );

       console.log({ httpsListenerRuleLimitExceeded });

       if (!httpsListenerRuleLimitExceeded) {
         httpsListenerARN = arn;
         sandboxEnvIndex = index;
         break;
       }

       // no need to reserve rules in current alb if limit is already exceeded
       await updateReservedRules(
         deploymentLogId,
         arn,
         rulesNeeded,
         "decrement"
       );
     }
   }

generateUrl() Function generates the predicted domain name of the service based on the sandbox environment name and available load balancer index.

function updateCourierTrackingConfigDependencyURLs({
 sanitizedEnvironmentName,
 configSourcePath,
 fileName,
 sandboxEnvIndex,
 sandboxResourceMap,
 servicesPresent
}) {
 const projectXBaseUrl = `https://${generateUrl(
   "projectx",
   sanitizedEnvironmentName,
   servicesPresent,
   sandboxResourceMap?.["projectx"]?.["sandboxEnvIndex"] ?? sandboxEnvIndex
 )}`;
 const ltlBaseUrl = `https://${generateUrl(
   "ltl-backend",
   sanitizedEnvironmentName,
   servicesPresent,
   sandboxResourceMap?.["ltl-backend"]?.["sandboxEnvIndex"] ?? sandboxEnvIndex
 )}`;

 const applicationConfig = fs.readFileSync(
   `${configSourcePath}/${fileName}`,
   "utf-8"
 );
 let parsedApplicationConfig = JSON.parse(applicationConfig);
 parsedApplicationConfig["PROJECTX_BASE_URL"] = projectXBaseUrl;
 parsedApplicationConfig["ltl_base_url"] = ltlBaseUrl;

 fs.writeFileSync(
   `${configSourcePath}/${fileName}`,
   JSON.stringify(parsedApplicationConfig),
   "utf-8"
 );
 return JSON.stringify(parsedApplicationConfig, null, 4);
}

Here, we faced another challenge: Since we are checking the availability of rule limits at the start of the script. What will happen in case of concurrent sandbox deployments?

We overcame this challenge by storing the data required by the rules in the database for each load balancer and have taken the lock in the database row. Now, the concurrent sandbox deployments cannot take the lock to the same load balancers simultaneously, thereby avoiding the race condition.

3. Create & Register Task Definition

A Task is a running container and its settings are defined in the Task Definition. This task definition is required to run Docker containers in Amazon ECS.

function getCourierTrackingDefinition({
 repository,
 sanitizedEnvironmentName,
 imageTag
}) {
 return {
   containerDefinitions: [
     {
       name: `courier-tracking-${sanitizedEnvironmentName}-container`,
       image: `${ecrURI}/${repository}:${imageTag}`,
       essential: true,
       logConfiguration: {
         logDriver: "awslogs",
         options: {
           "awslogs-group": "/ecs/demo-courier-tracking-ec2-task",
           "awslogs-region": "us-west-2",
           "awslogs-stream-prefix": "ecs"
         }
       },
       portMappings: [
         {
           hostPort: 0, // port will be assigned when task is fired up
           protocol: "tcp",
           containerPort: repositoryContainerPort[repository]
         }
       ],
       cpu: "256",
       memory: "512"
     }
   ],
   family: `courier-tracking-${sanitizedEnvironmentName}-ec2-task`,
   requiresCompatibilities: ["EC2"]
 };
}

4. Create Target Group

Next, we created target groups from the script:

const createTargetGroup = async ({
 loadBalancerClient,
 repository,
 sanitizedEnvironmentName
}) => {
 return new Promise((resolve, reject) => {
   const params = {
     Name: `tg-${repositoryTargetGroup[repository]}-${sanitizedEnvironmentName}`
       .substring(0, 32)
       .replace(/-\s*$/, ""), // target group can not have more than 32 characters
     Port: repositoryContainerPort[repository],
     Protocol: "HTTP",
     VpcId: VPC,
     HealthCheckPath: repositoryHealthCheckMapping[repository]
   };
   console.log(params);
   loadBalancerClient.createTargetGroup(params, (err, data) => {
     console.log(err, data);
     if (err) {
       reject(err);
     }
     resolve(data.TargetGroups[0].TargetGroupArn);
   });
 });
};

5. Add Listener Rules to Load Balancer

The listener rules are created dynamically from the script, and an example is shown below:

const addHTTPSRuleToListener = async ({
 loadBalancerClient,
 listenerARN,
 priority,
 hostHeader,
 targetGroupARN,
 pathPatterns = []
}) => {
 return new Promise((resolve, reject) => {
   const params = {
     Actions: [
       {
         TargetGroupArn: targetGroupARN,
         Type: "forward"
       }
     ],
     Conditions: [
       {
         Field: "host-header",
         Values: [hostHeader]
       },
       ...pathPatterns
     ],
     ListenerArn: listenerARN,
     Priority: priority
   };
   loadBalancerClient.createRule(params, (err, data) => {
     if (err) {
       reject(err);
     }
     resolve(data?.Rules[0].RuleArn);
   });
 });
};

6. Create & Deploy Service

We use an Amazon ECS service to run and maintain a specified number of instances of a task definition simultaneously in an Amazon ECS cluster.

function getCourierTrackingServiceParams({
 cluster,
 taskDefinition,
 repository,
 sanitizedEnvironmentName,
 targetGroupARN
}) {
 return {
   cluster,
   taskDefinition,
   serviceName: `courier-tracking-${sanitizedEnvironmentName}-service`,
   loadBalancers: [
     {
       targetGroupArn: targetGroupARN,
       containerName: `courier-tracking-${sanitizedEnvironmentName}-container`,
       containerPort: repositoryContainerPort[repository]
     }
   ],
   desiredCount: 1,
   role: "ecsServiceRole"
 };
}

Now that we have created a sandbox, we need to make sure that the entire undertaking stays cost-efficient as well.

On-Demand vs Spot Instances: Cost Considerations

There are two types of instances - on-demand instances (default) and spot instances. The on-demand instances come with no long-term commitment and can be availed anytime you want them. However, this availability comes at a higher price.

For us, daily sandbox deployments sit around 40, of which 10 are completely new deployments. The number of active container instances is 150 and active running branches are 470.

So, on-demand instances amounted to $445.04 per month.

Spot instances, on the other hand, can be availed of via a bidding system. There is a maximum bid price and by paying more than that, you can use the instance if there is free capacity.

Once the free capacity gets exhausted, or the current bid price goes higher than your maximum bid price, your spot instance is terminated.

By using these spot instances, we were able to reduce the monthly billings to $133.72, which meant 70% cost savings.

However, this came with another challenge - no default instance termination warning from Amazon. Whenever a spot bid price exceeds your bid or free capacity gets exhausted and the instance can get terminated even when you are in the middle of deployment.

We addressed this via two-pronged approach:

• Notification before instance termination
• Ensuring instance availability for interruption-free working

1. Notifications

Whenever an Amazon instance terminates, it goes into a Draining state, during which no new tasks can be placed on the instance. Now, we used the following shell script to set these notifications into action:

The command “instance_draining_true” is launched right after getting an instance. Now, as soon as the instance gets in the draining state, the script starts putting the tasks on another EC2 instance to avoid downtime and kicks a buffer period of 2 minutes to ensure no work gets lost.

2. Ensuring Instance Availability

To ensure that we have extra EC2 instances available, we make use of Spot Fleet. A Spot Fleet is a collection of multiple EC2 instances of almost similar configurations that we can choose during the ECS cluster configuration, as shown below:

By doing so, we ensure that EC2 instances are available when one of them goes into a draining state, and the probability of getting the instances of almost similar configuration is also increased.

Further, we have configured a specific threshold value for auto-scaling and auto-downscaling of instances in case the instance capacity utilization increases or decreases.

3. Scaling Testing Operations with Cost Efficiency

In an agile organization like Shipsy, operational scaling, especially in testing comes with numerous critical core considerations, of which robust performance and cost efficiency are of paramount importance. With spot instances, we were able to scale our UAT testing in a smart and reliable manner, all the while reducing the testing costs to 90%.

At Shipsy, we have a highly agile and innovative tech community of developers committed to making logistics and supply chain processes better, sharper, and more efficient with code that gets better every day!

If you wish to be a part of Team Shipsy, please visit our Careers Page.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where team members exchange notes on specific ideas and topics.

This write-up stems from a recent Tech-A-Break session on demo Sandbox, helmed by Viraj Shah and Semal Sherathia.

Hence, test automation!

Automating end-to-end UI testing significantly increases the test coverage rates and facilitates scaling of testing operations by reusing the test scripts created earlier. Automated testing makes test execution faster, and more accurate via efficient and well-maintained test scripts.

However, for test automation, the idea is to look for a reliable and intuitive platform that can be used by both the test engineers and developers for extended benefits. One such platform is Cypress, which allows testing engineers and developers to create web test automation scripts in JS.

Here is a detailed step-by-step tutorial from us, at Shipsy, for front-end test automation with Cypress. The tutorial starts with system requirements, and Cypress installation and also features code snippets from a test demo for a better understanding.

Let us get started with the basics!

Choice of Platform: Why Cypress?

Cypress is an open-source UI automation tool that can be used for integration and end-to-end testing automation. While other testing automation tools like Selenium sit on the compatibility layer (this layer sits between the browser and the Selenium testing framework), Cypress sits right inside the browser and performs all the tasks there.

This is possible because the test runner of Cypress injects the code into the browser and gets the information in and out of it. This, in turn, is possible because Cypress is built on Node.js and uses JavaScript for writing tests.

Further, the Mocha and Chai libraries are built-in and the platform is fast to set up, install and execute.

Finally, the software automatically takes snapshots as the tests run. The user can hover over each command in the command log to see exactly what happened in each step. They can also check the video playback of every test execution for more visibility into testing.

The same goes for Puppeteer. When it comes to quick testing, Puppeteer is great but if you have to test an entire application (which is generally the case), Cypress emerges as a reliable, robust, and resilient platform that offers impeccable performance and results.

The reasons for the huge difference between the performance lies in the fact that Puppeteer is a library, and Cypress is a solid end-to-end testing platform for writing and automating UI tests. Further, the team has done an amazing job with the documentation.

Getting Started: Setting Cypress

As Cypress sits in the browser, it allows much more control over DOM in general, because there is not too much “to-and-fro” among layers or drivers.

Now, one might think that the native side of events might suffer because of this, but Cypress offers repositories for native events.

Next, we share the step-wise process of setting up Cypress.

1. Download NodeJS

Install a version of NodeJS that is not older than NodeJS12.

2. Setting Cypress

It is a good practice to place the files for integration, unit testing, and end-to-end testing in the project folder for which tests are being written.

Now one might ask - “Why?”

As there is no code sharing among the files, Cypress can be kept apart from the main project technically. However, when we are using CI/CD for automatic online deployment, having all the tests in the same repository makes test execution easier and faster.

3. Initializing Cypress Test Directory

We can initialize “npm project” in two ways:

• Using the Yarn package manager
• Using the npm package manager (a more popular option)

For this, we run the following command:

npm init --

This completes the initialization of a package JSON file that manages the tendencies, scripts, and execution of the project that is being initialized via Yarn or npm.

4. Install Cypress

Next, install Cypress and download the Cypress binary:

npm install cypress –save-dev

While Cypress has its own full browser that ships with an Electron-based browser (a basic version of Chromium), any other browser can also be used.

5. Run Cypress Test Runner

Next, run the command:

npx Cypress open

This will open the Cypress test runner that has 5 folders:

• Fixtures
• Integration
• Plugins
• Support
• Video

Once the Cypress launchpad is opened, you can start writing scripts. Scripts can be run in headless mode as well via this command:

npx Cypress run -headless

This mode is required when we are running multiple tests in a CI/CD environment (a display-less environment where GUI is not there).

This is another advantage of using Cypress - headless testing can be automated. Next, we discuss the various folders in the Cypress test runner.

Cypress comes with a comprehensive testing example file. You can check that out before writing your first test.

Now, that’s everything that you need to know to start using Cypress but for a better understanding, we are going to discuss the Cypress framework in detail and explore the same with a detailed test case in the following sections.

Cypress Folders

1. Fixtures

The Fixture folder contains the dummy data that we wish to use in testing. This comes in handy when APIs are too expensive to call or APIs forbid access via the public internet.

In such cases, we can move the data from that particular API into a JSON file in the fixtures folder and conveniently get data for testing.

Now, this brings us to another question - “Why store this JSON file in fixtures only, and not store this outside in any other folder?”

We do this because Cypress offers out-of-the-box support for using these files statically and no manual data import is required for the JSON data folder. Hence, data imports become effortless and easier.

2. Integrations

This folder is extremely important for testing as it contains all the test or spec or specification files. We can create multiple folders in the integrations folder for test file categorization.

These test files contain the test description in the describe method. Every test file should ideally have only one describe, which can have multiple tests in it.

Hence, the describe method can be understood as a suite of tests, and all these tests are individually explained under this method.

3. Plugins

Plugins are used to extend the functionality of Cypress, such as in cases where we need oAuth from browsers, which is a tricky process.

4. Support

This folder allows the user to create reusable code and custom commands. This becomes of crucial importance in the cases of long codes, such as user login. The code in the support folder can be called again and again as and when required.

5. Video

This folder contains the video playbacks of all the test execution. These videos can be played by the user to identify any problem or issue with test runs.

This is important in a CI/CD environment where test logs might not offer an in-depth understanding of the test results.

Next, we share a real-time demonstration of automating testing with Cypress and some results of how this automation can speed up the testing without affecting release quality.

UI Testing Automation with Cypress - Implementation Snippets

The first step is to create a Cypress framework for automating UI testing. This is covered in detail in the next sections.

1. Creating A Page Object Model

Every page has specific DOM elements that are required for automation and are written in one place.

Now, for creating a page object model, we have to create a separate JS file for each web page. These JS files have the object elements of these pages that are used in DOM test cases.

In Cypress, this looks like this:

class page_customer {

    page_user_id() {
        return cy.get("#username")
    }

    page_password() {
        return cy.get("#password")
    } 

    page_login() {
        return cy.get('.submit-button')
    }

The page objects are now visible and accessible from the page object folder, and there is no need to access the codebase every time in case we need to change or access these page objects.

2. Custom Functions

In the next step, we have to create custom functions for specific tasks, such as consignment creation that requires the sender and destination details, etc.

import page_consignment from '../../PageObjects/pageObjects_express/page_consignment'
const page_consignment1 = new page_consignment()
var first_mile_trip
const first_mile_file = 'cypress/fixtures/fixtures_express/fixtures_firstmile.json'



class custom_consignment {

    custom_opencrm() {
        page_consignment1.page_menu_button().click()
        page_consignment1.page_crm_menu().click({force:true})
        page_consignment1.page_crm().click({force:true})
    }

So, each JS file now has corresponding custom functions related to specific tasks, and these functions can be called as and when required separately in multiple test cases.

The data for these custom functions comes from fixtures and environment settings, which we are going to explain in the coming sections. Basically, all the data comes from outside the main codebase which makes testing highly scalable and the codebase more secure.

3. Cucumber Integration (BDD Feature Integration)

Cucumber is one of the Gherkin-based tools which supports and helps in Behavior Driven Development (BDD). This tool offers the capability to write our tests in a syntax similar to English.

Feature File is the entry point to the Cucumber tests of your framework. It is a file where you will write your tests or acceptance criteria in the Descriptive Gherkin language (Like English). A feature file can include one or many scenarios that are in the form of Given-When-Then format.

Feature: CREATION OF DOCUMENT TYPE DOMESTIC CONSIGNMENT AND PICK UP REQUEST FROM CUSTOMER PORTAL.

Feature Description
    Creation "Domestic Consignment" and "Pick up Request" from customer portal.
    Complete pick up to "Pick up schedule" by rider app.


        Scenario: Domestic Consignment should be created after enter all mandatory fields like Source Address,Delivery Address,item type, weight, service type etc
            Given Customer Portal Url,Customer User id,Customer Password ,Submit button of Customer Portal
             When Click on Consignment button
              And Click on the Single Consignment button
              And Please select the invoice number
              And Enter the source address
              And select source address from saves address option
              And Enter the delivery address
              And select delivery address from saves address option
              And select option document type
              And Enter the weight
              And Select the service type
              And Click on Upload details button
             Then Consignment should be created with success message
              And Extract the Consignment Number as variable to use in another cases

        Scenario: After Create Consignment, Its should be displayed in "Search" page with status "Soft Data Upload" after run the scheduler API.
            Given API AUTOMATION-API url, headers of scheduler API
             When API AUTOMATION-hit the scheduler API
              And  Enter the consignment reference number in search text box
              And click on refresh
             Then consignment number should be displayed in search page
              And Status of consignment should be "Soft Data Upload"

Step Definition is a small piece of code with a design pattern attached to it. The cucumber will execute the code when it sees a Gherkin Step mentioned in the feature file.

Given('Consignment creation url, negative Length, width, height', () => {
    api_consignment_url = env_dtdc_data.customer_portal_api_url + resources_consignment1.resources_consignment_create()
    cy.log(" Consignment Creation API URL is : " + api_consignment_url ) 
    pieces = fixtures_customer.Dimensions[1]
    cy.log("Number of pieces is : " + pieces)
    length = fixtures_customer.Dimensions[0]
    cy.log("Length is : " + length)
    width = fixtures_customer.Dimensions[1]
    cy.log("Width is : " + width)
    height = fixtures_customer.Dimensions[1]
    cy.log("Height is : " + height)
    service_type = fixtures_customer.service_type[0]
    cy.log("Service type is : " + service_type)
    customer_code = env_dtdc_data.customer_user_code
    cy.log("Customer Code is : " + customer_code)
    customer_user_id = env_dtdc_data.customer_id
    cy.log("Customer User ID is : " + customer_user_id )
    customer_access_token = env_dtdc_data.consignment_access_token
    cy.log("customer_access_token is : " + customer_access_token) 

})

4. How to integrate Cucumber with Cypress?

Run the following command:

npm install cypress-cucumber-preprocessor

Once these two packages are installed, we call the cucumber-preprocessor next, in the plug-in>>index.js file:

module.exports = (on, config) => {
// `on` is used to hook into various events Cypress emits
// `config` is the resolved Cypress config
}
const cucumber = require('cypress-cucumber-preprocessor').default
module.exports = (on, config) => {
on('file:preprocessor', cucumber())
}

Next, we bind the step definitions by adding the below command in the packages.json file:

"cypress-cucumber-preprocessor": {
"nonGlobalStepDefinitions": true
}

The next set of configuration changes are in the cypress.json file:

{
"testFiles": "**/*.{feature,features}"
}

5. How to Write Cucumber BDD Tests in the Cypress Framework?

Feature file is created with .feature extension under the integration folder.

Let’s create a feature file with a scenario in it.

Create a feature file named “cucumber.feature” :
Feature: Customer Portal login
Feature Description
Scenario: Log in the customer portal
Given Url, user id and password of the customer portal.
When click on login after enter all above details.
Then Customer portal should be opened successfully.

Next, we create another folder under integration with the same name of the feature file and add one js file to write step definitions here:

We need to import {Given, When Then} from cypress-cucumber-preprocessor/steps package :

import {Given, When, Then} from "cypress-cucumber-preprocessor/steps"

In the above example, we have an integration feature file with different projects. There are different feature files for each project as well and these feature files have different test scenarios written in basic English.

6. Step Definitions for Cucumber

The code for these features is written in the step definitions folder that has step.express.js files for each step.

Given('Consignment creation page and required details.', () => {

     customer = Cypress.env("express_customer_code")
     cy.log("customer code is : " + customer)
     custom_consignment1.custom_opencrm()
     custom_crm1.custom_add_consignment()
     destination_name = Cypress.env("express_destination_details_name")
     destination_mobile = Cypress.env("express_destination_details_mobile")
     destination_address = Cypress.env("express_destination_address")
     destination_city = Cypress.env("express_destination_city")
     destination_state = Cypress.env("express_destination_state")
     destination_pincode = Cypress.env("express_destination_pin_code")
     destination_country = Cypress.env("express_destination_country")
     sender_name = Cypress.env('express_origin_details_name')
     sender_phone = Cypress.env('express_origin_details_mobile')
     sender_city = Cypress.env('express_origin_city')
     sender_state = Cypress.env('express_origin_state')
     sender_pincode = Cypress.env('express_sender-pin_code')
     sender_country = Cypress.env('express_origin_country')


})

When('Enter all the values and press submit.', () => {

     custom_crm1.custom_account(customer)
     custom_crm1.custom_destination_details(destination_name, destination_mobile, destination_address, destination_city, destination_state, destination_pincode, destination_country)
     custom_crm1.custom_sender_details(sender_name, sender_phone, sender_city, sender_state, sender_pincode, sender_country)
     custom_crm1.custom_weight(fixture_crm.weight[0])
     custom_crm1.custom_service(fixture_crm.service[0])
     custom_crm1.custom_upload_details()
     cy.wait(10000)

})
Then('Status of consignment should be "Pickup Awaited"', () => {
     custom_consignment1.custom_verify_table_status(fixtures_consignment_page.header_value[0])
})

This way, all the changes are made outside the codebase and the data can be accessed or modified without accessing the main application code.

7. Fixtures

Cypress provides a directory named Fixtures, which stores various Json files. These JSON files can store the test data, Which can be read by multiple tests. We store test data in the form of key values, which we can access in the test scripts.

Take a quick look at the following snippet for a better understanding:

{
    "bag_status": ["Created", "Sealed", "In Transit", "Inscan At Hub", "Debagged"]
}

These values are compared with the values in the step definitions:

Given('Bag number and Destination hub', () => {
    cy.random('BAG').then((number) => {
        bag_number = number
        cy.log("Bag Number is  :" + bag_number)
    })
    destination_hub = Cypress.env('express_destination_hub_code')
    cy.log(" Destination Hub is : " + destination_hub)
})

When('Click on Hub Code, Actions and Create Bag button', () => {
    custom_bag1.custom_actions_btn()
    custom_bag1.custom_create_bag_btn()
    cy.wait(2000)
})

If these values match, the test cases are successfully passed, otherwise, the test cases fail.

API Testing Automation

For API testing automation our Cypress framework has four parts:

1. Headers

All the API headers are defined in this folder and the key values are passed via the step definitions folder, as explained above.

Take a quick look at the screenshot for a better understanding:

2. Payloads

All the API payloads are defined in the form of payload functions in this folder.

Here is a screenshot of the API payload folder:

The code snippet for the highlighted folder is also shared below for a better understanding.

class payloads_rider {

    payloads_rider_login(username, password) {
        var payloads_rider_login =
        {
            "username": username,
            "password": password
        }
        return payloads_rider_login
    }
}
export default payloads_rider;

3. Resources

All the resources attached to the API base URLs are defined in this class.

Here is a screenshot of the Resources folder from the Cypress framework:

The code snippet is as follows:

class resources_rider {

    resources_rider_login(){
        return '/api/RiderApp/login'
    }

    resources_consignment_for_prs(){
        return '/api/RiderApp/consignmentsForPRS?worker_id=' 
    }

    resources_prepare_prs(){
        return '/api/RiderApp/preparePRS'
    }

    resources_arrived_location(){
        return '/api/RiderApp/arrivedAtLocationForPickup'
    }

    resources_complete_pickup(){
        return '/api/RiderApp/updatePickupTaskStatus'
    }

}

export default resources_rider

4. Custom-API Functions

In the custom API folder, all the functions on headers, payloads, resources, etc are written and executed.

This is how the folder looks like:

The code snippet for the specific folder is also shared below:

class custom_api_fn_rider {


    api_rider_login(url, username, password) {
        cy.request({
            method: 'POST',
            form: true,
            url: url,
            body: payloads_rider1.payloads_rider_login(username, password),
            headers: headers_rider1.headers_rider_login()
        }).its('body').then((response) => {
            response_login = response
            authToken = response_login.data.access_token.id
            worker_id = response_login.data.worker.id
            cy.log("token is:" + authToken)
            cy.log("worker_id is : " + worker_id)
            cy.log(response_login)
        })
    }

The rest of the process resembles the ones discussed for UI testing automation.

A sample step definition call for API testing automation is shown below:

Given('API Automation - URL, UserID and Password of Rider App',  () => {
    api_login_url = env_dtdc_data .api_rider_url + resources_rider1.resources_rider_login()
    api_rider_username = env_dtdc_data.api_rider_username
    api_rider_password = env_dtdc_data .api_rider_password
})

When('API Automation -Enter User ID, password and press Submit',  () => {
     api_rider1.api_rider_login(api_login_url, api_rider_username, api_rider_password)
})

When('API Automation -write the auth token from api response as json data',  () => {
     api_rider1.api_rider_login_data_generate()
})

Next, we discuss some other components of the Cypress framework.

1. Environment Settings

We have different types of environments, such as Dev environment, Demo environment, Production environment, etc.

Now, we did the environment settings such that the environment or script data for all these environments are written outside the main codebase so that we don't have to make any changes in the existing codebase in case of future environment data updates.

For this, we have used a separate config file that has multiple JSON files for each environment. The test scripts for each environment get the data from these JSON files for every specific command.

2. Common Functions in Command

The Support folder in the Cypress framework has a command.js file that has all the common functions that can be called anytime and anywhere as per requirements via the step definitions file.

Take a quick look at the screenshot that highlights the folder and file:

The code snippet for this specific file is shared below:

Cypress.Commands.add("verify_table_status", (selector1,selector2,header_name,header_value) => {
    cy.get(selector1).each(($id, index, $list) => {
        if ($id.text() === header_name) {
            cy.log($id.text())
            cy.get(selector2).eq(index).then(function ($status) {
               const status = $status.text()
               cy.log("header_value is :" +status)
               expect(status).equal(header_value)
           })
        }
        })
})

3. Reports

Another interesting feature of our UI testing automation framework is the reporting. These reports are generated for test scripts that we run. All these reports are extremely intuitive and offer actionable insights in a user-friendly manner because of our BDT framework in testing automation.

Here are a few snapshots of the reports for a better understanding:

These reports show the number of test cases that are passed and failed. It also shows the time taken for a test case to get executed.

So, this is how UI testing automation can be done with Cypress.

Now, give this a try, and let’s get in touch in the comments section to share the experience!

At Shipsy, we have a highly agile and innovative tech community of developers committed to making logistics and supply chain processes better, sharper, and more efficient with code that gets better every day!

If you wish to be a part of Team Shipsy, please visit our Careers Page.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where team members exchange notes on specific ideas and topics.

This write-up stems from a recent Tech-A-Break session on front-end UI test automation, helmed by Swatantra Srivastava.

Hence, redundancies, in any form and in any business vertical, can come with huge repercussions.

However, when we are operating at scale, redundancies have the tendency to not only creep in but also evolve gradually over time.

One such redundancy that we encountered was consignment label generation. Every customer had different label design specifications, which is why every label required individual creation and ultimately individual coding.

For example, every field and information present on this consignment label is positioned and rendered via code:

Source: Shipsy

This meant that a lot of code was redundant and repetitive. The process lacked resource efficiency and consumed a lot of time and effort as well.

Here is how we overcame this redundancy by making the entire process code-free.

Problem Statement - Redundant and Inefficient Label Generation Process

Previously, the label generation process included the following 5 steps:

Source: Shipsy

Previously, every label generation began with a ticket generation process, followed by coding as per the client provided specifications. Next, the label was tested by actually printing on paper to ensure that all the content is appearing the correct way.

Finally, the label entered the UAT (User Acceptance Testing).

Hence, the process was time-consuming, tedious, and involved a lot of repetitive coding.

Our Objective

We wanted to make our label generation entirely code-free, and create a dashboard for label generation so that:

• Anyone, including our clients, can generate labels directly from the dashboard in an entirely code-free manner
• The previously generated labels can be stored for future use with minimum changes
• The label generation process becomes more time and resource-efficient
• There is no need for QA, UAT, and actual print-testing of the labels

Here is the roadmap for our endeavor:

Source: Shipsy

Next, we share a step-wise walkthrough of the process that helped us make our label generation code-free, resource-efficient, and redundancy-free.

Solution: Code-Free Label Generation

Step 1 - Creating the Metadata to Generate Label

As a label is a grid with an array of rows, the metadata to create a label must have the following:

• Page properties - page size and page arrangement
• Components - rows, cells, text, image, barcode

A snapshot of basic metadata is shared below:

{
 "padding": "0px 0px 0px 0px",
 "orientation": "portrait",
 "dimension_code": "A6",
 "label_arrangement_code": "1x1",
 "label_vertical_spacing": 0,
 "label_horizontal_spacing": 0,
 "rows_metadata": [
   {
     "cells": [
       {
         "type": "content",
         "style": {
           "width": "100%",
           "padding": "0px 0px 0px 0px"
         },
         "content": [
           {
             "type": "text",
             "field": "service_type_id",
             "style": {
               "fontSize": "10"
             },
             "contentType": "dynamic_field_code",
             "dynamic_field_code": "service_type_id"
           }
         ],
         "widthType": "%",
         "contentStyle": {
           "justifyContent": "center"
         }
       }
     ],
     "style": {
       "height": 12
     }
   },
   {
     "cells": [
       {
         "type": "content",
         "style": {
           "width": "100%",
           "padding": "0px 10px 0px 10px"
         },
         "content": [
           {
             "type": "barcode",
             "field": "reference_number",
             "contentType": "static_value",
             "static_value": "reference_number"
           }
         ],
         "widthType": "%",
         "contentStyle": {
           "justifyContent": "center"
         }
       }
     ],
     "style": {
       "height": 65,
       "borderTop": false
     }
   }
 ]
}

Some content, such as company image, logo, barcode, etc. is fetched dynamically from the internal server, while the static content, such as shipment details, address, etc can be filled manually as well, as shown below:

Source: Shipsy

Step 2: Making UI From Metadata

We used the React-PDF library to render the primitive React components in a PDF.

Hence, the components can be returned as a Doc file, a blog, a series of PDFs, etc.

We wrote our own components on top of this React-PDF library, which can be iterated over our metadata to generate labels in a code-free manner.

This looks like regular React components and has properties that contain consignment data and metadata.

Step 3: Handling Barcodes

We were already using a Lambda function for barcodes that we have used here as well.

As the barcode is a dynamic consignment property, its generation process cannot be hard-coded. Hence, we have used a Unique Identifier (UUID) map that combines consignment data and metadata.

This way, the barcodes that are rendered from the consignment data are attached to the label at the time of final label rendering.

As the PDF rendering is a synchronous process and barcode generation from the Lambda function is asynchronous, it is important to get the barcode before rendering the PDF via React-PDF.

Step 4: Bringing Metadata to UI

We use form functionality to create a label where everything ranging from page size to padding, and static to dynamic label contents are generated without coding.

The dynamic preview of the label being made is also shown to show the liver rendering of the recent changes or actions, as shown in the following image:

Source: Shipsy

Further, the default consignment metadata is available on the sidebar to allow the developers easy access to the code as and when required.

This way, the dynamic content can be easily copy-pasted from the metadata to the form elements, and the label generation becomes easier.

While this process solved the code-free nature of the label generation process, two challenges were still there:

• It was an infinitely going-on form
• As form rendering is a resource-intensive process, re-rendering a long-form could easily render the page unresponsive

These challenges were resolved in the next step.

Step 5: Optimizing the Form Performance

We optimized form performance by breaking down the form components into different parts and made pure functions for these components.

Thus, the value of the component now remains the same unless the properties are changed. This means that unless the properties of a form component are changed, the values are returned from the cache by React

Memo and the form components are not re-rendered.

Hence, there are no performance issues as well.

Step 6: Printing the Label From Dashboard

Finally, once the label is ready, it can be saved and published in the dashboard. The print command can be given from the dashboard and any user can easily generate the labels without having to code.

The PDF of the label is generated on the server side and sent to the client as a blog. The client can view and print the label as and when required.

To prevent different people from editing a label concurrently, we have a uniqueness check for versioning.

The versions are stored in the history and can be used to override the changes.

An overall walkthrough of the entire process is shown in the following image:

Source: Shipsy

Results: Benefits We Gained via Code-Free Label Generation

Arresting such redundancies can optimize the processes and spur a number of benefits. Some of the benefits we unlocked via this endeavor include:

1. Speedy Label Generation

As the process no longer involves redundant and repetitive coding, the label generation has become faster, easier, and hassle-free.

Previously, it took 2 days to generate a single label. Using code-free label generation has reduced the label generation time to 2 hours!

2. Faster Onboarding of Customers

Fast and efficient label generation has reduced the operations kick-start time by 1.5 days.

The customers can get started with the label generation process without any specific learning involved. The dashboard is extremely intuitive and the UI components are self-explanatory with captions being shown with a hovering cursor movement.

3. Save Drafts for Quicker Updates

The multiple drafts generated by a user can be saved for future use and updates. This reduces the overall time and effort spent in generating labels.

Shipsy is a community of agile developers consistently working towards the improvement of our products, and underlying tech to ensure performance-intensive business deliverables.

We hope this write-up energizes similar efforts across the developer community.

To become a part of our developer community, please visit the Careers Page.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where team members exchange notes on specific ideas and topics. This write-up stems from a recent Tech-A-Break session on code-free label generation, helmed by Shivangi Singla and Sumit Gupta.

While an app might be fairly stable initially, constant updates, data overload, and sudden scaling bring a slew of changes that derail its stability.

Here, we discuss various tips for mobile app developers to create scalable and stable apps. We also share the efforts we invested in one of our apps to make it 99% stable and highly scalable.

Developer Tip #1 - Identify and Define Key Events to Track and Record Them Separately

Diversify the analytics by tracking and recording all the key events, such as all types of conversion events, like:

• App browsing
• Wishlist tracking
• Check out
• Cart abandonment
• Visitor activity, etc

Create different events for different steps in the customer journey, such as conversion, and track them.

This way the upper management can get highly granular business intelligence in the form of actionable insights, such as:

• Increase or decrease in conversions after a new feature release
• Conversion trends for different campaigns
• Sales and impressions generated for the similar product with different imagery or promotional campaigns

Takeaway:

Creating different events for all the crucial steps in the customer journey facilitates event tracking and app monitoring at a granular level. It makes issue tagging easier and faster.

Developer Tip #2 - Proactive Root Cause Analysis (RCA)

We started working on the stability and scalability of one of our mobile apps a few years back, and a few of our priorities were:

• Proactive event tracking and issue resolution
• Constant on-the-move monitoring
• Repeating the cycle for a glitch-free UI/UX

And, our list of challenges included the following:

• Gathering information about events that led to issues, such as crashes, missed orders, or alerts, from the end-users
• Making our mobile app more stable and knowing runtime crashes on production
• Hitting a large number of APIs via a Pull-based mechanism

Now, these three challenges spawned the following three issues:

• Inability to locate and identify the root cause of the issue - a wrong entry, any existing bug, process fault, etc.
• Inability to track and monitor the app stability in runtime from a developer’s perspective
• A massive number of API calls persisted irrespective of the efficiency of the query

Now, take a look at the following image for a basic overview of the implications these issues caused:

Source: Shipsy

So, what did we do?

We had a two-pronged approach with Firebase here - Analytics and Crashlytics.

Let us explore them one by one.

Analytics - What, How, and Why?

We created an event for every user action and recorded every action, such as:

• Button clicks
• Screen navigation
• API calls and status
• Functional events

The entire process is shown below:

Source: Shipsy

Next, we gathered the event data (analytics data) for an in-depth analysis. This data store recorded events (past events and intra-day events) in a date-wise manner.

Finally, we did a thorough analysis and reported on these data sets to generate actionable insights into the overall user activity and app performance. We have also created multiple dashboards for the analysis purpose to know the status of core functionalities.

Gathering such analytics allowed us to tap into the granular user activities and experiences, such as:

• User behavior analysis, such as average time spent on a specific tab or page
• Analyze the features or updates that increased crashes or app issues
• Track and monitor app user journey to figure out the most-used app features
• Optimize and improve the app UI by reprioritizing the app screen order

So, we leveraged the following 4-step process to improve the UI via analytics:

Source: Shipsy

Crashlytics: Proactive tracking, monitoring, and resolution of issues

A few years back one of our worst-case scenarios looked like this:

• 5% of 6800 order numbers were lost
• We were getting 35000 API calls per minute!
• Every end-user was looking for updates and new orders via a “PULL” mechanism, causing more API hits

To overcome these challenges, we ensured that every time our mobile app crashed or threw an exception, the stack trace was thrown with the exception.

So, our crash reports now included:

• Crash versions
• Names
• Keys
• Logs
• Event data

This way, we no longer required the app users to report the exact sequence of events that led to the crash or any exception.

Also, every crash monitoring was followed by a crash report and a crash fix, and the process was repeated proactively.

We started “pushing down” the latest information about events as alerts and notifications.

This helped us significantly reduce the number of API calls and helped us scale in an efficient and sustainable way.

This proactive RCA and in-depth event analytics increase our app stability to 99% from 68%. It also empowered us with insights that helped us resolve any type of issues in our mobile app even before the client could notice them.

Takeaway:

Proactive Root Cause Analysis can be of real help when it comes to building highly scalable and stable mobile apps. Using actionable insights from the event records can improve the overall app usability and performance.

Let Your App Tell You What Is Wrong

While the technical aptitude of every app user is different, generally, their perspective is way different from a developer.

For example, the app user would say - “I pressed the New Order button and the app didn’t work properly. It did nothing.”

On the other hand, a developer is looking for something like - “I was in the middle of updating a delivery record when I got the New Order message. I tapped on it and the app didn't do anything. I was not able to record the delivery and had to relaunch the app.”

Situations like these can be endless.

Therefore, it is important that every crash event detail is fetched from the most trustworthy source - your app.

Developer Tip #3 - Track, Monitor, Record, and Analyze Data

Following a consistent and robust app data recording practice pays off in various ways. You always, always have the right event data for debugging, app improvements, and issue resolution.

This makes it easier for the developers to locate and identify the exact cause of the crash event and resolve it properly.

Takeaway:

Making your mobile apps “tell you” what went wrong allows you to make them more stable and resilient.

Bridging the Gap Between Support and Production

Earlier our dashboard system for our Support Team and Production Team was disparate.

However, this led to the disjoint information collection and redundant event data collection.

This is because every support team member would use a different phrase to record the crash information. This burdened the production team to make individual calls to the end-users and gather the information.

We overcame this challenge by bridging the gap between our Support and Production teams.

Now, every event has an event ID, that can be tracked, monitored, and referenced in the future as well.

Developer Tip #4 - Reduce the Time Spent in Gathering App Event Data

By doing so you can:

• Reduce the overall time spent in gathering the event data
• Skip the agony of processing average analysis done by support staff
• Track the event
• Record and monitor it for future references

Takeaway:

Reduce the number of steps for event data gathering and standardize the event reporting, monitoring, and tracking process. This makes debugging process more efficient and less redundant.

App Performance Monitoring: An Ongoing Process

Creating a stable, robust, and scalable mobile app is a daunting task that requires consistent efforts. This is because the scope, functionalities, and utility of an enterprise mobile app vary over time as more people and different user categories evolve.

We, at Shipsy, believe in the consistent improvement of our products, codebase, and underlying tech to ensure that our products stay relevant, high-performing, and razor-sharp.

To become a part of our developer community, please visit the Careers Page.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where team members exchange notes on specific ideas and topics. This write-up stems from a recent Tech-A-Break session on Mobile App stability and scalability, helmed by Pankaj Yadav.

Technical Contributions: Sahil Arora and Kalpesh Kundanani.

He wakes up sharp at 3 am daily, to plan delivery routes for 50000 consignments from his warehouse. With a team of 60 riders and simple geo-coding software, he is able to complete the job by 6:30 am.

Even after diligent planning, he is unable to plan efficient trips that save money, time, and fuel. He is unable to find the most cost and time-efficient routes or vehicles for the largest savings.

So, he is planning to wake up at 2 am tomorrow morning. But, he is still unsure whether he will be able to save more money than yesterday, or not.

Route planning in logistics can be challenging for large enterprises. This is because constraints make it hard to optimize the transit of millions of orders per day.

Now, these constraints can be anything:

• Number of deliveries every vehicle is allowed to make
• Number of vehicles serving a specific area
• Cost of vehicles, fuel, and fulfillment
• Time or any other SLA

Optimizing routes is a challenging constraint programming problem. It involves analyzing and optimizing specific business use cases at multiple levels.

Some businesses might focus on quick deliveries, while others might prefer vehicle optimization.

This means unlocking economies at scale requires much more than a simple geo-coding engine or TSP.

Scaling your route planning software involves two things:

• Solving business-specific constraints at scale
• Generating intuitive and optimized trips even when the constraints increase

So, as we expanded, we were routing millions of consignments per day, and the standard “one-size-fits-all” approach crumbled down.

We required a DIY Smart Route Planning Optimizer, and here is a walkthrough of how we built one.

What makes this entire endeavor more rewarding is the fact that this DIY worked for both - the developers and the clients. Both the stakeholders can customize and configure the routing software by Shipsy.

They can generate optimized routes by choosing the set of trip constraints from a given list.

So, the routing software allows Sam, the warehouse manager, and all his friends in the industry to generate trips with the greatest profits.

Ultimately, this means that he and his friends can now enjoy a peaceful sleep.

Building a smart route optimizer for multiple constraints

We aimed at building a smart, efficient, and scalable route optimizer that could:

• Distribute consignment (orders) among riders and take care of all the constraints
• Optimize the route (Cost)
• Suggest the best non-overlapping routes (quality and efficiency by plying only one vehicle to a specific area)
• Doesn’t require developer involvement for configuration every time (We have to make it easier for Sam, remember?)

This optimizer would help us in:

• Asset allocation
• Creating route plans, loading sequences, delivery ETAs
• Market vehicle requirements

It would consider the existing resources to suggest a relevant optimization strategy. It would consider the asset configuration, cost function, and consignment constraints.

This would help us deliver or transport consignments from a hub to desired locations (delivery location or another hub) while:

• Optimizing the use of existing resources
• Avoiding breaching any vehicle or consignment constraints

Add operational costs and distance traveled and we had a Pandora’s Box gawking at us!

At first glance, this might seem like a simple K-means or Travelling Salesman problem.

But, here is the catch!

To extract the global optimum, the only possible way would be to generate all the arrangements of trips possible. Only those arrangements which satisfy all arrangements should then be filtered in.

Finally, we should pick the most optimum of the filtered.

Since we’re trying every permutation of the trip, the time complexity of this would be of O(n!).

To put things into perspective, consider the following scenario:

Consider we have three letters {A, B, and C}.

How many permutations of it are possible?

We can start by fixing A, then choosing between {B, C}. This can be done in two ways: {A, B, C} or {A, C, B}. The same can be extended to B and C.

Wherein the results would be: {A, B, C}, {A, C, B}, {B, A, C}, {B, C, A}, {C, A, B}, {C, B, A}.

Take a look at the following image for a visual idea:

Source

Thus, the number of permutations => 6 = 3! We have established that the time complexity for global optimum is n!.

The growth rate of n! is worse than exponential:

Source

We can see n! is a “terrible” time complexity. Thus we needed ways to optimize this process.

So, we started with the strategies we had and began a smart DIY for Shipsy’s Smart Route Optimizer.

What did we do

We had different routing algorithms that fit in different use cases

• Balanced K-Means and Concorde K means algorithm helps distribute the consignments among the workers. Concorde provides the optimal path within the cluster.
• Constraint programming solver
• Shipsy's Routing Algorithm

As we onboarded more clients, the nature of consignments changed, adding more constraints:

• Consignments’ weight, volume, height, etc., needed to be considered in the planning
• Fuel Type - Certain areas in India especially in the NCR region have constraints on the type of fuel you can use. For example, in the national capital, only CNG vehicles can serve particular pin codes.
• Delivery, Pickup, and Pickup Delivery in different time windows
• Area Partitioning
• Vehicle Priority (Self-owned vehicles should get priority)
• Order Priority (Certain high-value orders need to be prioritized)
• Soft constraints, such as overlapping of delivery routes, clustering, and vehicle use

Hence, we needed something better than K-means.

After all, Sam’s friend Ray might be looking for a way to create profitable and intuitive trips with a specific set of vehicles or riders. This is the whole idea behind DIY software.

It assumes the configuration that a specific user finds “the best or relevant”.

So, we opted for solving constraint programming using Google OR-tools.

Using Google OR-Tools for Linear Programming

The basic idea was to define "what a particular solution should look like", instead of defining the exact solution.

We converted constraints into equations of the Linear Optimization problem. Then we solved those equations keeping the constraints in mind.

An example of a Linear Optimization problem is shown below:

Source

In our case, the constraints were:

• Consignment constraints: Weight, volume, time, nature, etc.
• Resource: Fixed cost, vehicle shift, vehicle location, weight capacity, volume capacity, etc.
• Cost Function, Speed factor, etc.

(Before we proceed further, it is important to mention that this list of constraints is ever-expanding. This is because as we scaled and onboarded more clients, the problems and criteria for determining the “profitability and optimization” of the trips changed vastly.

Currently, we are offering three different types of routing algorithm options. Each one of them has 30 to 40 constraints.)

Now, to suggest a solution, we were:

• Defining the properties of the solution (optimized routes)
• Not defining the steps (which vehicles for which route, etc) to come to a solution

For constraint programming, we used Google OR-Tools Routing Solver. It is a fast, memory-efficient, and numerically stable solution.

For example, its solution for the problem shown above looks like this:

Source

So, using the Routing Solver by Google, we solved the vehicle routing optimization. Now, we could find the best routes for a fleet of vehicles visiting a set of locations.

Usually, "best" means routes with the least total distance or cost.

Look at the following example where “0” denotes hub and other numbers as nodes for vehicles to visit:

Source

When we used Google OR-tools without constraints, the trip looked something like that:

Source

Okay, so we had amazingly intuitive trips with a single constraint.

But this is not the case in the real world, right?

Because, remember Sam’s friend Ray, his manager has been looking for ways to cut down the operational costs.

So, here comes another set of constraints, such as vehicle capacity.

Now, when we added even one more constraint (resources, consignments, and cost functions), the trip became:

• Non-intuitive
• Complex

So, with constraints, the Routing Solver presented the following trip:

Source

The trip shown above became even worse as we kept on adding constraints. The routes were overlapping, and the trips were no longer intuitive.

So, even though the trips were optimal, they were extremely complex and non-intuitive.

They looked something like this:

Source

Now, not every customer applies all the constraints on every delivery or transit. So, we needed our trips to be intuitive as well as optimal.

Thus, we created Shipsy’s Clustering Algorithm from scratch.

Shipsy’s Clustering Algorithm

Shipsy’s Clustering Algorithm is easy to use and fast. It helps us create intuitive trips with simple constraints.

It first segregates customers into clusters based on the partition they belong to.

Usually, partition_id is set by users to restrict vehicles serving multiple locations and minimize overlaps.

This is followed by collecting all the feasible nodes greedily. The greedy aspect denotes choosing the closest feasible consignment.

Finally, a TSP algorithm is applied to each cluster to get an optimal route per cluster.

So, the trips that initially looked something like this:

Source

Were now extremely intuitive and looked like this:

Source

While we solved the “intuitiveness” challenge, the product required configuration for every client.

This means that every time Sam or Ray or any other person required a change or started using the software, they had to sit with the developer for backend configuration.

This is because every optimization strategy had different optimization parameters as per:

• Business requirements
• Use cases

Now, this doesn’t look like a very good DIY; does it?

Thus began our journey to create an extremely scalable and configurable routing software that would:

• Assume the configuration as per a specific business
• Scale efficiently
• Require minimum to zero developer involvement for backend configuration
• Allow change at any particular period of time
• Come with a negligible learning curve
• Suggest highly optimized and intuitive trips every time (irrespective of the type and number of constraints)

Let us have a quick walkthrough in the next section.

Shipsy’s DIY Routing Playground

Shipsy boasts of a plethora of cutting-edge algorithms for vehicle routing problems. We wanted our clients to get a “feel” of how each algorithm fares in a real-world scenario.

Enter: Routing Playground.

It is one of our hallmark products, and allows users to set up dummy customers, and vehicles, and install their required constraints.

The end user can configure the software and try numerous constraints for creating their version of “the best” trips.

So, they can “play around” with the wide range of options we offer, which makes the name “Routing Playground” apt.

The user can choose any of the routing algorithms they want. The software would generate an optimized routing path within moments.

So, the trips were now optimized and intuitive, as shown below:

Source

They can save the most satisfactory configuration as the default backend engine. This engine keeps on suggesting optimized routes effortlessly and can be configured also.

Also, we were left with another problem - Area Partitioning. This would ensure efficient optimization as no two vehicles served the same area.

Solving area partitioning

It is often the case that the user wants vehicles to serve in select locations only.

For instance: A vehicle serving in the Noida region should not go to Delhi, and vice-versa.

It helped us in two ways:

• Quality of trip: Reduced overlap between vehicle trips.
• Vehicle region restriction: Restricting a vehicle to serve a specific region.

Our intuition here is to assign a “partition_id” to each vehicle and consignment.

Now, only the matching ids may be used to form a trip. We allow users to manually define a boundary in the map itself.

Thus, consignments that fall under that region would be assigned that partition_id.

Take a look at the following screenshot for a better understanding:

Source

Results: Benefits We Unlocked With Our DIY Route Optimizations

1. DIY Routing for Every Stakeholder

We started with Sam, who aimed at creating the most profitable trips. According to Sam, the trips that help him save the most money are the best ones.

However, the logistics and supply chain industry has a lot of Sams, Rays and stakeholders.

So, the definition of “optimized or best” trips varies from person to person.

Creating a DIY routing software allowed our solution to be as versatile as all our customers.

They no longer have to rely on the developers for small configuration changes.

Likewise, at the organizational level, we are able to use the DIY nature of the software for our requirements.

So, Shipsy’s Routing Playground is a DIY-hit with all the stakeholders.

2. Ease of Use and Speed of Processing

Google’s Routing Solver is complex to use and comes with a learning curve. Also, we have to define constraints and create equations for each one of them.

Shipsy’s clustering algorithm offers quick planning and creates intuitive-looking trips. It is easy to use

When we used Google’s Routing Solver, the trip planning for 1000 consignments took 10 to 15 minutes. Shipsy’s clustering algorithm can plan trips for 20, 000 to 30, 000 consignments in a few minutes.

3. OSRM for More Realistic Distance Function

Our routing optimizer uses OSRM (Open Source Routing Machine). So, every trip suggestion examines the geography between two points, such as dead ends, etc.

The trips appear as polylines on OSM (Open Source Maps) and are highly precise.

They also consider the real-world road conditions for smart decisions.

4. Cost Efficiency

Using OSM helped us reduce our dependence on Google Maps which comes with subscription fees. Also, OSRM offers blazing-fast speed because of its C++ backend.

5. Versatile Strategizing

Shipsy’s clustering algorithm offers a large number of options. For example, it offers 100+ consignment parameters and constraints for route planning.

So, strategizing can be as versatile as a client wants. For example, they can opt for Geo-fence partitioning, to map a rider to a specific geo-fence partition for zonal consignments.

At Shipsy, we aim to keep our products, operations, and performance razor-sharp. This ensures that our products scale well and stay relevant to the evolving client needs.

To be a part of our developer community, please visit our Careers Page.

Acknowledgments and Contributions

As an effort towards learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy. In these sessions, our team members exchange notes on ongoing innovation and optimizations.

This write-up stems from a recent Tech-A-Break session on Routing Playground.

Contributions: Sahil Arora, Aman Ruhela, Rajat Kumar, Krishna Yadav, and Nanubala Gnana Sai.

Being an agile organization with an intense focus on innovation entails designing and creating future-proof technological solutions that scale, evolve, and stay relevant.

However, delivering across such expectations requires an impeccably robust codebase, which is readable, maintainable, and intuitive for years down the lane.

We aimed at creating a codebase that can serve as a reference for the new developers and “explains itself” even when the original developer is not around. This is also called future-proofing, and here is how we energized the efforts at Shipsy.

Problem Statement: Can Software Designing Be Future-Proof?

Future-proofing has many different faces and definitions based on the business use cases, such as:

• Preserving code readability and maintainability even after the original developer has left the organization
• Ensuring that code is not clunky for future usage, extensions, or upgrades
• Developing a system design that is effortless relevant for every stakeholder

In our pursuit, we zeroed down on the fundamentals - problem decomposition, as outlined by the industry stalwart John Ousterhout.

Any computer software is one big problem decomposition challenge - the number of modules, functionalities of these modules, documentation, dependencies, and the overall complexity of the functional system.

As the clients suggest changes or ask for more features, there is hardly the time to play by the rules. So, code refactoring or best practices tend to take the back seat, especially in startups.

Then, how can we make our code future-proof?

Solution: Reduce System Complexity

System complexities affect developer productivity in many ways, even if it is not apparent from the very beginning. Understanding the working of a piece of code, lots of efforts for implementing small changes, and localizing all the points where a single change reflects - are some symptoms of complex systems.

As the software complexity increases, it becomes more vulnerable to bugs and delays in development.

Software complexities are of three types:

• Change Amplification - Any simple change requires changes in many places, as shown below:

Bad Example:

// file1.js
if (direction === 'UP') {
 // ....
}

// file2.js
if (direction === 'UP') {
 // ....
}
.....

Good Example:

enum Direction {
 UP = ‘UP’,
 DOWN = ‘DOWN’,
 LEFT = ‘LEFT’,
 RIGHT = ‘RIGHT’
}
// file1.js
if (direction === Direction.UP) {
 // ....
}

// file2.js
if (direction === Direction.UP) {
 // ....
}

• Cognitive Load - Developers need to carry a lot of information to complete the task. This increases the chances that they might miss something leading to bugs and delays in development.

As shown in the above example, the shared enum variable holds the direction and each page references that variable.

• Unknown Unknowns - There's important information you need to know before making a change, but it is not obvious where to find it or even if it is needed.

As shown in the following example, the shared enum variable has the “string” type. However, few files use the “number” type.

enum Direction {
 UP = 'UP',
 DOWN = 'DOWN',
 LEFT = 'LEFT',
 RIGHT = 'RIGHT'
}
// file1.js
if (direction === Direction.UP) {
 // ....
}

// file2.js
if (direction === Direction.UP) {
 // ....
}

// file3.js
// direction holds numbers instead of string
// for e.g up -> 1, down -> -1 left -> -1, right -> 1
if (direction === Direction.UP) {
 //
}

Unknown unknowns are the most critical type of complexity, as in this case, you don’t even know that there is an underlying vulnerability or risk in your code.

Generally, in agile organizations, such as startups, software development is tactical, meaning that during development, the main focus is on faster deliveries and accomplishing the intended functionality via shortcuts. As there is no specific focus on long-term goals, there is generally no planning (strategic development) for code refactoring.

Ideally, software development must be strategic, keeping the long-term goals, such as maintainability, in mind. However, the more tactical a developer becomes, the more time they take in developing software, as shown in the following graph:

Source

Hence, we started to look beyond the “working code” and approached code refactoring strategically, such as specific projects that are well matured. This helped us balance the strategic and tactical development goals and steered us towards effortless yet agile system development.

Here are three things that help us reduce system complexities consistently.

1. Modular Design

Addressing complexities, one at a time.

We create small and independent modules that reduce complexity by ridding dependencies.

However, there is a catch - independent doesn’t mean more modules. We implement independence in our modular design by ensuring that the implementation details in the service class of one module are not visible to another. Also, we use encapsulation so that the service class shows fewer implementation details for layers of abstraction.

Below, we share key considerations for concise and strategic modular design:

• Use default class for common behavior
• Avoid shallow modules as they increase the number of modules, which yet again adds to the overall complexity, as invoking any one of them is not easy.

Further, the shallow modules tend to be complex because they include functionalities from other modules as well.

Take a look at the following examples for a better understanding.

Bad Example:

export abstract class Inquiry {
 abstract createInquiry(organisationId: string, params: CreateInquiryDto);
 abstract sendInquiry(organisationId: string, params: SendInquiryDto);
 abstract searchInquiry(organisationId: string, params: SearchInquiryDto);
 abstract searchByReferenceNumber(organisationId: string, params: SearchInquiryDto);
 abstract updateDeadline(organisationId: string, params: UpdateInquiryDeadlineDto);
 abstract getInquiryDetailsForShipper(organisationId: string, params: FetchInquiryDetailsDto);
 abstract getInquiryDetailsForFF(organisationId: string, params: FetchInquiryDetailsDto);
 abstract fetchInquiry(organisationId: string, params: FetchInquiryDetailsDto);
 abstract updateInquiry(organisationId: string, params: UpdateInquiryDto);
}

Deep modules work the best for light and clean interfaces, as most of the information is hidden, even if there is a lot of functionality in a method.

Good Example

export abstract class Inquiry {
 abstract create(organisationId: string, params: CreateInquiryDto);
 abstract send(organisationId: string, params: SendInquiryDto);
 abstract search(organisationId: string, params: SearchInquiryDto);
 abstract update(organisationId: string, params: UpdateInquiryDto);
 abstract fetch(organisationId: string, params: FetchInquiryDetailsDto);
 abstract delete(organisationId: string, params: DeleteInquiryDto);
}

1. Code Documentation

Code documentation or commenting is essential to make the code more understandable and readable for future references and correlations.

While good commenting can overcome the unknown unknowns and cognitive load challenges, over-commented code makes things complex.

Below, we share some key pointers to keep in mind for code documentation.

Good comments:

• Legal comments
• TODO comments
• Explain the intent of the coder regarding some important implementation, as shown in the following screenshots

/**
* @summary dump inquiry and bid details to rate_master when bid is sent for an inquiry
* @description
* 1. find port and carrier details to set db internal identifiers
* 2. separate charges with and without container type, size from bid charge details and
*    prepare them into rate_master charge format
* 3. check if revised bid is sent
* 4. for each Inquiry container type,size insert/update rate master object
* @param {string} organisationId [Organization identifier]
* @param {Users} user [user details]
* @param {Inquiry} inquiry [inquiry details]
* @param {Bids} bid [bid details]
* @param {OptionsType} options [extra properties]
*/
function addInquiryBidInRateMaster(
 organisationId: string,
 user: Users,
 inquiry: Inquiry,
 bid: Bids,
 options: OptionsType = {}
) {
}

Bad comments:

• They are noise comments that offer redundant information, such as explaining the names of functions even when they are easily understood without comments.
• Commented out code creates confusion and brings down the code readability.
• The parameter definition comments used in a codebase or mandated comments also affect code readability.

// Don’t repeat the code
// get time diff
let timeDiff = currentTime - queryStartTime;
// remove milliseconds
const milliseconds = Math.round(timeDiff % 1000);
timeDiff /= 1000;
const seconds = Math.round(timeDiff % 60);
// remove seconds from the date
timeDiff = Math.floor(timeDiff / 60);
// get minutes
const minutes = Math.round(timeDiff % 60);
// remove minutes from the date
timeDiff = Math.floor(timeDiff / 60);
// get hours
const hours = Math.round(timeDiff % 24);
// remove hours from the date

1. Function and Variable Naming

Every good function or variable name is a combination of three things: Prefix+Action+Context.

Prefix - It is applicable when code is returning boolean values, such as:

• is - current state of the context, for example isMember or isAdmin
• has - current context possesses a certain value, for example hasPermission
• should - positive conditional statement coupled with an action, for example shouldUpdateEntity

Action - It is the verb part of your function name, such as:

• get - accesses data, for example getStatusCount
• set - sets variable with value, for example setUserRole
• reset - reset variable with an initial value, for example resetItems
• fetch - requests data usually network requests, for example fetchPosts
• remove - removes something from somewhere, for example removeFilter
• delete - completely remove the existence, for example deletePost
• compose - creates new data from existing data, for example composeDisplayAddress(place, area, pincode)
• handle - handles action, for example handleButtonClick

Context - It is the expected data type that a function operates on, such as:

Things to keep in mind during function and variable naming:

• The name should be intuitive and descriptive
• Avoid contractions or abbreviations that are confusing
• Avoid context duplication
• Pay attention to singular and plural names

Bad Example:

const isExtraServicesSelected = lodash.difference(inquiry.origin.services, originServices).length > 0;

Good Example:

const hasExtraServicesSelected = lodash.difference(inquiry.origin.services, originServices).length > 0;

Bad Example:

const orgModules = orgConfig.modules;

Good Example:

const organisationModules = organisationConfig.modules;

Bad Example:

class country {
 this.country_name = ‘’
}

Good Example:

class country {
 this.name = ‘’
}

Our previous post on clean coding covers the function and variable naming practices with detailed examples and can be read for a better understanding.

Results: Paving the Way Towards Code Excellence

Future-proofing the entire codebase is a gradual and continuous process.

At Shipsy, we created a robust, reliable, and thorough engineering handbook for driving clean coding practices. With a renewed focus on better design and maintainable code, we are moving towards a well-established development organization culture that motivates all of us to work smarter and better.

Explore careers at Shipsy to be a part of our consistently improving and innovation-oriented developer community.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where our team members exchange notes on specific ideas and topics. Contributions: Sahil Arora, Viraj Shah

Not only this led to an increase in the number of support tickets, but it also slowed down our IOPS, as duplicate requests kept overburdening the servers. Hence, scaling our client-initiated or on-demand analytics has been on our minds for quite some time now.

When we say scaling, we don’t specifically refer to the number of download requests that we can successfully cater to, but also the concurrent data downloads and the time large downloads take.

There are obvious advantages of scaling data analytics, such as operational efficiency, large data handling, etc., apart from ridding the process queue choking.

Here is a glimpse of how we scaled and optimized our on-demand analytics and what benefits stemmed from our pursuit.

On-Demand Analytics: Previous Scenario

Incoming data download requests were processed using scripts. These scripts ran infinitely, looking for pending download requests, as shown in the following image:

This approach was redundant because it lacked:

• Concurrency
• Efficient Resource Utilization
• Visibility

Things got irksome because of the following constraints stemming from the process inefficiencies:

• Size - Clients need a minimum of one month of data for analytics, and some of them were generating mountains of data, such as 2M+ orders in one month.
• Requests - Any average day, especially the start and end of a month, used to have a crunching workload, such as 300 to 600 download requests in a day.
• Query Time - Such large data downloads can easily take up to 15 - 20 minutes in any transactional DB (the case with us).
• Waiting Time - Queue processing meant only one request was processed at one time, and nobody likes to wait patiently for hours for their turn. Users raised multiple requests when the request took too long to get processed.

Thus, the queue got choked with requests, most of them being duplicate ones.

This killed operational efficiency and kept the queue running for duplicate requests, leading to resource wastage.

All this called for a solution that could:

• Fetch large data quickly (Seems impossible with transactional DBs).
• Perform concurrent request processing
• Cache duplicate requests

What Did We Do?

We addressed these inefficiencies by migrating to Redshift, which is specifically built for analytics

Migrating to Redshift

Transactional databases are not designed for performance-intensive analytics, and Redshift offered us an obvious advantage in this regard. It could execute operations on piles of data with lightning-fast speed and helped us overcome the performance and wait-time-related issues.

Further, Redshift supports regular SQL queries, so no learning curve was involved.

Next, we share glimpses of our migration to Redshift.

We created ETL pipelines to synchronize the data from our previous transactional database to Redshift:

Source

This pipeline first streams the data to S3 and then uses S3 to update the Redshift database, as shown in the following image:

Next, we used query builder to execute the data analytics queries for the Redshift schema.

Download Handler for Analytics

We leveraged a new service (Download Handler or DH) to achieve Concurrency and Caching.

We refined our DH operations over years of use, which helped us achieve concurrency management out of the box.

Here, we had 2 main blockers:

• Caching
• Analytics

To cache any incoming download request, creating a hash key for that specific request was necessary.

For this, we used a cacheManager that did two things:

• Toggle caching
• Generates Hash string

Once we have a hash string for a request, we could categorize each request into Main or Duplicate for managing cache.

All the requests with the same hash value were divided into main and duplicate.

Here is the snapshot for an overall idea:

cacheManager (params: any) 
    {
        const { queryToExecute: query, queryParams, organisationId } = params;
        const orgWiseDumpCacheConfig = config.orgWiseDumpCacheConfig || {};
        let useCache = true;
        if (orgWiseDumpCacheConfig[processName]) {
            useCache = get(orgWiseDumpCacheConfig, `${processName}.${organisationId}.useCache`, false) || false;
        }

        const toRet: any = {
            useCache,
        };

        if (useCache) {
            toRet.hash = hashingFunction(query) + hashingFunction(queryParams, { unorderedArrays: true });
            toRet.ttl = get(orgWiseDumpCacheConfig, `${processName}.${organisationId}.ttl`, 300000) || 300000;
        }

        return toRet;
    }

Once a request came in, the hash value was checked for the master or slave category, and if the request was a duplicate one, it was linked to the master request.

Once the master request was completed, all the slave requests were also marked complete.

Here is the complete flowchart of the entire process:

For analytics, we treated Redshift as a normal transactional data source and created a new dbId in DH.

So, an analytics dump handler would look like a normal transactional database dump handler.

Finally, we configured our resources for a specific number of concurrent requests and were able to successfully scale our on-demand analytics.

Results: Benefits We Unlocked With Redshift Implementation

Constraint Solved: Query Time Reduction

So, if a query for Rider Level Aggregated Data for one month for a client with 2.25 M orders per month used to take 15 to 20 minutes earlier, it now got completed in a few minutes. It was a gain of 20000% in query time!

Efficient, Non-Redundant, and Scalable Analytics

Our implementation analysis showed us the results (as shown in the following graph) that previously, roughly 50% of duplicate requests ran in the queue, draining our resources.

With the successful implementation of DH and Redshift, we scaled our operations and unlocked efficiency and speed.

Consistent innovation alongside consistent improvement - Shipsy’s development culture is a perfect combination of consistency and dynamism. We aim to keep our products, operations, and performance razor-sharp.

To be a part of our developer community, please visit our Careers Page.

Acknowledgments and Contributions

As an effort towards consistent learning and skill development, we have regular “Tech-A-Break” sessions at Shipsy where team members exchange notes on specific ideas and topics. This write-up stems from a recent Tech-A-Break session on on-demand analytics, helmed by Shikhar Sharma and Garima Goyal.

However, every developer leaves a distinct mark on their code because of a subjective approach towards coding. While this doesn’t escalate into concern when the developer is the only one working on a particular project, when we bring more developers and future-proofing of the codebase into the picture, things change.

Right from naming conventions to code structure and functions to modules - the understanding and perception of “How to write code” changes from developer to developer. This can bring down code readability and affect the overall value an organization can draw from its assets.

Also, we aim at making our code assets to be more standardized, global, neat, and perfectly readable for future-proofing.

Hence, we follow a set of well-cultivated code practices that help us keep our code readable for facilitating an inclusive engineering culture.

Below, we share the key takeaways from our clean coding session to energize similar efforts across the entire industry.

Why Clean Code?

When it comes to coding, there are two situations that no developer can deny having encountered:

One, where the developer begins with a crystal clear understanding of all the names, comments, references, etc. As the code progresses and assumes a mammoth stance, or becomes complex, the developers tend to lose their grip over the understanding of all the confusing names and variables.

The second one is when a developer doesn’t necessarily play by the rules when it comes to coding.

While this developer might be agile and resourceful, he leaves the organization with a code puzzle that you can take forever to solve or make sense of.

Source

It is normal for an organization to have different types of software codebases and update, edit, add, or remove code lines as the need arises. Also, organizational coding is a collaborative approach where more than one person or team is working simultaneously, or alone.

Generally, highly experienced developers or code architects create the code wireframe of the conceptual software system. These code architects also define the coding standards and various architecture standards that need to be followed during the process.

The developer team then works on this wireframe keeping the standards and software development specifications in mind.

As a number of developers are working on the different components of the software, it is inevitable for the code to have distinct peculiarities in terms of naming conventions, variables, code calls, parameters, etc.

This leads to inconsistencies, redundancies, and clunky code that is hard to read, debug and maintain keeping the future requirements in mind.

Further, every developer can make certain assumptions:

• This function name is so clear and intuitive, anyone can tell what is being done here
• Commenting on every function will make my code more readable and clearer
• I can clearly use this function call to bypass a whole page of standard routine for making my job easier
• I can assist whenever there is a problem; after all, I am not leaving the organization anytime sooner

But last-minute fixes, debugging, demand escalation, and an ever-expanding set of client demands affect the code readability.

The code is now a mess with:

• Variable names that no longer make sense
• A chain of comments that seem to convey a different meaning to every other developer
• A number of functions that look redundant or “not required”

All of them affect the code readability severely and make code upgrades, remodels, changes, and reuse extremely difficult.

The impact of bad coding practices goes beyond readability as it brings down productivity as shown below:

Source

Bootstrapping The Change

Our main focus is on the usual suspects:

• Variables
• Functions
• Formatting
• Comments

No matter how clean of a code we start with, we eventually end up with messy modules that keep hiding inside the millions of code lines. While this might not be that irksome to some, they can wreak havoc when it comes to refining or editing the code in the light of new client demands.

Many times, these revisions happen in the absence of the original developer, or after sizable time has passed since the project delivery. In that case, code readability and standardization become extremely significant for the successful completion of these revisions.

This is also important from the organizational perspective as internal applications and operations also need a clean codebase for staying future-proof even when the employees leave the organization.

Hence, we targeted the above-mentioned four key areas to build a clean and readable codebase, and below we share the highlights for the same.

Clean Coding: 4 Key Considerations for an Easy yet, Significant Initiation

Given below, are the glimpses from our playbook for driving a clean code practice that aims at creating a global codebase.

Variables

#1 - Meaningful Variable Names

Make sure that the variable names are intention-revealing and meaningful. The basic rule of thumb is to check whether a name requires a comment to reveal its intention.

If yes, then you need to change it.

Bad Example:

const hawbNo = NON_NEGOTIABLE_FIELD_MASTER_CODES.HOUSE_AWB_NUMBER;
const date = moment(booking.sailingDate).format("YYYY/MM/DD");

Good Example:

const houseAWBNumber = NON_NEGOTIABLE_FIELD_MASTER_CODES.HOUSE_AWB_NUMBER;
const sailingDate = moment(booking.sailingDate).format("YYYY/MM/DD");

#2 - Avoid Misinformation

Misinformative names always create problems and cost you your time and productivity. Inconsistent spelling is also misinformation.

Here the function “getById” returns carrier code in the key “id”.

Hence, anybody who is calling this function will have no idea about this and will surely end up with lots of errors.

Bad Example:

class CarrierService extends CarrierInterface {
  async getById( carrierId: string | null, .... ) {
    let filters: KeyWithNullableValue = {
        code: carrierId, // here carrierId is attached to the code. even function name is getById
    };
    functionLogic()
    return {
      id: carrier.code, // here it passes code in the key "id"
      name: carrier.name,
    }
  }
}

Good Example:

class CarrierService extends CarrierInterface {
  async getById( carrierId: string | null, .... ) {
    let filters: KeyWithNullableValue = {
        id: carrierId,
    };
    functionLogic()
    return {
      code: carrier.code,
      name: carrier.name,
    }
  }
}

#3 - Avoid Noise Words and Non-Distinguishable Names

Further, it is important to make a meaningful distinction by avoiding the noise words, to distinguish between variables like data or info.

You might be tempted to change one name in an arbitrary manner when you need to use the same name to refer to two different things in the same scope.

However, avoid misspellings at all costs as it degrades the code readability.

Some examples of non-distinctive names are:

booking or bookingData
money or moneyAmount
user or userInfo

#4 - No Generic Names

Avoid using generic names, such as sum, total, count, etc. and add prefixes to them for boosting code readability.

Bad Example:

async inquiryBidsCount (....) {
  let count = 0;
  functionLogic();
  return count;
}

Good Example:

async inquiryBidsCount (....) {
  let bidsCount = 0;
  functionLogic();
  return bidsCount;
}

#5 - Don’t Describe Constants in Comments

Instead of describing a constant in comments, give a proper name to it.

Bad Example:

if (request.processingCount == 5) { // 5 is the max retry count
  doStuff();
}

Good Example:

const MAX_RETRY_COUNT = 5;
if (request.processingCount == MAX_RETRY_COUNT) {
  doStuff();
}

#6 - Use Prefixes Smartly

Sometimes prefixes are a necessity and not an option.

For example, the address has many components:

• firstName
• lastName
• Street
• City
• Country

Now, if you use only “State” variable in a method, some other person reading the code might not get the idea that it was a part of an address. You can remedy the situation by adding the “address” prefix to these names, which will always convey the right idea.

Functions

#1 - Limit the Arguments

Try to use the minimum number of arguments. In our codebase, we use options as one argument. Always try to pass all optional arguments in it.

Bad Example:

async createBookingRequest(carrierCode?: string, ... , options: OptionsType<{}>) {
  if (carrierCode) {
    //functionLogic()
  }
  //functionLogic()
  return;
}

Good Example:

In the above example, carrierCode is optional, so we can pass this in options as well. This will decrease the number of arguments without changing anything in the code.

async createBookingRequest(... , options: OptionsType<{carrierCode?: string}>) {
  const { carrierCode } = options;
  if (carrierCode) {
    //functionLogic()
  }
  //functionLogic()
  return;
}

#2 - Naming Conventions

For creating a clean code, we adhere to the naming conventions for variables, when it comes to Functions as well.

#3 - Structure of A Function

Keep the functions small and stick to the “one-task-per-function” dictum to ensure the conciseness of functions.

Bad Example:

async createShippingInstruction(isDraft: boolean, ...) {
  if(isDraft) {
    // validations for draft request code
    // functionLogic()
  } else {
    // validations for non draft request code
    // functionLogic()
  }
  return;
}

Good Example:

async createShippingInstruction(isDraft: boolean, ...) {
  if(isDraft) {
    await validateDraftShippingInstructionRequest();
    // functionLogic()
  } else {
    await validateNonDraftShippingInstructionRequest();
    // functionLogic()
  }
  return;
}

#4 - Avoid using lots of conditionals

Bad Example:

const myFunc = (dep: string) => {
  const myVar = (() => {
    switch(dep) {
      case 'a':
        return 'aahoo';
      case 'b':
        return 'deadman';
      default:
        return 'spooky';
    }
  })();
  return myVar;
};

const myFunc = (dep: string) => {
  let myVar = 'spooky';
  if (dep === 'a') {
    myVar = 'aahoo';
  }
  if (dep === 'b') {
    myVar = 'deadman';
  }
  return myVar
};

const requestsHandler = (requestType: string) => {
  if (requestType === 'booking'){
    return this.getBookingObject();
  } else if (requestType === 'si'){
    return this.getSIObject();
  } else if (requestType === 'vgm'){
    return this.getVGMObject();
  }
};

Good Example:

const myFunc = (dep: string) => {
  const map = {
    a: 'aahoo',
    b: 'deadman',
    // ... goes on ...
  };
  const myVar = dep ? map[dep] : 'spooky';
};

const requestsHandler = (requestType: string) => {
  const map = {
    booking: this.getBookingObject,
    si: this.getSIObject,
    vgm: this.getVGMObject,
  }
  return map[requestType]();
};

#5 - Favor Functional Programming

Favor functional programming over imperative programming for making code testing easier.

Bad Example:

const programmerOutput = [
  {
    name: "Uncle Bobby",
    linesOfCode: 500
  },
  {
    name: "Suzie Q",
    linesOfCode: 1500
  },
  {
    name: "Jimmy Gosling",
    linesOfCode: 150
  },
  {
    name: "Gracie Hopper",
    linesOfCode: 1000
  }
];

let totalOutput = 0;

for (let i = 0; i < programmerOutput.length; i++) {
  totalOutput += programmerOutput[i].linesOfCode;
}

Good Example:

const programmerOutput = [
  {
    name: "Uncle Bobby",
    linesOfCode: 500
  },
  {
    name: "Suzie Q",
    linesOfCode: 1500
  },
  {
    name: "Jimmy Gosling",
    linesOfCode: 150
  },
  {
    name: "Gracie Hopper",
    linesOfCode: 1000
  }
];

const totalOutput = programmerOutput.reduce(
  (totalLines, output) => totalLines + output.linesOfCode, 0);

#6 - Avoid Side-Effects

Ensure that there are no side-effects of a function, such as writing to a file, modifying global variables, and sharing state between objects without structure

Otherwise, in the future, if someone needs to update or edit the code, such side effects can lead to serious outcomes.

Bad Example:

// Global variable referenced by following function.
// If we had another function that used this name, now it'd be an array and it could break it.
let name = "Ryan McDermott";

function splitIntoFirstAndLastName() {
  name = name.split(" ");
}

splitIntoFirstAndLastName();

console.log(name); // ['Ryan', 'McDermott'];

Good Example:

function splitIntoFirstAndLastName(name) {
  return name.split(" ");
}

const name = "Ryan McDermott";
const newName = splitIntoFirstAndLastName(name);

console.log(name); // 'Ryan McDermott';
console.log(newName); // ['Ryan', 'McDermott'];

#7 - Miscellaneous Pointers:

• As we cannot always avoid “switch” statements, try to keep them in a low-level class and never repeat them
• Use descriptive names to convey what the function does
• Remove all instances of duplicate code

Formatting

#1 - Variable Declaration

Declare variables as close to their usage as possible. If some variable is used in loops or in conditional statements. They must be either inside that scope or just above that part of the code.

Bad Example:

async getActiveBookingCount() {
  let activeBookingCount = 0;
  // functionLogic()
  bookings = getBookings();
  bookings.forEach((booking) => {
    if(booking.is_active) {
      activeBookingCount++;
    }
  });

  return activeBookingCount;
}

Good Example:

async getActiveBookingCount() {
  // functionLogic()
  bookings = getBookings();
  let activeBookingCount = 0;
  bookings.forEach((booking) => {
    if(booking.is_active) {
      activeBookingCount++;
    }
  });

  return activeBookingCount;
}

#2 - Keep Calling and Callee Functions Close

If a function calls another function, keep those functions vertically close in the source file. Ideally, keep the caller right above the callee; wherever possible. We tend to read code from top-to-bottom, like a newspaper. Because of this, make your code read that way.

Bad Example:

aysnc getBidDetails(...) {
}

async getBidDetailsForFF() {
  return await getBidDetails( ..., {...options, bidsView: 'FF'});
}

async getBidDetailsForShipper() {
  return await getBidDetails( ..., {...options, bidsView: 'SHIPPER'});
}

OR

async getBidDetailsForShipper() {
  return await getBidDetails( ..., {...options, bidsView: 'SHIPPER'});
}

aysnc getBidDetails(...) {
}

async getBidDetailsForFF() {
  return await getBidDetails( ..., {...options, bidsView: 'FF'});
}

Good Example:

async getBidDetailsForShipper() {
  return await getBidDetails( ..., {...options, bidsView: 'SHIPPER'});
}

async getBidDetailsForFF() {
  return await getBidDetails( ..., {...options, bidsView: 'FF'});
}

aysnc getBidDetails(...) {
}

Comments

Writing a description or summary of the functions is a good thing. But writing comments as make-up for bad code is not.

Like if some function or variable name is not good and we just write some comment to cover that thing. In this case, we always have to use the correct name so that it's self-descriptive.

Bad Example:

// Check to see if the employee is eligible or not for full benefits
If ((employee.flags & HOURLY_FLAG) && employee.age > 65)) {

}

Good Example:

If (employee.isEligibleForFullBenefits()) {
}

Below, we share some pointers to keep in mind for good and bad commenting practices.

Good or necessary comments:

• Legal comments
• Explanation of intent: Basically sometimes we have to give some useful information about the implementation of the decision we took there.
• Clarification: Sometimes we get in a situation where we have to clarify about the return object or we are using any third-party things. Like defining EDIFACT segments' names by comments.
• TODO comments

Bad Comments:

• Redundant comments or noise comments, such as defining the function or variable even when you can understand them easily by their names.
• Mandated comments, all the parameters’ definition comments that we used in our code base.
• Commented out code always creates confusion and degrades the code readability.

Bonus Tip - Error Handling

Thrown errors are a good thing!

They mean the runtime has successfully identified when something in your program has gone wrong and it's letting you know by stopping function execution on the current stack, killing the process (in Node), and notifying you in the console with a stack trace.

Hence, we never ignore the caught errors.

Doing nothing with a caught error will mean you never reacted or fixed it. Logging the error to the console (console.log) isn't much better as oftentimes it can get lost in a sea of things printed to the console.

If you wrap any bit of code in a try/catch it means you think an error may occur there and therefore you should have a plan, or create a code path, for when it occurs.

Bad Example:

try {
  functionThatMightThrow();
} catch (error) {
  console.log(error);
}

Good Example:

try {
  functionThatMightThrow();
} catch (error) {
  // One option (more noisy than console.log):
  console.error(error);
  // Another option:
  notifyUserOfError(error);
  // Another option:
  reportErrorToService(error);
  // OR do all three!
}

Establishing a Clean Coding Culture: Every Step Is Crucial

While it is easy to elaborate on the clean coding practices on paper, implementing them at an organizational level is a game of patience and time.

At Shipsy, we facilitate a clean coding culture by making it an essential part of our engineering onboarding process.

We also follow the Engineering Guide that we have built from scratch. We keep on updating it with every project to keep every developer on the same page.

Finally, we ensure that our entire community stays abreast of all the latest developments and clean coding practices by organizing regular tech sessions where we share, learn, and innovate in a sustainable manner.

Such organizational measures and initiatives leave no room for discrepancies or a lopsided codebase.

Fostering a clean coding culture at the organization level is an ongoing process and we hope that our inputs and endeavors energize similar efforts across the global Dev community.

So, to all our coding fellows - “In Code, we Trust!”

Source

We want to share with you some of the work that we are doing; essentially, how we catered to our multiple Shopify app clients via a single server.

Before we get into the granular details, it is important to understand the driving force behind this.

There are three crucial components of Shopify SDK:

• Shopify App Bridge
• Shopify Auth
• Shopify API

The Shopify App Bridge connects the client-side with the Shopify server. The Shopify Auth and Shopify API libraries perform the underlying and facilitating tasks, such as communications, authentication, and validation.

Now, both these libraries are stateful, this means that once they have a “state” variable, context object in this case (we will revisit this in later sections), these libraries don’t allow any change in it.

So, once the context object has a client ID, Shopify libraries will not allow you to change it, and thereby, the Shopify libraries only support “one-server-one-app” architecture.

However, we wanted to change that!

Problem Statement

Achieving a “create once, use infinitely” capability on our Shopify app to ensure that our entire customer base from different domains is able to use the same product.

Essentially, we wanted to make the Shopify libraries “stateless” and allow us to dynamically change the context object as per the incoming connection requests.

Now, this was something like getting your own highway for your specific traveling needs!

Yes, it was nothing short of a Utopia, but Hey! We at Shipsy realized our Utopia!

Presented here, is a walk-through of our entire endeavor and a little glimpse of what it took to get our own highway!

Challenges to Our Approach

Shopify’s API libraries are stateful, which means that all the APIs share a global context object. If you don’t have core libraries, you cannot use this context object as per your wishes.

Before we move ahead, let us have a brief discussion about this context object.

The context object has all the information of the Shopify API key and API Secrets for each app. Both of them play an essential role in authentication and verification via session tokens and JW tokens.

So, the Shopify app libraries have only one context object and in that context object, there is only one combination of API Key and API Secret.

As this context object is being used everywhere - for sending app requests to the Shopify server and getting responses back from the same - we were not able to use the single server for serving app requests from multiple apps.

So, what we did can also help the developer community across the globe. The developers can learn from this approach and leverage the Shopify server to serve multiple apps from a single server.

Overcoming Context Object Challenges With Custom Libraries

We custom-coded the Shopify API and Shopify Auth libraries.

While the Shopify Auth library for our apps is entirely built from scratch, line-by-line, Shopify API is coded as per the business’ unique needs.

By doing this, we converted Shopify libraries from stateful to stateless libraries!

Hence, whenever a request comes from the Shopify dashboard, or from the Shopify App Client to the server, instead of using Shopify libraries, we use our custom-coded Shopify Auth library.

Next comes a step that is one of the many fantastic things code can help us developers do!

We have a custom logic that identifies which app is requesting this service.

Once we know which app is requesting the connection, we can pass the context object in every function with request-based parameters, and it is no longer global.

Next, a pure function (which is also custom coded), takes the data from this context object parameters and sends it to the Shopify server.

While a major hurdle was overcome, there was still one consequential challenge left.

How to Know Which App to Serve?

Whenever we create an app, we set a custom subdomain on the basis of its domain and we tell the app the correct server API so that it hits the right server.

The config file stores the client details, on the basis of which, we figure out which app needs to be served.

Now, we configured our DNS such that all the requests coming on this domain are sent to the Shipsy server.

All the incoming app requests are encountered by the frontend and we identify which app needs server access. Once this is done, all the other communications are then internally handled by custom Shopify Auth and Shopify API.

This Shopify API is handling all the conversations we are having with Shopify, such as any data we require from Shopify, etc. Our custom Shopify Auth handles all the logic on the server-side of the Shopify App.

Now we will talk about the client-side architecture of our Shopify App.

Overcoming the Client-Side Challenges in Custom Library Riddle

For all the pages in the front end, we call the APIs indirectly, as our app is loaded in Shopify, and now we are making API calls, such as soft data, label generation, virtual series generation, etc. there only.

This is because earlier the request authentication and verification were managed by Shipsy.

However, in Shopify's case, authentication is done at Shopify’s frontend and our app backend and frontend.

We know that you might need to read that sentence again.

So, here is a little something to keep you motivated to do so:

Source

Let us try to understand this with the help of an example.

How We Authenticate Our Frontend With Our Backend?

Suppose we load a page or data on a page.

Now, before that request is processed, sync is loaded/ordered, and the frontend sends the request to Shopify.

In our backend, our middleware processes the session token, which has many values and details, such as - expiry time, Shop Name, etc. which is a unique identifier in our case.

As soon as the app frontend is loaded, initially, a skeleton is loaded. This skeleton loads the Shopify App Bridge client on the browser of the app user.

Now, every time the user sends a request, we include a session token in its headers, which we get from the Shopify App Bridge. This session token is verified on our Shopify app backend (server) to confirm whether the request is coming from a genuine source or not.

Once we know that the Shopify request is true and valid, the request gets processed normally.

Next, we discuss how this process generated desirable results for the entire Shipsy ecosystem.

Results of Custom Coding the Shopify Libraries

No Automatic Logouts

Earlier, when we used to manage authentication and verification at our end, we used session cookies for the process.

Now, once these session cookies expired, the clients were automatically logged out and that led to redundancy in the user experience.

Now, the authentication and verification are handled by our custom Shopify Auth library and the logouts don’t happen automatically.

Single Server for Multiple Clients

By creating custom libraries for our Shopify app, we are now serving multiple clients via a single server, which obviously comes with a lot of operational and management advantages.

Multilingual Shopify Stores

Being able to regulate the context object, we are now enabling organizations to use the same admin account for managing multiple stores that use multiple languages.

Looking Ahead

Every new undertaking in coding comes with a slew of learnings and this one also brought many of them to our team. We plan to leverage them across multiple scenarios and encourage our fellow developers to follow the suite.

Experiential learning impacts in the Dev community can spur a huge wave of transformation that benefits masses at a large scale.

And, at Shipsy, we believe in driving such changes and welcome the change drivers with an open embrace and an excellent Dev culture.

Wish to experience the wave of change? Get onboard with Shipsy and get started with your journey with our Dev Team.

Mobile technology evolved by leaps and bounds in the last decade, and along with it came skyrocketing demand for building apps for archaic company websites. Soon businesses realized the true potential of cloud-based apps with regards to scalability and supporting growing traffic volumes of their online business. Result? Millions of apps on the Play Store, App Store, and more.

However, apps have one major disadvantage in contrast to traditional websites. It is the ease of access. Any web browser can easily access a website by accessing its URL. But when it comes to using an app, one needs to have access to an Application Store. Along with that emerges the need to have an account. In other words, in App Store, one needs an Apple ID and a Google Account for Play Store.

So, is it a good idea then to have a website on a mobile device? It’s also not an ideal approach. A mobile website tends to be slow and it’s not adaptive to ever-evolving mobile screens. According to KissMetrics, Out of 100 people visiting a website, 40 abandon it just because it takes too much time to load. Just imagine the revenue that is lost because of website downtime. Research highlights that just 15 minutes worth of website downtime can cost businesses $12,495 in lost profits. No wonder the man below is so angry!

These usual problems with traditional websites and accessibility constraints of apps were enough to fuel the next major evolution in the app industry. As a result, the world was introduced to PWAs (Progressive Web Apps).

What are PWAs?

PWAs are simple web apps built using common web technologies like HTML, CSS, and JavaScript. The idea of PWA is not new, and it was first introduced by Steve Jobs. For the first time, he presented the concept in front of the world during the iPhone introduction in 2007. However, the term “PWA” is recent and was coined by Google Chrome developer Alex Russel and designer Frances Berriman in an article in 2015.

PWAs are faster, light-weight, easily extensible, and even work offline. The big advantage of PWAs is that they can be easily found on the web and can work on any mobile device that supports a web browser.

Also Read: A Progressive Web App Might Be Right for Your Brand

In India, where mobile data speeds are still limited, it made sense for companies to adopt PWAs and PhonePe. Considering the potential opportunity in delivering the PWAs, it launched its microapps platform called PhonePe Switch.

What is PhonePe Switch?

PhonePe Switch is a platform that hosts a vast collection of microapps with over 300 million active users. It reduces customer acquisition costs for any company by providing a user with one-click access to hundreds of apps and seamless integration with its secure payments channel. Existing mobile sites or even a PWA can easily be hosted on the platform by easy-to-follow guidelines provided in this documentation.

Looking at this opportunity we decided to host our Flutter App on the platform, considering that Flutter now supports building PWAs with the introduction of Flutter Web.

We ran our flutter app on chrome and we came across the following challenges:

1. Routes are hashed by default. For ex: localhost54724. These routes create problems in reading the query parameters and we were planning to use them
2. Some packages like geocoder and place picker didn’t support web platform
3. Image uploading and some other I/O operations have different implementations in web and mobile For different implementations, we had to separate the code for image upload for web and mobile platforms

Solution:

The above challenges can be solved if we make a web-specific service and encapsulate all the web-specific implementations there (same for mobile):

Define an interface for IOService containing all the methods to be implemented

abstract class IOService {}

Implement IOServiceMobile and IOServiceWeb from the interface and define platform-specific code

class IOServiceMobile implements IOService {}
class IOServiceWeb implements IOService {}

Conditionally import the service

import 'web_service_mobile.dart' if (dart.library.js) 'web_service_web.dart';

In the web service constructor, we can change the path URL strategy to solve our challenge for hashed routes (challenge no 1). For different implementations in web and mobile for the same logic (challenge no 2 and 3), we can implement package-specific methods and separate implementations for mobile and web, so the conditional import will execute the specific method from the platform-specific service.

Now our PWA is running, so we deployed it on our AWS ec2 instance. The next step is to make it work inside the PhonePe switch

According to PhonePe switch docs, we have the following requirements:

1. Deployed PWA
2. Pre Prod APK for PhonePe
3. Unique ID from PhonePe

Also if you want your app to work on a switch platform, you need:

1. SSO login feature

On the login screen, you should get a prompt for logging in via PhonePe SSO. If the user skips the login, then normal login can be done.

2. Payment using PhonePe

When a user makes a payment, the PhonePe payment screen has to be shown directly.

To implement the PhonePe switch, we implemented a PhonePeService for both mobile and web. Just like IOService and implemented the PhonePe JS SDK using our dart code. This also took some time to do but was achievable. We managed to load the SDK using JS wrappers in dart, Futures, and Completers.

  Future<void> loadSdk() {
   final Completer _completer = new Completer();
   if (isPhonePeSwitchPlatform()) {
     var head = document.getElementsByTagName('head')[0];
     var jsScript = document.createElement("script");

     jsScript.attributes.addAll({
       'type': 'text/javascript',
       'src': 'scripts/phonepe-sdk.js',
     });

     jsScript.addEventListener('load', (event) {
       window.console.log('[PHONEPE] Script Loaded');
       _initializeSdk();
       _completer.complete();
     });

     head.append(jsScript);
   }
   return _completer.future;
 }

 Future<void> _initializeSdk() async {
   var phonePeParent = jsUtil.getProperty(window, 'PhonePe');
   var phonePe = jsUtil.getProperty(phonePeParent, 'PhonePe');
   var constants = jsUtil.getProperty(phonePeParent, 'Constants');
   var species = jsUtil.getProperty(constants, 'Species');
   jsUtil.setProperty(phonePe, 'loggingEnabled', true);
   window.console.log('[PHONEPE] LOGGING ENABLED');
   _sdk = await jsUtil.promiseToFuture(jsUtil
       .callMethod(phonePe, 'build', [jsUtil.getProperty(species, 'web')]));
   window.console.log('[PHONEPE] SDK INIT DONE');
 }

Window and document are imported from dart:html and jsUtil is imported from dart:js_util package as:

import 'dart:js_util' as jsUtil;

Similarly, we managed to achieve the SDK methods implementation by wrapping them up like this.

The web application can be done using flutter and is not that tedious. Try it out yourself. If you love to solve complex engineering problems like this one, we would love to know you better. Check out the open job positions here , we would like to start engaging.

At Shispy we empower global businesses to optimize, automate, track and simplify end-to-end logistics and supply chain operations using our smart logistics management platforms. To enable this, we are handling complex cloud infrastructure at a massive scale.

We soon realized that it would be challenging for the infrastructure team to create, configure and handle the cloud infrastructure manually. So, the logical conclusion was Infrastructure as Code. We started using Terraform as our tool for Infrastructure as Code implementation.

In this article, we will explain the processes that we created for easy usability and scalability. Innovation and first principles thinking were key factors that empowered us to address scalability issues.

1. State File Management

Terraform keeps a state file (with the name terraform.tfstate in the folder where you run terraform apply) in which it stores the current state for infrastructure resources being managed by it. Whenever we run terraform plan or terraform apply, it compares our code with the data in the state file and tries to sync them. Now, this introduced us to the following issues when terraform was used in the production.

• Every member of the team needed the updated copy of the state file for creating the infrastructure

• Resolve conflicts when multiple team members are trying to update the state file

• Reverting back to the previous version in case of a big blunder was a mess

Soon we realized one important thing we need to do is keep the state file at a remote location where anyone working on the infrastructure can access it. This removed the need to keep different copies of the state file with each infrastructure developer. Additionally, we needed the locking facility so that simultaneous updates to the state files do not cause headaches for us.

Fortunately, terraform indigenously supports this via Terraform Backend. Terraform Backend simply controls how the terraform stores and loads the state. Terraform supports many backends such as Amazon S3, Google Cloud Storage, Terraform Enterprise, etc. Almost all the remote backends also give us the facility of locks. Terraform will get the lock on the state file before running terraform apply, all other requests for the file will have to wait until this operation is either completed or aborted.

We chose Amazon S3 in combination with a dynamoDB table for locking state files. Further, we enabled versioning on our S3 bucket. So, now we have all the state files and can switch back to any of them almost instantaneously. After creating the S3 bucket and the dynamoDB table we just added the following code to enable the Terraform Backend:-

terraform {
 backend "s3" {
   bucket = "<your bucket name>"
   key    = "terraform.tfstate"
   region = "<region of your s3 bucket>"

   dynamodb_table = "<name of the dynamoDB table>"
   encrypt        = true
 }
}

2. Modules ( DRY )

We realized a lot of our terraform code was repetitive. For instance, the terraform code for creating a new AWS Batch service was almost the same for dev, staging, and production environments. Even in the same environment, there were a lot of common steps for creating different Batch jobs.

In other programming languages, we usually create a function for the repetitive code and then just call it from all the places. Similarly, Terraform provides us Terraform Modules, which can be written once and then called multiple times.

resource "aws_batch_job_definition" "main" {
   name = local.batch_job_name
   type = var.job_type
   platform_capabilities = var.platform_capabilities
   container_properties = jsonencode({
       command = var.command
       image = local.container_image
       jobRoleArn = var.job_role_arn
       memory = var.memory
       vcpus = var.vcpus
       environment  = local.environment
   })

   tags = local.final_tag
}

// schedule the job

resource "aws_cloudwatch_event_rule" "event_rule" {
   name                = "${title(local.environment_type)}Schedule_${var.name}"
   description         = "Cloudwatch Rule for ${local.batch_job_name}"
   schedule_expression = "cron(${var.cron_parameter})"
}

resource "aws_cloudwatch_event_target" "event_target" {
 rule      = aws_cloudwatch_event_rule.event_rule.name
 batch_target {
   job_definition = aws_batch_job_definition.main.arn
   job_name = local.batch_job_name
 }
 role_arn = var.cloudwatch_event_job_role_arn

 // get the arn of the queue based on the environment
 arn = lookup(local.batch_queue_arn, terraform.workspace)
}

Now the above code can be called anytime we need to create an AWS Batch job.

module "batch_job" {
 source = "../../../../modules/aws-batch"

 name           = "test-script"
 vcpus          = 1
 memory         = 256
 cron_parameter = "30 4 ? * MON *"
}

Additionally, it abstracted out a lot of implementation details. Now, all our engineers write the script's name, resource requirements, and the cron parameters. This has reduced the script deployment time after production merges from 3 hours to 5 mins. We have written modules for all the infrastructure components.

3. Environment Isolation

As an organization, our philosophy is of learning through experimentation. So almost all the engineers perform numerous experiments which sometimes cause issues. In order to allow these experiments and keep our systems healthy, we have isolated our environments. Ideally, we wanted our dev, staging, and production infrastructure and the corresponding state file to be fairly isolated. This isolation can be achieved in two ways. One is Terraform Workspaces and the other is the file structure of your terraform code.

3.1 Terraform Workspace

Terraform workspaces provide us separate state maintenance. The most interesting aspect is, terraform creates separate state files for each workspace. Initially, you start in the “default” workspace. With the command terraform workspace new <workspace name> you can create a new workspace. Then terraform will automatically create an “env:” folder and will put the state file for this workspace in the AWS S3 bucket we are using for state files. You can switch workspace using terraform workspace select <workspace name>

Leveraging this information, we created three different workspaces, one for each dev, demo, and production. So now we are sure that any change in the dev or staging environment will not impact our prod state file and hence production infrastructure.

3.2 File Structure

Terraform Workspaces are a good way to achieve isolation. However, they are almost invisible at the code level. This caused many bugs since the developer didn't know whether the code will run for production or staging environments. Therefore, we have separate folders for each environment and then each resource type has its own folder. This brings out greater transparency for the developers and reduces the chances of wrong commits (i.e. code for staging pushed to production).

4. Deployment Pipelines

Creating infrastructure from developers' local machines using terraform apply initially worked smoothly. But as we scaled we realized this process had some limitations, like:-

• Opaque:- anyone could run the terraform apply, even sometimes without the PR review

• Scalability:- all developers changing infrastructure at the same time created chaos

• Permission Management:- everyone needed almost full write permission which could have been catastrophic

So we decided to create Jenkins Pipelines for the infrastructure creation using terraform. Our flow now involves:-

• Creating a branch from the production branch

• Making your changes

• Running a Jenkins pipeline to create a plan (output will show the changes that will happen in the infrastructure if this PR is merged)

• Creating a PR request and putting the link of the above run pipeline in the description. This makes the reviewer's life easy as now they know what will happen if this PR is merged.

• After the production merge, we run the Jenkins deployment. Our Jenkins deployment has an approval step. You need to read the plan and if you are satisfied with the plan then only the job will be complete.

• Created a user for Jenkins in the cloud provider and giving only this user the access to create infrastructure. This ensures that there is only one point of infrastructure modification across the organization

pipeline {
    agent {
        node {
            label 'master'
        }
    }
    stages {
        stage("initialize terraform") {
            steps {    
                sh "terraform init"
            }
        }

        stage("switch the workspace") {
            steps {
                sh "terraform workspace select ${env_type} || terraform workspace new ${env_type}"
            }
        }

        stage("validate the config") {
            steps {
                sh "terraform validate"
            }
        }

        stage("create the plan") {
            steps {
                sh "terraform plan"
            }
        }

        stage('Approval') {
            steps {
                script {
                    approver  = input(id: 'confirm', message: 'Apply Terraform ?', submitter: '', submitterParameter: 'submitter')
                }
            }
        }

        stage("apply the plan") {
            steps {
                sh "terraform apply -auto-approve"
            }
        }
    }
}

5. Refactoring

Continuous refactoring of the code for improving readability and the hygiene of the code is the inevitable truth of modern software development. However, refactoring in terraform is a little tricky since this will make your code out of sync with the state file. Result? Unexpected changes to your infrastructure even leading to downtime in the worst case.

What's the solution then? Terraform provides few CLI commands for the management of the state file. One of them is terraform state mv <source> <destination> (.i.e terraform state move). Using this command we can edit the state file and make it in sync with our new code without changing any infrastructure.

terraform state mv 'module.create_app_clients.raven' 'module.create_app_clients.raven-main'

Interestingly, you can run terraform state mv -dry-run which won't change anything but will let you know what will happen if you move the state.

Even for the CLI commands, we have separate Jenkins pipelines. After your PR is merged in the production branch, the pipeline will run with the appropriate commands.

If you love to solve complex engineering problems like this one, we are hiring. Check out the open job positions here.

You might have often found yourself struggling to set up new projects owing to scattered information and multiple dependencies, making it difficult for a new hire (developer) to understand which version to use. Then issues like inadequate CPU power of laptops slowing down software development processes makes it difficult to build more than one project at a time. Result? Massive productivity loss.

Another significant challenge that we frequently face is driving integration testing between different services. More often than not, all the integration issues are actually discovered post-development branch mergers. This is a very reactive approach to development and we wanted to change that.

Existing cloud technologies have made it extremely easy to get powerful remote machines at the click of a button at very economical rates. Our goal was to leverage cloud-based systems to shoulder heavy compute and storage requirements and enhance developers' productivity.

Here’s How We Achieved Our Goal in 7 Easy Steps

Step 1: Selecting VMs

We selected powerful virtual machines from AWS (you can choose any cloud provider e.g. Azure, GCP, etc.) and granted developers access to the same based on their team and project.

Step 2: Creating A User on The VM

Now whenever a developer joins a team, they fill a google sheet with their Bitbucket username, public SSH key, and the projects they are working on. This triggers a script that creates a user on the virtual machine.

Then we made a folder for this user and give them access to that folder only. The script also adds the user's SSH key to the 'authorized_keys' file, enabling the user to connect with the remote machine seamlessly.

add_user_with_ssh_key() {
   adduser --disabled-password --gecos "${full_name},,," --quiet ${username}
   mkdir /home/${username}/.ssh
   touch /home/${username}/.ssh/authorized_keys
   echo "$ssh_key" > /home/${username}/.ssh/authorized_keys
   chown -R ${username}:${username} /home/${username}/.ssh
}

Step 3: Restricting CPU Utilization

An imbalance in resource utilization can pose challenges when implementing this strategy. But we figured out a way to address it. To ensure one particular user does not exhaust all the resources, we created a separate cgroup for each user (cgroups in simple terms allow you to restrict how much resource users in a particular cgroup can use). This ensures that isolation between the users is maintained. In other words, there is zero interference between activities done by concurrent users of a machine.

For more detailed information on cfs_quota_us, cfs_period_us and limit_in_bytes refer resource_management_guide.

add_cgroup_configs() {
   echo -e "group ${username} {
    cpu {
        cpu.cfs_quota_us=20000;
    }
    memory {
        memory.limit_in_bytes = 10240m;
    }
   }" >> /etc/cgconfig.conf
   echo -e "\n ${username} cpu,memory ${username}" >> /etc/cgrules.conf
}

restart_cgroups_services() {
   systemctl restart cgrulesgend.service
   systemctl restart cgconfigparser.service
}

Step 4: Cloning Repositories

Then we created the SSH key pair and gave READ access to all repositories. This allowed us to clone the repositories of all the said user's projects in the 'user folder.' Post cloning, we changed the config file in the .git folder ensuring that any future commits/pushes are done on that particular user's behalf only.

The script will further do the following things:-

• Install all the dependencies of the projects

• Install basic software packages like git, node, python, docker, etc

• Copy the configuration files for the projects

So, now the project is ready to be used on a virtual machine. But the question is how to make it easily accessible and simple to work with for the developers? Luckily the good guys at Remote Development have developed a great VS Code plugin to solve this problem.

def setup_project(username, projectName, githubID):
   try:
       bitbucketCreds = bitbucket_config()

       print
       gitCloneCommand=f"""
           git clone https://{bitbucketCreds['username']}:{bitbucketCreds['password']}@bitbucket.org/dhr00v/{projectName}.git /home/{username}/{projectName}
       """
       run_system_command(gitCloneCommand, "Could not clone repository")
       changeLocalRepoOwnership=f"""
           chown -R {username}:{username} /home/{username}/{projectName}
       """
       run_system_command(changeLocalRepoOwnership, "Unable to change local repo ownership")
       gitChangeUserCommand=f"""
           sudo -H -u {username} bash -c "cd /home/{username}/{projectName} && git remote remove origin && git remote add origin https://{githubID}@bitbucket.org/<yourbitbucketaccountname>/{projectName}.git"
       """
       run_system_command(gitChangeUserCommand, "Unable to change email")
       print("Base Project Setup Completed")
       fetch_config_from_system(username, projectName)

   except Exception as e:
       print(e)

Step 5: Installing A Simple Plugin

You need to install the plugin, do a common palette search for "Remote SSH:Open configuration file" and enter your details.

Host <your VM’s DNS/IP>
 HostName <your VM’s DNS/IP>
 User <your user name on the VM>
 ForwardAgent yes
 IdentityFile <location of public ssh key file on your computer>

Step 6: Connecting VS Code with the VM

After that, click on the Remote Development button, the one you will see on the left panel, to connect with the machine. Now your VS Code is connected to the virtual machine on the cloud. After these steps, even though it will appear as if a developer is working on her local system, in reality, it's the powerful cloud-based virtual machine she is working on.

Step 7: Executing Integration Testing

With all your developers working on the same machine, a back-end engineer can run the server on the VS Code (which is actually running on the virtual machine) and give the port number to the corresponding front-end engineer for integration testing. One does not need to first get their branches merged and deployed. When both the engineers are satisfied, then their PRs can be merged. This will significantly reduce the development time.

In a nutshell, at Shipsy, we are seamlessly scaling development and testing environments irrespective of a developer's base location and laptop capabilities. In other words, our engineering teams' work is powered by the cloud, but from a developer's perspective, they are just working VS Codes on their own laptops.

If you love to solve complex engineering problems like this one, we are hiring. Check out the open job positions here .