Convex Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Convex deployment serves as the platform's centralized data and content layer. It encompasses the database schema, table definitions, and server functions utilized by the application suite. All persistent data in the Nordcom Commerce ecosystem is stored within this deployment, which is managed primarily through the @nordcom/commerce-convex package.
Sources: packages/convex/README.md:1-4, README.md:21-25
System Architecture
The deployment architecture is structured around a central Convex backend that interacts with multiple applications and packages. Apps do not import functions directly; instead, they interface through the service seam in @nordcom/commerce-db or storefront CMS getters.
The diagram above illustrates the interaction between frontend applications, utility packages, and the core Convex deployment.
Sources: packages/convex/README.md:6-10, packages/cms/README.md:103-107
Trusted Function Tiers
Public functions within the Convex deployment are categorized into four distinct "Trust Tiers" using specific constructors. These tiers enforce authorization and tenant-scoping at the database level.
| Tier | Constructor | Purpose |
|---|---|---|
| Tenant | tenantQuery / tenantMutation | Requires a validated end-user identity (JWT) and resolves shop membership. |
| Authed | authedQuery / authedMutation | Requires validated identity but no specific shop membership (e.g., customer profiles). |
| Server | serverQuery / serverMutation | Admits identity-less callers with a CONVEX_SERVER_SECRET (used by middleware). |
| System | systemQuery / systemMutation | Internal surfaces and cron jobs. |
Sources: packages/convex/README.md:27-40
Content Management Integration
The CMS content is deeply integrated with Convex, utilizing a multi-tenant schema where every table keys on the shop's unique ID. Content shapes are defined by field descriptors in the CMS package, which are used to auto-generate Convex table validators.
Schema Generation Flow
The deployment relies on a code-generation pipeline to ensure the storage schema remains in sync with CMS definitions.
Deployment Environments
The project supports three primary deployment modes: Production/Cloud, Local Development, and Ephemeral/Test.
1. Production/Cloud Deployment
Production environments are managed via the Convex CLI and require a CONVEX_DEPLOY_KEY in CI/CD environments.
Sources: packages/convex/README.md:52-53
2. Local Development
Developers utilize a persistent anonymous backend stored in .convex-local/. This is booted and seeded automatically using pnpm dev or pnpm convex:local.
Sources: README.md:46-52
3. Ephemeral/Test Backends
Integration tests utilize @nordcom/commerce-test-convex to launch temporary backends.
- startConvex(): Boots a real local backend and returns a URL and admin key.
- convex-test: Used for in-memory unit testing without a full backend.
Sources: packages/test-convex/README.md:10-18, packages/convex/README.md:65-68
Environment Configuration
A successful deployment requires several environment variables to be configured on the Convex dashboard or local instance.
| Variable | Scope | Description |
|---|---|---|
CONVEX_AUTH_ISSUER | Auth | The JWT issuer for identity validation. |
CONVEX_SERVER_SECRET | Trust | Secret for internal server-to-server queries. |
CONVEX_REVALIDATE_SECRET | Cache | HMAC key for signing revalidation events sent to the storefront. |
CONVEX_DEPLOY_KEY | Deployment | Used by CI to authorize production deployments. |
Sources: packages/convex/README.md:58-61, packages/convex/package.json:28-29
Core Scripts and Management
Primary interaction with the deployment is handled via the following workspace commands:
# Deploy to the configured production/cloud environment
pnpm convex:deploy
# Start local development backend with push
pnpm convex:dev
# Manage deployment environment variables
pnpm convex:env
# Refresh generated types and function references
pnpm --filter @nordcom/commerce-convex codegen
Sources: packages/convex/README.md:52-56, packages/convex/package.json:27-31
Conclusion
Convex Deployment is the backbone of the Nordcom Commerce data architecture, providing a type-safe, multi-tenant environment for both application state and CMS content. By leveraging trust tiers and automated schema generation, it ensures strict data isolation and consistency across the platform.