What The Interns Shipped

Flexport Engineering has hosted interns for several years now and summer 2022 was no different. (Several previous interns, myself included, have written about our projects and experiences on the blog.) It marked the third consecutive year that our internship program was fully remote, but that didn’t stop our interns from shipping a number of impactful projects.

First, a bit of context on our internship program: Flexport’s engineering interns are embedded in teams across our major tech hubs, including Chicago, San Francisco, and Bellevue. They work alongside other engineers, designers, and product managers; on many teams, interns are even in close contact with our users — customers, supply chain operators, warehouse staff, truck drivers, and more. Moreover, all our interns work full-stack, gaining experience with an array of front- and back-end technologies. It is not unusual for our interns — and you’ll hopefully notice this with the projects we’ve profiled — to work concurrently with Ruby on Rails, React, Sorbet, PostgreSQL, GraphQL, and Flow. And of course, we try to ensure that our interns depart from Flexport well-versed in essential non-coding skills like project planning, documentation, and written/oral communication. (If this program and the following projects pique your interest, do note that we’re looking for new interns! Check out the end of this post for more information.)

Our most recent intern cohort accomplished a lot in their 12 weeks. Some of the projects that our interns tackled included:

• Automated cargo label printing at Flexport and partner warehouses
• Configurable filters on our air demand and supply pages
• Self-service user interfaces for adding sailing routes, instead of requiring developers to manually add the database entry
• Transmission features for trucking carriers to assign specific “loads” to particular drivers, eliminating the need to communicate such information via text or email

For this post, however, I’ve chosen to profile just three projects that reflect the type of work Flexport interns can take on to have an outsized impact:

• Evan Hu built a “universal” document viewer to give users a visual interface to the results of our automated transcription systems.
• David Cheng consolidated the workflows for offsetting carbon emissions for Flexport’s shipments and shipments moved by other freight forwarders or last-mile transportation providers.
• Sam Jones created a dynamic integration between Jira support tickets and in-app feedback forms.

Universal Document Viewer

As a global logistics platform and freight forwarder, Flexport deals with a lot of documents: commercial invoices, packing lists, bills of lading — the list goes on and on. Oftentimes, there is data on these documents that Flexport wants to enter into its systems in a structured format. Historically, this would have been accomplished via manual data entry: humans would parse documents for important pieces of information and type them into our software.

As Flexport has continued to scale, we’ve been building more tooling to do this process — which we’ll call transcription — in an automated fashion. When certain classes of documents are uploaded, their important data is parsed using machine learning technologies and fed into Flexport’s systems. This newer process is significantly more efficient, but it also heightens the risks posed by bad data: what is the recourse when documents are not parsed accurately? How do supply chain specialists quickly reference the source document of transcribed data? Evan Hu was presented with these motivating questions (and a few design mockups). His task: build visual tools for operators to view — and correct — the transcription results of any document uploaded to Flexport’s platform.

First up was a document viewer workspace. Users could navigate through a particular document to inspect data of interest, view document metadata, and pore over logs of certain actions taken on that document. As he did throughout the summer, Evan utilized React and Latitude, Flexport’s design system, to build the workspace from scratch. Moreover, he thought hard about how to design intuitive and reusable interfaces for each of his React components, anticipating that future features would be built with the patterns he established.

A document workspace is a useful tool for viewing all the information about a particular document, but in certain cases, it can create noise. For example, operators looking at a specific shipment might be interested in only one data point, and they don’t want to jump back and forth with the workspace. Ideally, they could get the information they need in line.

A natural next step for Evan was to build out a document preview widget that solved this problem. The widget presented Evan with his toughest technical challenge of the summer: determining the correct proportions (in pixels) for (1) the “bounding box” that surrounded the data points, (2) the sub-section of the underlying document from which the data is sourced, and (3) the popup that enclosed it all. He and his team iterated on their approach multiple times, ultimately settling on an intelligent scaling scheme that maintained visual consistency across various document, bounded box, and browser size permutations.

Evan’s work stands to massively improve operator trust in our transcription systems and improve the efficiency of resolving bad data. I look forward to seeing his preview widget seated alongside data points across all of Flexport’s products in the coming months.

Streamlined Carbon Offsets

Flexport.org, the environmental and social impact arm of Flexport, leverages Flexport’s technology platform and shipping expertise to help nonprofits, NGOs, and clients with their social and environmental impact. One of the team’s key offerings is allowing clients to offset their carbon emissions directly in our software. To this end, Flexport.org supports offsetting emissions for shipments that Flexport moved and those it didn’t (hereafter referred to as “non-Flexport” shipments).

However, the product and backend offset workflows differed between Flexport and non-Flexport shipments. On the product side, the forms for each offset type were located in separate areas in our client-facing app. And on the backend, we had to separate services to handle each type of offset — despite the fact that the APIs for offsetting each shipment type were the exact same. (More on that later.) This duplication led to additional overhead for the Flexport operators fulfilling offset requests.

As an intern on Flexport.org’s technology team, David Cheng’s job was to consolidate these disparate product and code paths. He broke this work down into three main stages:

1. Refactor the backend APIs (Ruby on Rails)
2. Modify the GraphQL queries, mutations, and types
3. Build an intuitive frontend interface (React)

The first milestone was the most challenging: David had to familiarize himself with legacy Ruby code that had been around for 2+ years and think critically about how to cleanly merge the business logic for offsetting Flexport and non-Flexport shipments. In my view, the backend function signatures (Sorbet types included) before and after his work illustrate clearly the tech debt he had to pay down.

By the end of his project’s first stage, David had consolidated the business logic for processing Flexport and non-Flexport carbon offsets. Soon after, David updated the GraphQL layer to work with the updated logic and used React to build out the new front end (of course, in close collaboration with his team’s designer).

David’s hard work across the stack led to benefits for all stakeholders. On the engineering side, he cleaned up a long-standing piece of technical debt, making the code easier to reason about and build on top of going forward. And on the product side, he built a new offsets workflow that will soon be integrated into Flexport’s Emissions Analytics page, the one-stop shop for all the carbon emission information our clients care about.

Dynamic Jira Support Forms

Flexport, like many large organizations, uses Jira as its primary tool for bug tracking. When our users run into roadblocks, they know to submit support tickets on which product teams can take action. In fact, this process was so common that, some years ago, Flexport embedded support forms directly in our software. No longer would users have to navigate to the correct form in Jira; instead, our native forms would take input and (attempt to) map that data to a format that Jira’s API would understand, thereby allowing us to submit Jira tickets automatically.

This in-app support form was quite popular, but its high usage exposed an acute technical limitation: the integration between our frontend form and Jira backend was brittle. Several aspects of the implementation were hard-coded, and as a result, our product and business teams could not easily adapt the Jira forms to fit the ever-evolving needs of Flexport operators; corresponding front-end engineering work would always have to be scheduled — and waited on.

Sam Jones’s summer project was to tackle this challenge and create “dynamic” support forms. Rather than maintaining separate Flexport and Jira support forms and hoping that the integration between the two wouldn’t break, he and his team wondered if we could dynamically generate the frontend form from the pre-configured Jira form. Hypothetically, this would guarantee consistency between the in-app and Jira support forms.

The biggest source of technical complexity in this project, in my view, was grokking all of the various “mapping” that needed to happen between Flexport and Jira systems. For example:

• Mapping authentication information such that we can attribute Jira support requests to the correct Flexport users
• Mapping the Jira support form field types (returned from a GET request to Jira’s Service Desk API) into front-end Latitude components
• Mapping user input on the front end into a standardized GraphQL object to pass to the backend (via a mutation)
• Mapping that input data back into a format that Jira’s API expects (to automatically submit the ticket)

By the end of his summer, and despite this complexity, Sam had implemented a reusable, dynamic support form that’s now in use across Flexport’s various applications. Moreover, the clean design patterns he utilized throughout his JavaScript and Ruby code should allow engineers to build upon his work in the future. Great work, Sam!

And we’re looking for more interns!

If the projects described above sound interesting to you, please note that we are hiring! Among other positions, we’re actively looking for full-stack winter/spring and summer interns — as well as new graduates — to join our Chicago, Bellevue, and San Francisco engineering hubs. We’ll be hosting a number of on-campus recruiting events this fall, so do keep your eyes out for a Flexport booth at your university.

This post — and its format — was inspired by Yaron Minsky. Thanks to Aakash Prabhu, Emily Hu, Andy Hamon, and Cate DeBenedictis for reviewing early drafts. Thanks also to Evan, David, and Sam for taking the time to answer my copious amounts of questions about their projects.