Skip to main content

Key Concepts

Data Models​

The data models in High Velocity are key to the vendor-agnostic approach. The outputs of integrations are normalized to vendor-agnostic data models.

These data models are typescript types and zod schemas. Integration code is responsible for normalizing vendor specific outputs to objects that implement the data model schemas. These data models can be freely modified for particular requirements.

Server Centric​

For the main integration types, Commerce, CMS, OMS, Customer Profile, etc., the browser does not talk to vendors directly. Integration code is server-to-server and belongs in server components or route handlers. We also try to keep components as server components as much as possible, adding "use client"; only at the edges of the React app with interactivity.

Config and Secrets​

@hv/config

Configs are things like api tokens, active locales, and api endpoint urls. Any value that a developer may need to configure and may vary by deployment or locale. Configuration is treated as just another integration type. All configurations are fetched with an await so you can plug in an external service to provide values, such as AWS/GCP Secret Manager or Vercel Edge Config.

Out of the box, config values are pulled from environment variables with the help of the @hv/environment-variables-config package.

Feature Flags​

@hv/feature

This is closely related to configs, but features are intended to toggle functionality and are accessible by merchandisers. You can plug in your own provider for feature flags.

The @hv/feature-vercel package exposes feature flags to the Vercel toolbar.

Server Context​

You will see an object called serverContext of type DynamicServerContext or ServerContext pretty frequently in the codebase.

Server context is an object that stores all runtime variables that may impact the customer experience. It contains things like the current locale or the current customer.

This context is a dependency of all of the integration constructor functions: Config, Cart, Catalog, Search, etc. This allows these integrations to have different behaviors and configurations depending on the context.