DB Service Abstraction

The DB Service Abstraction within the Nordcom Commerce platform provides a type-safe service layer over the Convex backend. Located primarily in the @nordcom/commerce-db package, this abstraction manages data for core entities such as shops, users, sessions, and identities. It acts as the authoritative boundary for data access and modification, ensuring that sensitive information—such as provider tokens—is handled securely and never exposed to client-side components.

This architectural layer is designed to support a multi-tenant environment where a single deployment serves multiple shops. It resolves tenants by hostname and provides explicit context for every downstream data call. By abstracting the Convex database functions into a service layer, the platform maintains a clean separation between the storage schema and the application logic used by the Storefront and Admin applications.
Sources: README.md:12-25, CONTEXT.md:1-5, packages/db/package.json

Architecture and Multi-tenancy

The database abstraction is built to handle multi-tenancy at the edge. The system uses middleware to resolve the request hostname to a specific Shop record. Once a shop is identified, all subsequent data-fetching operations must carry an explicit { shop, locale } context to prevent cross-tenant data leakage.

Tenant Resolution Flow

The following diagram illustrates how the DB service abstraction assists in resolving a tenant from an incoming request.

The middleware normalizes the host header and utilizes the Shop service to find the corresponding tenant. If the shop exists, the URL is rewritten to include the domain and locale, ensuring the App Router operates within the correct tenant context.
Sources: README.md:144-155, CONTEXT.md:7-20

Core Service Components

The @nordcom/commerce-db package organizes its logic into services and models. Key entities managed by this layer include:

Shop Entity and Security

The Shop service is the authoritative path for all shop-related writes, primarily through the db/shop_write:upsertShop mutation. A critical feature of this abstraction is the projection of sensitive data. Sensitive fields, such as Provider Tokens and collaborator lists, are omitted by default. Accessing these requires an explicit { sensitiveData: true } flag, which is restricted to server-side execution.

// Example of server-side sensitive data access
import { Shop } from '@nordcom/commerce-db';

const shop = await Shop.findByDomain(hostname, { sensitiveData: true });
// tokens are now available but must not be passed to Client Components

Sources: apps/admin/README.md:104-110, CONTEXT.md:32-38, CONTEXT.md:144-150

Data Model and Schema Synchronization

The DB abstraction is tightly coupled with the CMS through shared descriptors. These descriptors generate Convex table validators, ensuring that the editor, the database schema, and the read contracts remain synchronized without manual intervention.

Entity Relationship Diagram

The following ER diagram represents the high-level relationships managed by the DB service layer.

A Shop is the central unit of tenancy, linked to domains, commerce providers (like Shopify), and collaborators. CMS content rows are keyed directly to the Shop's unique ID.
Sources: CONTEXT.md:124-135, packages/cms/README.md:14-25

Caching Strategy

The DB service abstraction supports a tenant-scoped and locale-qualified caching strategy. Every entity's cache tags include a Shop key, ensuring that revalidating data for one tenant never affects another.

• Cache Namespaces: The system distinguishes between different systems using namespaces like shopify and cms.
• Tag Structure: Tags follow a strict hierarchy: cms.<shopId>.<collection>.<key>.
• Invalidation: The Convex revalidation pipeline computes these tags and delivers revalidation events to the storefront.

Sources: CONTEXT.md:46-56, packages/cms/README.md:74-85

Conclusion

The DB Service Abstraction is fundamental to Nordcom Commerce's multi-tenant architecture. By centralizing Convex interactions within the @nordcom/commerce-db package, the platform ensures strict type safety, enforces security boundaries for sensitive credentials, and provides a scalable way to manage tenant-specific data across the Storefront and Admin applications. This layer guarantees that shop data is correctly isolated and efficiently cached, enabling the platform to serve many tenants from a single deployment.
Sources: README.md:12-25, CONTEXT.md:1-10