AI Design Documenter
Relevant source files
The following files were used as context for generating this wiki page:
- CLAUDE.md
- packages/cms/README.md
- apps/admin/e2e/pages-editor.spec.ts
- apps/admin/e2e/header-editor.spec.ts
- packages/cms/src/editor/ui/editor-fields.test.tsx
- apps/landing/src/app/(marketing)/news/[year]/[month]/[slug]/articles.ts/news/%5Byear%5D/%5Bmonth%5D/%5Bslug%5D/articles.ts)
The AI Design Documenter within the Commerce project refers to the systematic framework of guidelines, specifications, and automated tools used to document and maintain the architectural integrity of the multi-tenant headless commerce platform. It encompasses toolchain corrections for AI agents, standardized design document locations, and a descriptor-driven codegen system that ensures synchronization between CMS schemas, admin editors, and storefront types.
This system is primarily managed through the CLAUDE.md orchestration file and the @nordcom/commerce-cms package, which serves as the "source of truth" for content structures. By enforcing strict patterns for Git Commits and Architecture, the project maintains a self-documenting codebase optimized for both human developers and AI agents.
Sources: CLAUDE.md:1-55, packages/cms/README.md:1-25
Architecture and System Guidelines
The project architecture relies on a multi-tenant, hostname-based resolution system where tenant context is never implicit. This structure is documented and enforced through specific agent instructions to prevent architectural drift during automated or manual updates.
Core Architectural Principles
- Multi-tenancy: Resolved by middleware (hostname → shop), rewriting requests to
/[domain]/[locale]/.... - Tenant Context: Explicitly passed to all data-fetching helpers (e.g.,
ShopifyApolloApiClient({ shop, locale })). - CMS Data Flow: Driven by descriptors that generate Convex validators and TypeScript types.
The following diagram illustrates the high-level request flow and tenant resolution:
The diagram shows how requests are tenanted before reaching the App Router logic.
Sources: CLAUDE.md:95-108, packages/cms/README.md:27-40
Spec and Plan Management
A critical component of the documentation system is the management of design specifications and implementation plans. The project enforces a strict path-based organization for all technical artifacts to ensure historical context is preserved alongside the code.
Artifact Organization
All implementation specs, plans, and tasks are grouped by topic and date. These must be committed to the feature branch to maintain a "living" history of design decisions.
| Artifact Type | Path Pattern | Purpose |
|---|---|---|
| Specification | .specs/<YYYY-MM-DD-slug>/spec.md | Defines the problem and proposed solution. |
| Implementation Plan | .specs/<YYYY-MM-DD-slug>/plan.md | Steps for executing the specification. |
| Task List | .specs/<YYYY-MM-DD-slug>/tasks.md | Granular checklist of work items. |
Sources: CLAUDE.md:75-85
Descriptor-Driven Codegen
The CMS module uses a descriptor-driven approach to document and generate the platform's content schema. This ensures that the documentation of a field (its descriptor) is the same code that generates its database validation and UI representation.
Codegen Artifacts
By running pnpm cms:gen, the system derives multiple downstream components from the source descriptors.
The diagram represents the transformation of field descriptors into functional code across different packages.
Sources: packages/cms/README.md:42-55, CLAUDE.md:46-50
Editor and Form Documentation
The authoring surface is documented through E2E specs and editor manifests. These files serve as technical documentation for how complex nested structures (like depth-6 navigation) are managed.
Navigation and Block Structure
The system supports deeply nested content structures, which are validated through Playwright E2E tests and Vitest integration tests.
- Header Nav: Supports up to 6 levels of nesting, with each level carrying editable properties like
backgroundColorand localizeddescription. - Blocks: Standardized set of 9 blocks (Alert, Banner, Collection, etc.) that can be nested within layout blocks like
Columns.
Sources: apps/admin/e2e/header-editor.spec.ts:35-55, apps/admin/e2e/pages-editor.spec.ts:25-45, packages/cms/src/editor/ui/editor-fields.test.tsx:135-155
Form State Lifecycle
The EditorFields component and associated hooks manage the transition of data from raw document state to a serialized form state.
Coding Conventions and Standards
The AI Design Documenter enforces specific coding standards that act as a technical constraint for all contributions.
- Linting & Formatting: Exclusively uses Biome. ESLint and Prettier are forbidden.
- Async Next.js APIs: In Next.js 16,
params,searchParams,cookies(), andheaders()must be treated as Promises. - Environment Gates: All environment-tier checks must go through
@nordcom/commerce-utils(e.g.,isProduction()) rather than rawprocess.env.NODE_ENVreads. - JSDoc: Required for every exported and internal function, including React components, detailing intent and contract.
Sources: CLAUDE.md:110-150, apps/landing/src/app/(marketing)/news/[year]/[month]/[slug]/articles.ts:40-60
Conclusion
The AI Design Documenter is not a single tool but a collection of strictly enforced patterns, codegen scripts, and structured metadata. By centralizing the content schema in descriptors and enforcing clear paths for design artifacts, the system ensures that the technical documentation remains as accurate as the implementation itself. This approach facilitates rapid iteration while preventing the architectural degradation common in complex, multi-tenant headless systems.