Introduction
Relevant source files
The following files were used as context for generating this wiki page:
Nordcom Commerce is a production-grade, multi-tenant headless e-commerce platform designed to serve multiple shops from a single deployment. Built with a modern TypeScript stack including Next.js 16 and React 19, it integrates Shopify as a commerce backend and Convex as a serverless data and content layer. The system is architected to handle multi-tenancy at the edge, resolving tenants by hostname and routing requests to isolated tenant contexts.
The platform is composed of three primary applications: a high-performance Storefront for end customers, an Admin dashboard for merchant operations, and a Landing site for marketing and documentation. These apps are supported by a suite of shared packages that handle core concerns such as database access, CMS logic, and a unified error hierarchy.
Sources: README.md:1-20, CONTEXT.md:3-5
Core Architecture
The architecture relies on a "Multi-tenant by hostname" model. A single deployment serves arbitrarily many shops, where adding a new tenant is a matter of a database row rather than a code deployment. Tenant context is explicitly passed through every data-fetching and service call.
High-Level System Overview
The diagram shows how inbound requests are resolved into specific tenant contexts before interacting with the core applications and external backends.
Sources: CLAUDE.md:73-80, README.md:22-26
Multi-Tenant Resolution
Tenant resolution occurs in the Next.js middleware. The middleware normalizes the host header and queries the Convex database to find the corresponding shop record. On success, it rewrites the URL to include a /[domain]/[locale] prefix, ensuring the App Router operates within the correct shop context.
| Step | Action | Description |
|---|---|---|
| 1 | Extract Hostname | Strips ports, .localhost, and Vercel preview suffixes from the Host header. |
| 2 | Resolve Tenant | Calls Shop.findByDomain(hostname) against Convex. |
| 3 | Rewrite URL | Rewrites to /[domain]/[locale]/... for internal routing. |
| 4 | Fallback | If not found, rewrites to SERVICE_DOMAIN/status/unknown-shop/. |
Sources: README.md:129-140, CONTEXT.md:11-18, apps/storefront/README.md:31-40
Application Suite
Storefront
The Storefront is the public-facing surface serving end customers. It utilizes the Shopify Storefront API for catalog, cart, and checkout functionalities. Content is driven by the Convex-native CMS, which allows for descriptor-defined pages and blocks.
- Path:
apps/storefront - Routing: All routes are nested under
src/app/[domain]/[locale]/. - Caching: Implements per-tenant, per-entity cache tags (e.g.,
shopify.<shopId>.product.<handle>) for surgical revalidation.
Sources: apps/storefront/README.md:1-25, apps/storefront/README.md:76-80
Admin
The Admin app is the operator dashboard where shop owners configure integrations, manage products, and author content. It hosts the embedded CMS editor at /cms.
- Path:
apps/admin - Auth: Uses Clerk for operator sign-in, which then mints a Convex token for database access.
- Integrations: Handles the Shopify Admin API OAuth handshake and provides an embeddable surface for the Shopify admin.
Sources: apps/admin/README.md:1-15, apps/admin/README.md:118-121
Landing
The Landing app serves the public marketing site and documentation. Unlike the other apps, it has no direct database connection and relies on Markdoc for long-form content.
- Path:
apps/landing - Content: Driven by Markdoc files located in
src/app/(marketing)/docs/. - Status Pages: Hosts global status pages like
/status/unknown-shop/.
Sources: apps/landing/README.md:1-15, apps/landing/README.md:52-58
Data and Content Layer
Convex Backend
Convex serves as the unified data layer, housing shops, users, and CMS content. The @nordcom/commerce-db package provides a typed service layer over Convex.
The ER diagram illustrates the relationship between a Shop and its associated domains, collaborators, and content documents.
Sources: CONTEXT.md:11-23, CONTEXT.md:144-150, README.md:75-80
CMS Architecture
The CMS is "multi-tenant by construction." Field descriptors define content shapes and generate Convex table validators, ensuring the editor and storefront remain in sync.
- Block Renderer: A tenant-aware dispatcher in the storefront that renders structured block trees.
- Block Loaders: Shopify-aware data fetchers injected at the storefront boundary to keep the core CMS package Shopify-free.
- Setting Cascade: A resolution logic for component settings:
platform default -> store-wide default -> per-surface override -> per-instance override.
Sources: packages/cms/README.md:1-30, CONTEXT.md:68-85, CONTEXT.md:105-115
Development Toolchain
The project uses a strict, unified toolchain managed via pnpm workspaces and turbo.
| Tool | Purpose |
|---|---|
| Biome | Sole tool for linting and formatting (replaces ESLint/Prettier). |
| Turborepo | Build system and task runner. |
| Portless | Local proxy for handling .localhost domains and HTTPS. |
| Vitest | Unit and integration testing. |
| Playwright | End-to-end testing for critical flows. |
Sources: CLAUDE.md:5-20, README.md:100-112
Summary
Nordcom Commerce provides a robust foundation for building scalable, headless storefronts. By centralizing multi-tenancy logic in the middleware and providing a unified CMS and data layer through Convex, it minimizes the operational overhead of managing multiple e-commerce instances while maintaining high performance and developer productivity through its modern toolchain.
Sources: README.md:1-10, CONTEXT.md:3-5