HubSpot customers using your app are located around the globe.
They access HubSpot’s product infrastructure which is hosted in the United States, Canada, Australia, and the European Union but what if your backend infrastructure was located only in the Eastern United States?
When a HubSpot App Card user triggers an action like clicking a button, the subsequent hubspot.fetch() request must travel to and from the user's location to your backend server. This round-trip time (RTT) can be significant, especially for users located far from your server, leading to a sluggish and unresponsive application experience.
Let’s explore an architecture that can improve the performance of app cards for a global customer base. While this approach may not necessarily fit into your application’s existing architecture, it may help point out how you may want to tackle this problem.
Fig 1: If the developer server is stationed in Florida (eastern United States), then hubspot.fetch() requests from customers in other parts of the world will experience high round-trip time.
UI Extension Architecture
At their core, HubSpot UI Extensions leverage React to build rich user interfaces, known as App Cards, that integrate directly into the HubSpot platform. A critical component of these App Cards is the hubspot.fetch() interface. This function enables the front-end React code to communicate with your backend systems, retrieving and displaying dynamic data within the HubSpot interface.
As illustrated in Fig 1, HubSpot's infrastructure is strategically distributed across five regions. When a user interacts with your App Card, particularly by triggering an action that initiates a hubspot.fetch() request, that request travels from the user's browser through the nearest HubSpot server and then onward to your backend infrastructure. Imagine a user in Australia interacting with your App Card while your backend servers are exclusively located in Florida—the data has a long way to travel!
As HubSpot continues to expand its global footprint, the potential for increased latency becomes more pronounced for users of App Cards in newly supported regions. Therefore, optimizing the backend infrastructure to minimize these delays is crucial for ensuring a responsive and satisfying user experience.
Fig 2: A hubspot.fetch() request travels from the customer portal to the developer servers via the closest Hubspot servers.
It's important to emphasize that every product and its infrastructure are unique. We’ll explore a potential backend infrastructure strategy designed to mitigate latency for end users. The strategy presented here is a demonstration of one possible approach. You must carefully evaluate specific requirements and consider your existing architecture to determine the most effective solution for your application.
Optimizing Performance with Multi-Region Architecture
For high-traffic applications, minimizing latency and maximizing responsiveness requires deploying compute and data resources geographically closer to users. A multi-region architecture achieves this by distributing resources across various locations, enhancing both speed and redundancy.
While this approach becomes impactful as user volume grows and performance issues arise, it's crucial to assess whether the benefits outweigh these challenges for your application. Implementing a multi-region architecture introduces significant complexities, including increased operational overhead, higher development and infrastructure costs.
The guide below demonstrates a multi-region strategy using MongoDB Atlas for data distribution and Vercel for compute deployment. MongoDB Atlas's global clusters and location-based sharding keep data region-specific, reducing cross-region latency. Vercel functions are deployed across multiple regions, ensuring the nearest instance handles API requests.
This setup delivers low-latency, high-performance applications which are crucial for global operations demanding speed and reliability. Let’s dive into the details!
Example App: A Multi-Region Restaurant Search API
Here's what you'll need to build an API that helps users find the nearest restaurants worldwide:
Key Components
- Vercel Edge Functions: Our application will leverage Vercel for its API layer, taking advantage of serverless edge functions for low-latency computing worldwide. Vercel functions provide on-demand execution and automatic scaling for our backend logic while executing code at the network's edge closer to users – significantly reducing the distance data travels. Regions supported by Vercel are listed here.
- MongoDB Atlas Global Cluster: We will store our restaurant data in MongoDB Atlas, a fully-managed cloud database service from MongoDB that provides scalability, security, and high availability. Specifically, we leverage Atlas's Global Clusters feature. Global Clusters enable us to distribute our data across multiple geographic regions, placing data closer to users for lower latency and facilitating data localization for compliance purposes. This distribution is achieved by partitioning data across shards, which are essentially horizontal slices of our database residing in different cloud provider regions.
In this application, we will set up our Global Cluster using Atlas-Managed Sharding by dividing our data into two geographic zones, with one shard per zone. The us-east-1 zone stores restaurant data for North and South America, while the eu-central-1 zone manages data for all other regions.
For each shard, Atlas creates a location field (that only holds ISO country codes) in the compound shard key so that Atlas can distribute data to shards based on geographic location. We can also specify a secondary shard key, which in our case is postalCode.
MongoDB Atlas’s flexible configuration options allow developers to adjust the number of zones, define how locations map to these zones, and specify the number of shards per zone. This tailored approach to data distribution, combined with Vercel’s dynamic API capabilities, ensures a fast and responsive experience for our global user base.
Architecture Overview
Fig 4: Globally distributed architecture to minimize end user latency and ensure data localization
Let’s assume that the user initiates a search on a HubSpot App Card by choosing the country and postal code. This input triggers a hubspot.fetch() request, which begins its journey through Hubspot’s globally distributed architecture.
- HubSpot Infrastructure: The request is first routed to the nearest HubSpot data center, one of five strategically located worldwide. This ensures minimal latency within the HubSpot ecosystem.
- Routing to Vercel: The request is then forwarded from the HubSpot data center to our Vercel-hosted backend. Vercel's edge network intelligently routes the request to the nearest region where our functions are deployed. This routing is based on the request's origin and Vercel's internal routing algorithms, minimizing latency between HubSpot and your backend.
- MongoDB Client: The Edge Function uses a MongoDB client to connect to the MongoDB Atlas cluster. When the Edge Function executes a query, it includes the shard key fields (location and postalCode). MongoDB Atlas's routing layer (mongos) automatically directs the query to the appropriate shard(s) based on the provided shard key values, ensuring efficient data retrieval.
- Response Delivery: The Edge Function sends the response back through Vercel’s network, ultimately returning it to the user with minimal round-trip time.
Setup Guide: MongoDB Atlas & Vercel Edge Functions
This section breaks down the key steps for establishing a robust global infrastructure by setting up a MongoDB Atlas cluster and deploying Vercel Edge Functions. These guides are designed to help you:
Click the links above for detailed, step-by-step instructions on setting up each component and integrating them seamlessly.
You can now use the URL of your Vercel Edge functions in the hubspot.fetch() calls your UI Extensions to build high performance app cards on Hubspot. The best part, as you might have guessed, is that end users get to connect with the closest Serverless Function on Vercel, which internally connects with the closest MongoDB shard containing the data - all with very little code.
Note: Both MongoDB Atlas and Vercel Edge Functions are paid, usage-based services. Review their pricing models and consider your budget as costs vary based on usage, region, and configuration.
Bonus - Leveraging Customer’s Data Hosting Location
HubSpot UI Extensions now also contain the dataHostingLocation attribute in the context object (link), passed to the extension component via hubspot.extend(). This attribute will indicate the data center assigned to a customer. Here are the values of dataHostingLocation as of today and the regions they correspond to:
- na1 - United States (East) - Virginia
- na2 - United States (West) - Oregon
- na3 - Canada - Montreal
- ap1 - Australia - Sydney
- eu1 - European Union - Germany
You can also use this to optimize hubspot.fetch() routing, ensuring data residency compliance and directing requests to region-specific backends when edge routing is inadequate.
Putting It All Together
Building HubSpot App Cards that deliver a consistently fast and responsive experience for a global audience requires careful consideration of your backend architecture. While starting with a single-region setup is perfectly acceptable for many applications, understanding the principles of multi-region deployments is crucial as your user base expands and performance becomes paramount.
Key Takeaways
- Hubspot has a regional infrastructure with data centers in 5 regions (as of today) intended to improve our customers' performance and advance their local data compliance objectives.
- Starting simple is often the best approach but as your app scales, developers building App Cards must consider their global customer base when designing their infrastructure.
- Cloud services like MongoDB Atlas and Vercel can make it easier to host regionally distributed and isolated compute and data storage.
- HubSpot UI Extensions now contain the dataHostingLocation attribute in the context object which can help you route hubspot.fetch() requests to region-specific backends.