Code Health Assessment

Code Health Assessment

commerce

Generated by DocAgent — automated codebase documentation analysis. Based on analysis of 5 screens. Subject matter expert review is recommended before distribution.

April 20, 2026

Code Health Assessment

Application: commerce Document Title: Code Health Assessment Date: April 2026

1. Executive Summary

Generated by DocAgent — automated codebase documentation analysis. Subject matter expert review is recommended before distribution.

This assessment covers 5 screens of the commerce application. Overall, the codebase is rated Moderate Concern. The application demonstrates a strong architectural foundation: it is built on Next.js 15 App Router with React Server Components used consistently and correctly, TypeScript strict mode is enabled throughout, and the Shopify integration is cleanly abstracted behind a lib/shopify service layer. The deliberate use of streaming SSR via Suspense boundaries on the Product Detail screen and the server-side-only handling of API credentials reflect sound engineering judgment.

The three highest-risk findings are: [CH-003] Unguarded featuredImage Property Access in JSON-LD — a null dereference that will throw a runtime error for any Shopify product without a featured image, causing a 500 response on the primary conversion page; [CH-002] dangerouslySetInnerHTML JSON-LD Without </script> Escape Hardening — a known XSS vector on the Product Detail page where JSON.stringify does not neutralize </script> sequences embedded in Shopify-sourced data; and [CH-001] Duplicate Shopify API Calls Across generateMetadata and Page Components — a cross-cutting pattern affecting three screens where the same data is fetched twice per request, doubling Shopify API load and increasing latency when fetch deduplication is not guaranteed.

The assessment is based entirely on per-screen technical documentation. No static analysis tools, runtime profiling, test coverage measurement, or direct source code access was used. Findings marked "(based on documentation — verify with static analysis)" require tooling confirmation before acting. See the Finding Inventory for the complete catalog of findings by severity.

2. Assessment Methodology

Quality Model

Findings are classified against ISO/IEC 25010:2023 quality characteristics: Maintainability, Reliability, Security, Performance Efficiency, Functional Suitability, Usability, Compatibility, and Portability.

Debt Classification

Technical debt is classified using the SQALE method: Design Debt, Code Debt, Test Debt, Doc Debt, and Dependency Debt.

Severity Model

Aligned with SonarQube's quality model:

Scope

This assessment covers 5 screens of the commerce application:

• Home (/)

• Item Detail (/[page])

• Product Detail (/product/[handle])

• Search (/search)

• Search Detail (/search/[collection])

Screens, features, and components not included in the assessed documentation are outside the scope of this document. Specifically, the lib/shopify service layer, shared components (ThreeItemGrid, Carousel, Gallery, ProductDescription, ProductGridItems, Grid, Footer, Prose, GridTileImage, CartProvider, Navbar, WelcomeToast), cart/checkout flows, and account management screens are not assessed here.

Limitations

• All findings are derived from per-screen technical documentation, not from automated static analysis, runtime profiling, or direct source code inspection.

• Cyclomatic complexity, lines of code, test coverage percentages, and bundle size metrics cannot be measured from documentation alone.

• Git history (churn rate, contributor patterns, commit frequency) is unavailable.

• Findings about shared components and the lib/shopify service layer are inferred from how they are described in screen documentation and are placed in the Needs Verification section.

3. Quality Scorecard

4. Detailed Findings by Quality Dimension

[Diagram: Component dependency graph showing the five assessed page components, their shared child components (ThreeItemGrid, Carousel, Gallery, ProductDescription, ProductGridItems, Grid, Footer, Prose), and the lib/shopify service layer — illustrating the layered architecture and the points where duplicate API calls occur.]

4.1 Maintainability (Score: 4/5)

Overview

The codebase follows the Next.js App Router convention of thin page components that delegate data fetching and rendering to child components. TypeScript strict mode (strict: true, noUncheckedIndexedAccess: true) is enabled, which significantly reduces the surface area for type-related bugs. The primary maintainability concern is a cross-cutting pattern of duplicate API calls that affects three screens and would be resolved by a single shared utility.

CH-001: Duplicate Shopify API Calls Across generateMetadata and Page Components

Severity: Major Quality Sub-Characteristic: Reusability Screen(s): Item Detail (/[page]), Product Detail (/product/[handle]), Search Detail (/search/[collection]) Component(s): generateMetadata and page component functions in app/[page]/page.tsx, app/product/[handle]/page.tsx, app/search/[collection]/page.tsx

Description: On three screens, the same Shopify API fetch function is called independently in both generateMetadata and the page component body for the same request. This pattern doubles the number of outbound Shopify API calls per page render unless Next.js's fetch deduplication layer coalesces them. Deduplication is not guaranteed — it depends on whether lib/shopify uses the native fetch API with identical URL and options, and whether cache: 'no-store' is set anywhere in the call chain. The team has documented this as a known issue on two of the three affected screens.

Evidence:

• Item Detail (/[page]): "Both generateMetadata and the Page component independently call getPage(params.page)... this results in two identical Shopify API requests per page render" (§17)

• Product Detail (/product/[handle]): "getProduct(params.handle) is called independently in both generateMetadata and ProductPage for the same handle on the same request" (§17)

• Search Detail (/search/[collection]): getCollection(params.collection) is called in generateMetadata and the collection slug is also used in getCollectionProducts in the page body (§5)

Risk: Each affected page render may issue two Shopify Storefront API calls instead of one. Shopify's Storefront API enforces rate limits; under load, doubling the call rate increases the probability of hitting rate limits, which would cause 429 errors and degrade page availability. Additionally, each extra round-trip adds latency to the server render.

Recommendation:

• Wrap each data-fetching function (getPage, getProduct, getCollection) with React.cache() in lib/shopify or in a per-route cache module. React.cache() guarantees request-level memoization regardless of fetch configuration:

// lib/shopify.ts (or a per-route cache wrapper)
import { cache } from 'react';

export const getProduct = cache(async (handle: string) => {
// existing implementation
});

• Apply the same pattern to getPage and getCollection.

• After applying React.cache(), verify with Shopify API request logs that only one call per handle is made per page render.

Effort: Low (< 1 hour per function; 3 functions total)

SQALE Characteristic: Maintainability

Source Evidence: Item Detail (/[page]), Product Detail (/product/[handle]), Search Detail (/search/[collection])

CH-010: Unsafe searchParams Type Cast Suppresses Runtime Safety

Severity: Major Quality Sub-Characteristic: Analysability Screen(s): Search (/search), Search Detail (/search/[collection]) Component(s): app/search/page.tsx, app/search/[collection]/page.tsx

Description: Both search screens cast searchParams using as { [key: string]: string }, which suppresses TypeScript's awareness that query parameter values can be string | string[] | undefined. This means the sort and q values passed downstream to getProducts and getCollectionProducts may be string[] or undefined at runtime without any type error being raised. The team has documented this as a known issue on both screens.

Evidence:

• Search (/search) §17: "The line const { sort, q: searchValue } = searchParams as { [key: string]: string } uses a broad type cast that suppresses TypeScript's awareness of undefined and string[] values."

• Search Detail (/search/[collection]) §17: "The line const { sort } = searchParams as { [key: string]: string } performs an unchecked cast."

Risk: A URL with duplicate parameters (e.g., ?sort=price-asc&sort=trending) passes a string[] to getProducts or getCollectionProducts. If those functions do not guard against array inputs, the behavior is undefined — it may silently fall back to defaultSort, pass an array as a GraphQL variable (causing an API error), or produce unexpected results. This is a latent bug that is difficult to detect in testing because it requires a crafted URL.

Recommendation:

• Replace the type cast with explicit runtime guards:

// Safe extraction with runtime type guard
const rawSort = searchParams?.sort;
const sort = typeof rawSort === 'string' ? rawSort : undefined;

const rawQ = searchParams?.q;
const searchValue = typeof rawQ === 'string' ? rawQ : undefined;

• Apply the same pattern to the collection parameter on the Search Detail screen.

• Consider a shared utility function getSingleParam(params: unknown, key: string): string | undefined to centralize this pattern across all search-related pages.

Effort: Low (< 1 hour per screen; 2 screens)

SQALE Characteristic: Reliability

Source Evidence: Search (/search), Search Detail (/search/[collection])

4.2 Reliability (Score: 3/5)

Overview

The most significant reliability risk is a confirmed null dereference on the primary conversion page (Product Detail). Additionally, the absence of error boundaries at the page level means Shopify API failures propagate as unhandled server errors across all five screens. The team has documented several of these gaps in §17 of the affected screens, which reflects good awareness of the debt.

CH-002: Unguarded featuredImage Property Access in JSON-LD

Severity: Critical Quality Sub-Characteristic: Fault Tolerance Screen(s): Product Detail (/product/[handle]) Component(s): productJsonLd construction in app/product/[handle]/page.tsx

Description: The productJsonLd object accesses product.featuredImage.url directly without a null or undefined guard. The generateMetadata function on the same screen correctly handles this case with optional chaining (product.featuredImage || {}), but the JSON-LD block does not apply the same defensive pattern. Any Shopify product that has no featured image configured will cause a runtime TypeError when the page renders, resulting in a 500 error response for that product URL.

Evidence: Product Detail (/product/[handle]) §10: "The JSON-LD block accesses product.featuredImage.url directly without a null guard — if featuredImage is undefined, this would throw a runtime error." Also documented in §17: "Potential null dereference on featuredImage."

Risk: Any product in the Shopify catalog without a featured image will return a 500 error instead of a product page. This is a production-breaking defect for affected products — shoppers cannot view or purchase those items, and the error will appear in server logs without a clear user-facing message.

Recommendation:

• Apply optional chaining consistent with the generateMetadata pattern already in the same file:

// Before (unsafe)
image: product.featuredImage.url,

// After (safe — consistent with generateMetadata pattern)
...(product.featuredImage?.url && { image: product.featuredImage.url }),

• Add a unit test asserting that productJsonLd is constructed without error when product.featuredImage is undefined.

• Audit lib/shopify's getProduct return type to confirm whether featuredImage is typed as optional — if it is typed as required but can be null at runtime, the type definition is incorrect and should be fixed.

Effort: Low (< 1 hour)

SQALE Characteristic: Reliability

Source Evidence: Product Detail (/product/[handle])

CH-004: No Error Boundaries at Page Level — Shopify API Failures Produce Unhandled Server Errors

Severity: Major Quality Sub-Characteristic: Fault Tolerance Screen(s): Home (/), Item Detail (/[page]), Product Detail (/product/[handle]), Search (/search), Search Detail (/search/[collection]) Component(s): All five assessed page components; RelatedProducts server component

Description: None of the five assessed page components wrap their data-fetching calls in try/catch blocks, and none have co-located error.tsx files documented. When getPage, getProduct, getProducts, getCollection, or getCollectionProducts throw (network failure, Shopify rate limit, malformed response), the error propagates as an unhandled server exception. The behavior depends on whether a parent layout defines an error.tsx boundary — if none exists, Next.js renders a generic error page with no user-friendly messaging. The RelatedProducts component on the Product Detail screen is specifically called out as having no error boundary.

Evidence:

• Item Detail §10: "A Shopify API network failure — Unhandled at this component level; propagates as an unhandled server error."

• Product Detail §10: "No error boundaries: Neither RelatedProducts nor the Gallery/ProductDescription Suspense wrappers include React Error Boundaries."

• Product Detail §17: "A failure in getProductRecommendations (network error, Shopify API error) has no error boundary."

• Search §10: "There is no try/catch block in the page component wrapping the getProducts call."

• Search Detail §10: "Shopify API failure in getCollectionProducts — Error propagates to Next.js error boundary (defined at layout level, not in this file)."

Risk: A transient Shopify API outage or rate-limit event causes all affected pages to return 500 errors simultaneously, with no graceful degradation. Users see a generic error page rather than a helpful message. For the Product Detail screen, a failure in RelatedProducts could take down the entire product page even though the core product content loaded successfully.

Recommendation:

• Add a co-located error.tsx file at the app/ level (or per-route where appropriate) that renders a user-friendly error message and a retry option.

• Wrap the RelatedProducts component in a React Error Boundary so that a failure in related product recommendations does not affect the main product card:

// app/product/[handle]/page.tsx
<Suspense fallback={<RelatedProductsSkeleton />}>
<ErrorBoundary fallback={null}>
<RelatedProducts id={product.id} />
</ErrorBoundary>
</Suspense>

• For the getProducts and getCollectionProducts calls on search screens, add try/catch with a fallback to an empty array and a user-facing "Unable to load products" message.

[Not documented — WHO: tech lead; WHAT: Does a root-level app/error.tsx or app/global-error.tsx file exist in the repository?; WHERE: Insert answer in CH-004 above — if a root error boundary exists, severity of this finding should be reduced to Minor (defense-in-depth gap only).]

Effort: Medium (1–4 hours)

SQALE Characteristic: Reliability

Source Evidence: Item Detail (/[page]), Product Detail (/product/[handle]), Search (/search), Search Detail (/search/[collection])

CH-005: Invalid Date Rendered to Users When page.updatedAt Is Malformed

Severity: Minor Quality Sub-Characteristic: Fault Tolerance Screen(s): Item Detail (/[page]) Component(s): Date formatting inline expression in app/[page]/page.tsx

Description: The last-updated date is formatted inline using new Intl.DateTimeFormat(undefined, {...}).format(new Date(page.updatedAt)). If page.updatedAt is an empty string, null, or a non-ISO date string, new Date(...) produces an Invalid Date object, and Intl.DateTimeFormat.format() outputs the literal string "Invalid Date" to the rendered page. This is a user-visible data quality failure.

Evidence: Item Detail §10: "page.updatedAt is malformed → new Date(page.updatedAt) produces an Invalid Date; Intl.DateTimeFormat.format() would output 'Invalid Date' as a string."

Risk: Shoppers see "Invalid Date" in the last-updated line of informational pages (Privacy Policy, About Us, etc.), which undermines trust in the storefront's professionalism. While Shopify typically returns well-formed ISO 8601 timestamps, defensive handling is warranted for any externally sourced date value.

Recommendation:

• Add a guard before formatting:

const updatedDate = new Date(page.updatedAt);
const formattedDate = isNaN(updatedDate.getTime())
? null
: new Intl.DateTimeFormat(undefined, {
year: 'numeric',
month: 'long',
day: 'numeric',
}).format(updatedDate);

// In JSX:
{formattedDate && (
<p className="text-sm italic">
{`This document was last updated on ${formattedDate}`}
</p>
)}

• Add a unit test for the malformed date case.

Effort: Low (< 1 hour)

SQALE Characteristic: Reliability

Source Evidence: Item Detail (/[page])

CH-006: No Test Suite Present Across All Assessed Screens

Severity: Major Quality Sub-Characteristic: Testability Screen(s): Home (/), Item Detail (/[page]), Product Detail (/product/[handle]), Search (/search), Search Detail (/search/[collection]) Component(s): All assessed page components

Description: No co-located test files are present for any of the five assessed screens. The package.json test script runs only prettier:check (a formatting check), confirming that no test runner (Jest, Vitest, Playwright, Cypress) is configured in the project manifest. The documentation for each screen includes a recommended testing strategy, indicating the team is aware of the gap.

Evidence:

• All five screens §16: "No co-located tests found in the collected files."

• package.json scripts.test: "pnpm prettier:check" — no test runner invocation present.

• No jest, vitest, @playwright/test, or cypress packages appear in package.json dependencies or devDependencies.

Risk: Without automated tests, regressions in critical paths (product not found → 404, add-to-cart flow, search result rendering) are only caught manually or in production. The productJsonLd null dereference (CH-002) and the Invalid Date rendering (CH-005) are examples of defects that unit tests would have caught before deployment.

Recommendation:

• Add a test runner to the project. Given the Next.js App Router and React Server Component architecture, Vitest with @testing-library/react is recommended for unit and integration tests; Playwright is recommended for E2E tests.

• Prioritize tests for the highest-risk paths first:

  1. productJsonLd construction with featuredImage: undefined (covers CH-002)

  2. generateMetadata not-found handling for all three dynamic routes

3. Search sort fallback logic

4. Invalid Date guard for page.updatedAt

• Update the test script in package.json to run the test suite in addition to the Prettier check.

Effort: Very High (16+ hours — initial test infrastructure setup + first test suite)

SQALE Characteristic: Testability

Source Evidence: Home (/), Item Detail (/[page]), Product Detail (/product/[handle]), Search (/search), Search Detail (/search/[collection])

4.3 Security (Score: 3/5)

Overview

The application's security posture is reasonable for a public-facing read-only storefront: all Shopify API credentials are server-side only, no authentication tokens are exposed to the client, and the GraphQL parameterization in lib/shopify prevents injection attacks. Two specific hardening gaps require attention: an XSS vector in the JSON-LD script tag and an unsafe type cast that could pass unexpected values to the Shopify API.

CH-003: dangerouslySetInnerHTML JSON-LD Without </script> Escape Hardening

Severity: Critical Quality Sub-Characteristic: Security (Confidentiality / Integrity) Screen(s): Product Detail (/product/[handle]) Component(s): JSON-LD <script> tag in app/product/[handle]/page.tsx

Description: The structured data block uses dangerouslySetInnerHTML={{ __html: JSON.stringify(productJsonLd) }} to inject JSON-LD into a <script> tag. JSON.stringify does not escape the </script> character sequence. If any Shopify-sourced string field (product title, description, or SEO fields) contains the literal text </script>, the browser's HTML parser will interpret it as closing the script tag, potentially allowing injected HTML or script content to execute. This is a documented XSS vector for inline JSON-LD. The team has documented this in §17.

Evidence: Product Detail §14: "if Shopify-sourced data contained a </script> sequence, it could theoretically break the script tag. A more robust approach would use a JSON serializer that escapes <, >, and & characters." Also §17: "JSON.stringify does not escape </script> sequences, which is a known XSS vector for inline JSON-LD."

Risk: A Shopify merchant (or an attacker with access to Shopify admin) who sets a product title or description containing </script><script>alert(1)</script> could inject arbitrary JavaScript into every visitor's browser on that product page. While this requires Shopify admin access, it is a meaningful risk in multi-merchant or compromised-admin scenarios, and it violates defense-in-depth principles.

Recommendation:

• Replace JSON.stringify with a hardened serializer that escapes HTML-unsafe characters:

function safeJsonLd(data: object): string {
return JSON.stringify(data)
.replace(/</g, '\u003c')
.replace(/>/g, '\u003e')
.replace(/&/g, '\u0026');
}

// Usage:
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: safeJsonLd(productJsonLd) }}
/>

• This is a one-line utility function; extract it to lib/utils.ts for reuse if JSON-LD is added to other pages.

• Add a unit test asserting that a product with </script> in its title produces escaped output.

Effort: Low (< 1 hour)

SQALE Characteristic: Security

Source Evidence: Product Detail (/product/[handle])

CH-007: dangerouslySetInnerHTML in Prose Component — XSS Dependency on Shopify Output Sanitization

Severity: Major Quality Sub-Characteristic: Security (Integrity) Screen(s): Item Detail (/[page]) Component(s): Prose component (components/prose), used in app/[page]/page.tsx

Description: The Prose component renders page.body — a raw HTML string from Shopify's CMS — using dangerouslySetInnerHTML (implied by the html prop pattern). The security of this rendering depends entirely on two factors: (1) whether Shopify sanitizes its page body output before returning it via the Storefront API, and (2) whether the Prose component applies any additional sanitization. Neither factor is confirmed in the provided documentation. If a Shopify page body contains a <script> tag or an event handler attribute (e.g., <img onerror="...">), it would execute in the visitor's browser.

Evidence: Item Detail §3: "The component applies typographic prose styling to the injected HTML. It receives... an html prop containing the raw HTML string. This component uses dangerouslySetInnerHTML internally (implied by the html prop pattern)." Item Detail §14: "if the Prose component uses dangerouslySetInnerHTML without sanitization, any XSS payloads stored in Shopify page content would be rendered. The security posture depends entirely on the Prose component's implementation and Shopify's own output sanitization."

Risk: If Shopify's Storefront API returns unsanitized HTML and the Prose component does not sanitize it, a merchant (or attacker with Shopify admin access) can inject arbitrary JavaScript into informational pages (Privacy Policy, About Us, etc.), affecting all visitors.

Recommendation:

• Verify whether Shopify's Storefront API sanitizes page.body HTML output. Review Shopify's API documentation for the Page.body field's sanitization guarantees.

• Inspect the Prose component source to confirm whether it applies HTML sanitization (e.g., using DOMPurify or a similar library) before passing content to dangerouslySetInnerHTML.

• If neither Shopify nor Prose sanitizes the content, add client-side sanitization using isomorphic-dompurify or sanitize-html:

import DOMPurify from 'isomorphic-dompurify';

// In Prose component:
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(html) }} />

Effort: Medium (1–4 hours — dependency on Prose component review)

SQALE Characteristic: Security

Source Evidence: Item Detail (/[page])

4.4 Performance Efficiency (Score: 4/5)

Overview

The application makes excellent use of Next.js 15's performance capabilities: React Server Components eliminate client-side JavaScript for all five assessed pages, streaming SSR via Suspense is used on the Product Detail screen, and prefetch={true} on related product links reduces navigation latency. The primary performance concern is the absence of pagination on search and collection pages, which is a scalability risk for large catalogs.

CH-008: No Pagination on Search and Collection Product Listings

Severity: Major Quality Sub-Characteristic: Time Behaviour Screen(s): Search (/search), Search Detail (/search/[collection]) Component(s): getProducts and getCollectionProducts calls in app/search/page.tsx, app/search/[collection]/page.tsx

Description: Both search screens fetch all matching products in a single API call with no pagination, infinite scroll, or cursor-based loading. The maximum number of products returned is governed by lib/shopify's implementation (not assessed here). For stores with large catalogs or broad search terms, this pattern can produce slow server renders, large HTML payloads, and high memory usage. The team has documented this as a known issue on both screens.

Evidence:

• Search §12: "There is no pagination, infinite scroll, or virtual list implementation. For stores with large product catalogs, this could result in slow renders or large payloads."

• Search Detail §12: "All products in the collection are fetched and rendered in a single request. For collections with very large product counts, this could become a performance concern."

• Search §17: "No pagination: For stores with large catalogs, the lack of pagination could be a scalability concern."

• Search Detail §17: "No pagination: All products in a collection are fetched in a single call."

Risk: As the product catalog grows, search and collection pages will become progressively slower. A collection with hundreds of products will produce a large server render time and a large HTML payload, degrading Core Web Vitals (LCP, FID) and potentially causing timeouts on the Shopify API call.

Recommendation:

• Implement cursor-based pagination using Shopify's Storefront API pageInfo { hasNextPage, endCursor } pattern.

• For the initial implementation, a "Load More" button (appending to the current list) is simpler than full infinite scroll and avoids the accessibility concerns of infinite scroll.

• Alternatively, implement URL-based page navigation (?page=2) for deep-linkable paginated results.

• Set an explicit product limit (e.g., 24 or 48 per page) in getProducts and getCollectionProducts as an immediate mitigation even before full pagination UI is built.

[Not documented — WHO: tech lead or Shopify integration owner; WHAT: What is the current first: limit set in the getProducts and getCollectionProducts GraphQL queries in lib/shopify?; WHERE: Insert in CH-008 above — if the limit is already set to a reasonable value (e.g., ≤ 50), severity of this finding may be reduced to Minor.]

Effort: High (4–16 hours)

SQALE Characteristic: Efficiency

Source Evidence: Search (/search), Search Detail (/search/[collection])

CH-009: Experimental Next.js Features in Production Configuration

Severity: Minor Quality Sub-Characteristic: Operability (Compatibility) Screen(s): All screens Component(s): next.config.ts

Description: The next.config.ts enables three experimental Next.js features: ppr (Partial Prerendering), inlineCss, and useCache. Additionally, the project uses next@15.6.0-canary.60 — a canary (pre-release) build. Experimental features and canary builds are subject to breaking changes between releases without semantic versioning guarantees. The useCache directive in particular is a new caching API that is not yet stable.

Evidence: next.config.ts: experimental: { ppr: true, inlineCss: true, useCache: true }. package.json: "next": "15.6.0-canary.60".

Risk: A Next.js canary update could introduce breaking changes to any of the three experimental APIs, causing build failures or runtime regressions without a major version bump. The useCache API is particularly new and its behavior may change. This is a low-probability but high-impact risk for a production storefront.

Recommendation:

• Track the Next.js changelog for stabilization of ppr, inlineCss, and useCache. Pin the canary version explicitly (already done via 15.6.0-canary.60) and establish a deliberate upgrade process rather than using a range specifier.

• When Next.js 15 stable releases these features, migrate from experimental.* flags to the stable API.

• Document the rationale for using canary in the project README so future contributors understand the intentional choice.

Effort: Low (< 1 hour for documentation; Medium for migration when stable APIs land)

SQALE Characteristic: Portability

Source Evidence: next.config.ts, package.json

4.5 Functional Suitability (Score: 3/5)

Overview

The core e-commerce flows (product browsing, search, collection filtering, product detail) are functionally complete within the assessed screens. Two functional correctness issues are present: server-locale date formatting that produces incorrect output for international users, and the soft-hide product mechanism that may not meet merchant expectations for truly hidden products.

CH-011: Server Locale Used for Date Formatting — Incorrect Output for International Users

Severity: Major Quality Sub-Characteristic: Functional Correctness Screen(s): Item Detail (/[page]) Component(s): Inline date formatting in app/[page]/page.tsx

Description: The last-updated date on informational pages is formatted using new Intl.DateTimeFormat(undefined, ...). When undefined is passed as the locale on a server, the formatter uses the server's runtime locale, not the visitor's browser locale. This means all users — regardless of their language or region — see the date formatted according to the server's locale setting. For example, a French user visiting an English-language server will see "April 15, 2026" rather than "15 avril 2026". The team has documented this as a known issue.

Evidence: Item Detail §8: "The Intl.DateTimeFormat is instantiated with undefined as the locale, which resolves to the runtime environment's default locale. On a server, this will be the server's locale rather than the user's browser locale — a subtle but important distinction." Also §17: "This means all users see the date formatted according to the server's locale setting, which may not match their expectations."

Risk: For international storefronts, all users see dates in the server's locale format. This is a functional correctness failure for non-English users and may cause confusion or distrust on legal/policy pages where date accuracy is important.

Recommendation:

• For a server-rendered component, the user's locale is not directly available. Two approaches:

  1. Use a fixed locale matching the storefront's primary language (e.g., 'en-US') for consistency and predictability:

new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
.format(new Date(page.updatedAt))

2. Use a <time> element with ISO datetime and format client-side in a "use client" wrapper component that reads navigator.language. This is the most correct approach for international storefronts but adds a client component.

• Replace the plain <p> with a <time datetime={page.updatedAt}> element regardless of which approach is chosen, as this improves semantic correctness and accessibility (see CH-013).

Effort: Low (< 1 hour for option 1; Medium for option 2)

SQALE Characteristic: Maintainability

Source Evidence: Item Detail (/[page])

CH-012: Hidden Products Accessible via Direct URL — Soft-Hide Is Not Access Control

Severity: Info Quality Sub-Characteristic: Functional Completeness Screen(s): Product Detail (/product/[handle]) Component(s): HIDDEN_PRODUCT_TAG logic in app/product/[handle]/page.tsx

Description: Products tagged with HIDDEN_PRODUCT_TAG are excluded from search engine indexing (noindex, nofollow) but remain fully accessible via direct URL. This is a deliberate design decision documented in the screen. However, if merchants expect "hidden" products to be inaccessible to users (e.g., for staging new products or internal-only SKUs), the current implementation does not meet that expectation — it only prevents search engine discovery.

Evidence: Product Detail §2: "products tagged with the HIDDEN_PRODUCT_TAG constant are rendered normally for visitors but are marked noindex, nofollow in their metadata... This means hidden products are accessible via direct URL but will not appear in search engine results." §14: "This is a soft-hide mechanism, not an access control mechanism."

Risk: Merchants who use HIDDEN_PRODUCT_TAG expecting true access restriction will find that anyone with the direct URL can view and potentially purchase the product. This is a functional expectation mismatch rather than a code defect, but it should be clearly communicated.

Recommendation:

• Document the soft-hide behavior explicitly in the project README or a merchant-facing guide so that the distinction between "hidden from search" and "access-restricted" is clear.

• If true access restriction is required for any products, implement a middleware guard that checks for the tag and returns a 404 for direct URL access.

• No code change is required if the current behavior is intentional and merchants are informed.

Effort: Low (< 1 hour for documentation; High if access restriction is required)

SQALE Characteristic: Maintainability

Source Evidence: Product Detail (/product/[handle])

4.6 Usability (Score: 3/5)

Overview

The application provides a clean, server-rendered experience with good empty state handling on search and collection pages. The primary usability gaps are missing loading skeletons on several screens, absent ARIA live regions for dynamic content, and semantic HTML gaps that affect screen reader users.

CH-013: Missing <time> Element for Machine-Readable Dates

Severity: Minor Quality Sub-Characteristic: Accessibility (Usability) Screen(s): Item Detail (/[page]) Component(s): Last-updated paragraph in app/[page]/page.tsx

Description: The last-updated date on informational pages is rendered in a plain <p> tag with no <time> element or datetime attribute. The <time> element with a machine-readable datetime attribute improves semantic correctness, enables screen readers to announce dates in a locale-appropriate format, and allows browser extensions and search engines to parse the date accurately. The team has documented this gap in §17.

Evidence: Item Detail §15: "The Intl.DateTimeFormat date string is rendered in plain text without a <time> element and datetime attribute, which would improve machine-readability and screen reader context." Also §17: "No <time> element for the updated date."

Risk: Screen readers may announce the formatted date string verbatim rather than interpreting it as a date. Search engines cannot reliably parse the date for structured data purposes. This is a low-severity accessibility and semantic gap.

Recommendation:

• Replace the plain <p> with a <time> element:

<p className="text-sm italic">
{`This document was last updated on `}
<time dateTime={page.updatedAt}>
{new Intl.DateTimeFormat('en-US', {
year: 'numeric',
month: 'long',
day: 'numeric',
}).format(new Date(page.updatedAt))}
</time>
</p>

• This change also addresses the locale issue documented in CH-011 if a fixed locale is chosen.

Effort: Low (< 1 hour)

SQALE Characteristic: Maintainability

Source Evidence: Item Detail (/[page])

CH-014: Missing Loading Skeletons on Search and Item Detail Screens

Severity: Minor Quality Sub-Characteristic: User Experience (Usability) Screen(s): Search (/search), Search Detail (/search/[collection]), Item Detail (/[page]) Component(s): Page-level loading state; absence of loading.tsx sibling files

Description: The Search, Search Detail, and Item Detail screens do not define loading.tsx sibling files (based on documentation evidence). Without a loading.tsx, Next.js App Router does not show a loading skeleton during server render. Users navigating to these pages during slow Shopify API responses will see a blank or stalled page rather than a skeleton that communicates progress. The Product Detail screen partially mitigates this with Suspense fallbacks on Gallery and ProductDescription, but the search screens have no equivalent.

Evidence:

• Search §17: "there is no loading.tsx sibling file referenced, meaning users may see a blank or stalled page during slow Shopify API responses without a skeleton/loading UI."

• Search Detail §12: "The page component itself defines no loading skeleton. This relies entirely on Next.js layout-level loading.tsx files or Suspense boundaries defined elsewhere in the app."

• Home §10: "the page component does not define any loading.tsx or error.tsx co-located files (based on provided sources)."

Risk: During slow network conditions or Shopify API latency spikes, users see a blank page with no feedback, which increases perceived load time and bounce rate. This is a usability concern rather than a functional defect.

Recommendation:

• Add loading.tsx files co-located with the affected page routes:

  • app/search/loading.tsx — skeleton with placeholder product grid cards

  • app/search/[collection]/loading.tsx — same skeleton

  • app/[page]/loading.tsx — skeleton with placeholder heading and text blocks

• Use Tailwind's animate-pulse utility to create simple skeleton placeholders without additional dependencies.

Effort: Medium (1–4 hours for all three screens)

SQALE Characteristic: Usability

Source Evidence: Search (/search), Search Detail (/search/[collection]), Item Detail (/[page])

CH-015: Absent ARIA Live Regions for Search Result Announcements

Severity: Minor Quality Sub-Characteristic: Accessibility (Usability) Screen(s): Search (/search) Component(s): Results summary paragraph in app/search/page.tsx

Description: The Search screen renders a results count paragraph (e.g., "Showing 4 results for 'shoes'") but does not wrap it in an aria-live region. Because this is a server-rendered full-page navigation (not a client-side update), the page title change may serve as the primary announcement mechanism for screen readers. However, an explicit aria-live="polite" region on the results summary would provide a more reliable and explicit announcement of result counts to assistive technology users.

Evidence: Search §15: "There is no aria-live region to announce search result counts to screen reader users when results update. Since this is a server-rendered page (full navigation on search), the page title change may serve as the announcement mechanism, but an explicit live region would improve the experience."

Risk: Screen reader users may not receive a clear announcement of how many results were found after navigating to a search URL. This is a WCAG 2.1 Level AA concern (Success Criterion 4.1.3 — Status Messages).

Recommendation:

• Add role="status" and aria-live="polite" to the results summary paragraph:

{searchValue && (
<p role="status" aria-live="polite">
{products.length === 0
? `There are no products that match "${searchValue}"`
: `Showing ${products.length} ${resultsText} for "${searchValue}"`}
</p>
)}

• Verify with a screen reader (NVDA, VoiceOver) that the announcement fires correctly on navigation.

Effort: Low (< 1 hour)

SQALE Characteristic: Usability

Source Evidence: Search (/search)

4.7 Compatibility (Score: 4/5)

Overview

The application targets modern browsers via es2015 TypeScript compilation target and uses standard Next.js image optimization with AVIF/WebP formats. The primary compatibility concern is the use of a canary Next.js build with experimental flags, which is addressed in CH-009.

No additional compatibility findings beyond CH-009 are evidenced in the documentation.

4.8 Portability (Score: 4/5)

Overview

The Shopify integration is cleanly abstracted behind lib/shopify, meaning the storefront UI is decoupled from Shopify-specific API details. The next.config.ts image remotePatterns allowlist is appropriately scoped to cdn.shopify.com. No portability findings beyond CH-009 (experimental flags) are evidenced in the documentation.

5. Technical Debt Inventory

6. Finding Inventory

7. Needs Verification

The following findings are inferred from patterns described in the documentation but cannot be confirmed without direct source code access. They are not counted in severity totals and are not scheduled in the Remediation Roadmap.

8. Remediation Roadmap

Phase 1: Immediate (This Sprint)

Phase 2: Short-Term (30 Days)

Phase 3: Medium-Term (90 Days)

Phase 4: Long-Term (Backlog)

9. Positive Patterns

10. Screen Health Matrix

Note: Finding counts per screen reflect the number of findings where that screen is listed as an affected screen. Findings affecting all screens (CH-004, CH-006, CH-009) are counted once per screen in the matrix but appear as a single finding in the Finding Inventory.

11. Glossary

Quality Terms

Domain Terms

Technical Terms