Foundation Service — Glossary

Platform: Infosys Equinox | Key terms and concepts

Term Definition
instanceId The top-level tenant identifier for a SaaS subscription on the Equinox platform. Every API request must carry an instanceId in the JWT or header. All data in every collection is filtered by instanceId at the repository layer to prevent cross-tenant data access.
businessId Numeric unique identifier for a Business entity — the merchant organisation (tenant root). All stores, sites, and sellers belong to exactly one business. Must exist in Foundation before any store can be created.
storeId Numeric unique identifier for a Store. This is the primary data scope for every other Equinox service — products, orders, inventory, and users are all associated with a storeId.
hierarchyPath Ordered array of storeId numbers from the root store to a given store: [root, ..., parent, this.storeId]. Built and maintained automatically by the service when stores are created or re-parented. Used by the effective-config resolver to fetch all ancestors in a single MongoDB $in query.
hierarchyLevel Integer 0–3 indicating a store’s depth in the hierarchy. Level 0 = root (no parent). Level 3 = leaf (cannot have children). Enforced by the service — creating a level-4 store throws MAX_HIERARCHY_DEPTH_EXCEEDED.
effective-config The merged property set for a store, resolved by walking its full ancestor chain. Root store properties are lowest priority; the leaf store’s own properties are highest priority. The result is Redis-cached and recalculated whenever any ancestor is mutated.
parentStoreId The storeId of the immediate parent store. null for root stores at level 0. Setting this field places the store in the hierarchy and triggers hierarchyPath and hierarchyLevel recalculation.
properties A free-form key-value map on businesses, stores, templates, and locations. On stores, this map participates in hierarchy inheritance — child stores inherit all parent property keys and can override individual values without affecting siblings.
serviceProperties Structured array on a store: [{ serviceName, propertyName, value }]. Consumed by other Equinox services (PIM, OMS, etc.) to look up service-specific config for a store. Does NOT participate in hierarchy inheritance — each store must set its own values.
adminAuthHook A Fastify preHandler (src/hooks/AdminAuthHook.ts) attached to routes that need protection. It relies on the shared JWT plugin to validate the Bearer token, then checks that the required privilege string is present in the token’s claims. Returns 401 for invalid/expired tokens and 403 for missing privileges. (Some routes currently ship with it commented out.)
FOUNDATION_USE_INMEMORY Environment variable. When true, swaps in an in-memory Mongo/cache/event-publisher stack (src/infrastructure/inmemory/*). No external services are needed. Data is lost on restart. Local development and tests only.
STAGE Environment variable identifying the deployment stage (dev, staging, prod, test, …). Drives the DB name (foundationdb_<STAGE>), event-publish gating (events publish when STAGE !== 'test'), and serverless URL prefixing.
ENABLE_EVENT_PUBLISHING Environment variable that gates only the legacy stub event publisher (eventPublisher.util.ts). It does not control the live event path (which is gated by STAGE). There is no ENABLE_EVENT_BRIDGE variable.
pluginConfig Per-instance configuration (under instanceContext.properties.pluginConfig) that declares which validator and lifecycle extensions to load and how (package/file/S3 source, route scoping, remote-app URL). See 14-extensions-and-lifecycle.md.
instanceContext The resolved per-request tenant context (instance properties including pluginConfig). Used to decide which extensions run for the current instance.
getExtensions() The @equinox/plugin-registry call (`getExtensions(‘storeValidator’ \
ALLOWED_PLUGIN_PACKAGES / _FILE_PREFIXES / _S3_BUCKETS Allowlist environment variables that restrict where extension code may be loaded from (npm package name, local/EFS file prefix, S3 bucket). A safety guard on the extension framework.
collectionId The field carried on domain events (= the owning businessId). Domain events use collectionId, not instanceId; only batch events carry instanceId.
DEFAULT_PAGINATION Shared list-endpoint defaults (src/utils/constants.ts): PAGE=1, LIMIT=10, MAX_LIMIT=100. Requests exceeding MAX_LIMIT are capped.
ship-from-store (SFS) Boolean flag (shipFromStore) on a Location document. When true, this location is eligible to fulfil online orders by shipping from its local stock. The inventory service uses this flag and the location’s coordinates when routing stock reservations to the nearest eligible location.
BOPIS Buy Online, Pick Up In Store — a fulfilment capability tag on a Location. When present in the capabilities array, the storefront displays this location as a customer pickup option during checkout.
batch A named ETL pipeline container grouping related jobs together. A Batch does not execute on its own — execution is done by individual jobs within it.
batchJob A specific ETL operation within a Batch. Defines the processing Lambda ARN, input schema, and action step sequence (validate → parse → process → finalize).
batchSchedule A trigger configuration for a batch job. Type SCHEDULED creates an AWS EventBridge cron rule that fires the job automatically. Type ONDEMAND requires manual triggering via the API.
batchHistory An execution record created for each individual batch job run. Tracks lifecycle status (PENDING → RUNNING → COMPLETED or FAILED), progress percentage, timing metrics, and error messages.
runRequestId A unique ID generated for each individual batch job execution. The processing Lambda uses this ID to callback progress and status to Foundation’s history endpoints.
fastify.publishEvent() The live event-publish path — a decorator added by the @equinox/event-bridge-implementation plugin (source foundation-service). Service code calls it with { type, subject, data }. See 04-events.md.
EventBridgeEventPublisher A legacy/stub publisher class (src/utils/eventPublisher.ts) with publishCreated/publishUpdated/publishDeleted. It has no live call sites and is not the path events actually take — do not rely on it or its entityType/eventType/beforeState envelope.
Master Data Read-only reference collections in Foundation: currencies, locales, timezones, countries, store_types. Seeded during platform deployment and never mutated via the API. All services validate their configuration values against these collections before saving.
soft-delete The deletion pattern used by all Foundation delete endpoints. Instead of removing the MongoDB document, the status field is set to inactive (or a deletedAt timestamp is added). The record remains in the database and is excluded from active-only queries. Use the GDPR endpoints for permanent deletion.
effective-config cache key Redis is keyed by effectiveConfig:<storeId>. Invalidated automatically on any mutation to that store or any of its ancestors. When Redis is unavailable, the service falls back to MongoDB — data is never wrong, only slower to retrieve.
serviceProperty A named global configuration entry registered via /v1/service-properties. Other Equinox services read these at runtime to get instance-level configuration without needing their own environment variables for tenant-specific settings.
Site An online storefront entity representing a web domain (e.g. shop.acme.com). A Site is linked to a Store. In a marketplace, multiple Sellers operate under the same Site.
Seller A marketplace vendor profile linked to a Store (the seller’s fulfilment unit) and optionally a Site (the marketplace they list on). Used in multi-vendor marketplace scenarios.
Store Association A relationship record between two stores — e.g. a fulfilment partnership where Store A can ship on behalf of Store B. Associations carry their own properties for relationship-specific configuration.


Revision History
2026-08-04 | AN – Page created and uploaded the contents