Admin Operator Dashboard
Relevant source files
The following files were used as context for generating this wiki page:
The Admin Operator Dashboard (@nordcom/commerce-admin) is a Next.js 16 application serving as the back-office surface for the Nordcom Commerce platform. It allows shop owners and operators to manage multi-tenant shops, configure integrations (primarily Shopify), and author content via a Convex-native CMS. The dashboard is designed to handle multiple tenants from a single deployment, where each shop is resolved by its domain segment.
Sources: apps/admin/README.md:1-10, README.md:11-15, CONTEXT.md:214-216
Architecture and Core Stack
The Admin application is built with a modern React 19 and Next.js 16 stack, utilizing the App Router and Turbopack for development. It relies on several core services for its functionality:
- Authentication: Managed by Clerk, where operators sign in and the server mints Convex tokens for database access.
- Data Layer: Uses
@nordcom/commerce-dbfor interacting with Convex-backed services for shops, users, and CMS documents. - Integrations: Uses
@shopify/shopify-apifor Admin API interactions and OAuth handshakes. - CMS: Integrates
@nordcom/commerce-cmsfor descriptor-defined content editing.
Data Flow Overview
The following diagram illustrates how the Admin app interacts with the data layer and external providers:
The Admin application acts as a central hub connecting authentication, commerce backends, and content storage.
Sources: apps/admin/README.md:12-23, CONTEXT.md:214-216
Routing and Tenancy
The dashboard uses Next.js route groups to organize functionality. Authentication is enforced via middleware (src/proxy.ts), redirecting unauthenticated requests to /auth/login/.
Route Structure
| Route Group | Purpose | Path Pattern |
|---|---|---|
(auth) | Sign-in and sign-out flows | /auth/* |
(dashboard) | Per-shop management (content, products, settings) | /[domain]/... |
(setup) | New-shop onboarding wizard | /new |
(user) | Personal account and profile settings | /accounts |
integrations | Shopify OAuth callbacks and embed surfaces | /integrations/shopify/* |
Sources: apps/admin/README.md:88-106
Tenant Resolution
The App Router utilizes the [domain] dynamic segment to scope requests to a specific shop. getAuthedCmsCtx(domain) is used to resolve the tenant context, ensuring operators only access data relevant to the specific shop domain.
Sources: apps/admin/src/app/(app)/(dashboard)/[domain]/content/page.tsx:109-112, CONTEXT.md:20-25
Content Management System (CMS) Editor
The Admin app hosts the native authoring stack for the CMS. Content is organized into "Globals" (singletons) and "Collections" (multiple entries).
Editor Logic and Components
The CMS editor utilizes editorConvexBridge to perform CRUD operations on documents stored in Convex. The EditorEditPage component is responsible for fetching documents, building form state, and rendering the field surface.
The sequence shows the transition from fetching document data to persisting a draft.
Sources: packages/cms/src/editor/ui/editor-edit-page.tsx:100-150, apps/admin/src/app/(app)/(dashboard)/[domain]/content/page.tsx:120-140
Key CMS Features
- Autosave: Implemented with a 2-second interval for draft-bearing collections (e.g., pages, articles).
- Versioning: Supports version restoration via a
/versions/route for every document. - Localization: Fields are edited within locale buckets. The editor redirects to the shop's
defaultLocaleif no locale is specified in the URL. - Metadata Overlays: Specific collections like
productMetadataandcollectionMetadataallow CMS content to be overlaid on Shopify entities using theshopifyHandle.
Sources: packages/cms/src/editor/ui/editor-edit-page.tsx:116-125, packages/cms/README.md:46-56, apps/admin/src/app/(app)/(dashboard)/[domain]/content/page.tsx:142-168
Configuration and Integration
Operators manage the "Customization Hub," which consolidates several configuration surfaces into a single interface.
Customization Hub Tabs
- Theme: Manages Theme Tokens (styling scalars like colors/spacing).
- Components: Configures Component Settings (behavioral defaults for ambient UI).
- Blocks: Sets store-wide defaults for editor-placeable blocks.
- Sections: Manages visibility and ordering of fixed page chrome (Header, Footer, Info-bar).
Sources: CONTEXT.md:143-160
Shopify Integration
The Admin API integration allows the platform to perform back-office operations. The integration is designed so that a single deployment can be embedded within any merchant's Shopify admin dashboard.
Sources: apps/admin/README.md:111-115
Technical Specifications
Environment Variables
The dashboard requires several environment variables for secure operation:
| Variable | Purpose |
|---|---|
CONVEX_AUTH_PRIVATE_KEY | RS256 key for signing Convex operator tokens. |
ADMIN_DOMAIN | Canonical hostname for the admin application. |
SHOPIFY_API_KEY | Credential for the Shopify Admin API integration. |
CLERK_SECRET_KEY | Authentication secret for Clerk. |
Sources: apps/admin/README.md:40-60
Performance and Reliability
- Edge Caching: Uses per-tenant and per-entity cache tags for surgical revalidation.
- E2E Coverage: Critical flows like Header/Footer editing and version restoration are covered by Playwright specs.
- Error Handling: Uses a typed error hierarchy from
@nordcom/commerce-errorsto provide stable error codes across the UI.
Sources: README.md:19-35, apps/admin/package.json:20-25
Summary
The Admin Operator Dashboard is the central management interface for the Nordcom Commerce platform. It provides a multi-tenant, domain-aware environment for merchants to configure their shops, integrate with Shopify, and manage rich content through a sophisticated CMS editor. Its architecture leverages Next.js 16 and Convex to ensure type-safety, surgical cache revalidation, and a seamless operator experience.