Key Concepts
Data Models
The data models in High Velocity are key to the vendor neutral approach. The outputs of integrations are normalized to vendor neutral 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 things as server
components as much as possible and adding "use client";
only at 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
plugin 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 plugin 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 the all of the integration constructor functions: Config
, Cart
, Catalog
, Search
, etc.
This allows these integrations do have different behaviors and configurations depending on the context.