Code Health Assessment

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

Executive Summary

Generated by Inkwell Forge — 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 architectural foundation is sound — React Server Components are used consistently and correctly, the Shopify integration is cleanly abstracted behind lib/shopify, and TypeScript strict mode is enabled throughout — but a cluster of recurring patterns across screens introduces reliability and maintainability risk that warrants structured remediation.

Key strengths include the disciplined use of the Next.js App Router RSC model (zero client-side JavaScript overhead on all five assessed screens), clean separation of data-fetching concerns behind the lib/shopify abstraction layer, and the consistent application of notFound() guards that prevent broken UI states for missing Shopify resources. The next.config.ts demonstrates deliberate use of experimental Next.js features (Partial Prerendering, inline CSS, the useCache API) that position the application well for performance at scale.

The three highest-risk findings are: [CH-002] Unguarded featuredImage Access in JSON-LD Construction (a null-dereference that will crash the Product Detail page render for any product without a featured image), [CH-001] Duplicate getPage/getProduct API Calls Across generateMetadata and Page Component (a cross-cutting pattern affecting three screens that doubles Shopify API calls per request when fetch deduplication is not active), and [CH-006] JSON.stringify Used for HTML-Embedded JSON-LD Without HTML-Character Escaping (a latent XSS vector on the Product Detail page if Shopify-sourced content contains </script> sequences). See the Finding Inventory for the complete catalog of findings by severity.

This assessment is based entirely on per-screen technical documentation. Static analysis tooling, runtime profiling, git history, and direct source code access were not available. Findings marked "(based on documentation — verify with static analysis)" or "(inferred from …)" require confirmation before scheduling remediation work.

Assessment Methodology

Quality Model

ISO/IEC 25010:2023 — eight quality characteristics assessed where applicable: Maintainability, Reliability, Security, Performance Efficiency, Functional Suitability, Usability, Compatibility, and Portability.

Debt Classification

SQALE method — findings are classified by remediation type (Design Debt, Code Debt, Test Debt, Doc Debt, Dependency Debt) and effort band (Low / Medium / High / Very High).

Severity Model

Aligned with SonarQube severity definitions:

Scope

This assessment covers 5 screens of the commerce application:

Screens, features, and components not included in the assessed documentation are outside the scope of this document. This includes lib/shopify, components/product/product-description, components/product/gallery, components/grid/tile, components/layout/product-grid-items, components/grid, and all middleware and layout files beyond app/layout.tsx.

Limitations

• Findings are derived from per-screen technical documentation, not from automated static analysis, runtime profiling, or direct source code inspection.
• Cyclomatic complexity, line counts, test coverage percentages, and churn rates cannot be measured from this documentation.
• The lib/shopify service layer is referenced extensively but not documented; findings about its behavior are marked with the appropriate inference markers.
• Where a finding's existence depends on undocumented behavior, severity has been calibrated conservatively per the hedge-calibrated severity requirement.

Quality Scorecard

Detailed Findings by Quality Dimension

Maintainability (Score: 3/5)

Overview

The five assessed screens follow a consistent architectural pattern — thin RSC compositor pages that delegate data fetching and rendering to child components. This is a positive structural choice. However, three recurring patterns degrade maintainability: (1) a duplicate API call pattern in generateMetadata / page component pairs that appears on three screens, (2) unsafe searchParams type assertions on two screens, and (3) a hardcoded magic number for the image gallery cap. The codebase has no co-located tests on any assessed screen, which is the most significant maintainability gap.

CH-001: Duplicate API Calls in generateMetadata and Page Component

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

Description: On three screens, the same Shopify service function is called independently in both generateMetadata and the default page export: getPage on Item Detail, getProduct on Product Detail, and getCollection on Search Detail. Each call is a separate invocation with no shared result. If the underlying lib/shopify functions use the native fetch API with identical cache keys, Next.js request memoization will deduplicate them within a single render pass. If lib/shopify uses a non-fetch HTTP client (e.g., a custom GraphQL client or node-fetch), two separate Shopify API network requests are made per page load on each of these three routes. This doubles API quota consumption, increases latency, and makes the data-fetching logic harder to reason about.

Evidence:

• Item Detail (/[page]): §5 — "getPage is called twice per request — once in generateMetadata and once in the Page component."
• Product Detail (/product/[handle]): §5 — "getProduct(params.handle) is called twice — once in generateMetadata and once in ProductPage."
• Search Detail (/search/[collection]): §5 — "getCollection is called in generateMetadata" and §17 — "getCollection is called twice."
• §17 (Item Detail) and §17 (Product Detail) both list this as known technical debt.

Risk: If lib/shopify does not use native fetch (a common pattern in Shopify integrations that use a custom GraphQL client), every page load on these three routes makes two Shopify API calls instead of one. Under load, this doubles API rate-limit consumption and increases p99 latency. It also creates a subtle consistency risk: if the Shopify data changes between the two calls (unlikely but possible during a deployment), generateMetadata and the page body could render different data.

Recommendation:

• Wrap the service calls in React's cache() function (available in React 19, which this project uses) at the lib/shopify call site or in a per-request cache module. This guarantees deduplication regardless of the underlying HTTP client.
• Example pattern:

// lib/shopify/cached.ts
import { cache } from 'react';
import { getProduct as _getProduct } from './index';

export const getProduct = cache(_getProduct);

• Replace direct imports of getProduct, getPage, and getCollection in the affected page files with the cached variants.
• Alternatively, pass the fetched data from generateMetadata to the page component via a shared module-level cache, though React cache() is the idiomatic App Router solution.

Effort: Medium (2–4 hours across all three screens)

SQALE Characteristic: Efficiency / Maintainability

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

CH-003: Unsafe searchParams Type Assertion

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

Description: Both screens cast searchParams using as { [key: string]: string }. This assertion suppresses TypeScript's awareness that: (a) query parameter values can be string | string[] | undefined when the same key appears multiple times in a URL, and (b) searchParams itself may be undefined (the prop type on Search Detail is documented as Promise<...> | undefined). The cast bypasses the type system's protection, meaning a crafted URL like /search?q=shirt&q=pants would pass a string[] to getProducts as the query parameter, producing undefined behavior. On Search Detail, if searchParams is undefined, the destructuring will throw a runtime error.

Evidence:

• Search (/search): §14 — "searchParams is cast with as { [key: string]: string }, which means if q or sort are undefined, searchValue and sort will be undefined."
• Search (/search): §17 — "Unsafe type cast: searchParams is cast as { [key: string]: string } using as, which suppresses TypeScript's awareness that query parameter values can be string | string[] | undefined."
• Search Detail (/search/[collection]): §10 — "The destructuring const { sort } = searchParams as { [key: string]: string } would throw a runtime error if searchParams is undefined."
• Search Detail (/search/[collection]): §17 — "Unsafe searchParams type assertion."

Risk: A crafted URL with duplicate query keys could cause getProducts or getCollectionProducts to receive a string[] where a string is expected, potentially causing an unhandled exception or incorrect API query. On Search Detail, an undefined searchParams causes a runtime crash. Both scenarios would surface as 500 errors to the user.

Recommendation:

• Replace the type assertion with explicit runtime extraction and type narrowing:

// Safe extraction pattern
const rawSort = Array.isArray(searchParams?.sort)
  ? searchParams.sort[0]
  : searchParams?.sort;
const sort = typeof rawSort === 'string' ? rawSort : undefined;

• For Next.js 15 App Router, use the typed ReadonlyURLSearchParams pattern or the next/navigation useSearchParams hook in client components. For RSC pages, use the searchParams prop with proper optional chaining.
• Apply this pattern consistently to both q and sort parameters on both affected screens.

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

SQALE Characteristic: Reliability / Maintainability

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

CH-004: Hardcoded Magic Number for Gallery Image Cap

Severity: Minor Quality Sub-Characteristic: Modifiability Screen(s): Product Detail (/product/[handle]) Component(s): app/product/[handle]/page.tsx

Description: The expression product.images.slice(0, 5) uses the literal 5 as the maximum number of images passed to the Gallery component. This magic number has no named constant, no comment explaining the rationale, and no configuration entry. If the desired gallery size changes, a developer must locate this literal by searching the codebase rather than updating a single named constant.

Evidence: Product Detail (/product/[handle]): §8 — "Only the first 5 product images (product.images.slice(0, 5)) are passed to Gallery, regardless of how many images Shopify returns. This is a hard-coded business rule limiting gallery size." §17 — "Hard-coded image limit: product.images.slice(0, 5) is a magic number with no named constant or configuration."

Risk: Low immediate risk. The risk is a maintenance error: a future developer changes the gallery layout to support 6 images, updates the Gallery component, but misses the slice(0, 5) call in the page file, resulting in the 6th image never being displayed. The bug would be non-obvious because the Gallery component would appear to work correctly.

Recommendation:

• Define a named constant in lib/constants (alongside the existing HIDDEN_PRODUCT_TAG and sorting constants):

// lib/constants.ts
export const MAX_GALLERY_IMAGES = 5;

• Replace the literal in page.tsx:

product.images.slice(0, MAX_GALLERY_IMAGES).map(...)

Effort: Low (< 30 minutes)

SQALE Characteristic: Maintainability

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

CH-010: No Co-Located Tests on Any Assessed Screen

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 page components

Description: No co-located tests were found for any of the five assessed screens. The package.json test script runs only prettier:check — a formatting check, not a test suite. No testing framework (Jest, Vitest, Playwright, Cypress) appears in the project manifest. This means there is no automated regression safety net for any of the documented screens. The documentation for each screen provides detailed recommended testing strategies (unit, integration, E2E), indicating the team is aware of the gap.

Evidence:

• §16 of every assessed screen: "No co-located tests found in the collected files."
• package.json: "test": "pnpm prettier:check" — no test runner configured.
• No jest, vitest, @playwright/test, or cypress entries in dependencies or devDependencies.

Risk: Without automated tests, any refactoring of the Shopify service layer, sort logic, metadata generation, or routing behavior carries a high risk of silent regression. The duplicate API call pattern (CH-001), the null-dereference risk (CH-002), and the type assertion issues (CH-003) would all benefit from test coverage before remediation to prevent introducing new bugs.

Recommendation:

• Add a testing framework to the project. Given the Next.js 15 / React 19 stack, Vitest with @testing-library/react is the recommended choice for unit and integration tests; Playwright for E2E.
• Prioritize tests for the highest-risk logic first: generateMetadata fallback chains, notFound() guard behavior, sort resolution logic, and the productJsonLd construction.
• Add the test runner to the test script in package.json so CI enforces test passage alongside formatting.
• Use the recommended testing strategies documented in §16 of each screen as the initial test specification.

Effort: Very High (16+ hours to establish the framework and initial coverage across all five screens)

SQALE Characteristic: Testability

Source Evidence: All five assessed screens (§16); package.json

Reliability (Score: 3/5)

Overview

The screens handle the most common failure mode (missing Shopify resource) consistently and correctly via notFound() guards. However, one confirmed null-dereference bug will crash the Product Detail page for any product without a featured image, and the uniform treatment of "not found" and "API error" as the same condition makes operational diagnosis difficult. No error tracking SDK is identifiable from the project manifest.

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

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

Description: The productJsonLd object accesses product.featuredImage.url without a null guard. The generateMetadata function in the same file correctly guards this access with product.featuredImage || {}, but the page body's JSON-LD construction does not apply the same pattern. If a Shopify product has no featured image (a valid Shopify state), product.featuredImage will be null or undefined, and accessing .url on it will throw a TypeError at render time, crashing the entire page render and returning a 500 error to the user.

Evidence: Product Detail (/product/[handle]): §10 — "Missing featured image: The productJsonLd object accesses product.featuredImage.url without a null guard. If featuredImage is null or undefined, this will throw a runtime error." §17 — "Unguarded featuredImage access in JSON-LD: product.featuredImage.url in productJsonLd has no null guard, unlike the generateMetadata function which uses product.featuredImage || {}."

Risk: Any product in the Shopify catalog that lacks a featured image will produce a 500 error on its product detail page. This is a production-impacting bug, not a theoretical risk. The inconsistency with generateMetadata (which correctly guards the same field) suggests this was an oversight rather than an intentional design choice.

Recommendation:

• Apply the same null-guard pattern used in generateMetadata:

const productJsonLd = {
  // ...
  image: product.featuredImage?.url,
  offers: {
    // ...
  },
};

• Alternatively, conditionally omit the image field from the JSON-LD object when featuredImage is absent:

...(product.featuredImage && { image: product.featuredImage.url }),

• Add a unit test that constructs productJsonLd with a product where featuredImage is null and asserts no exception is thrown (see CH-010).

Effort: Low (< 30 minutes)

SQALE Characteristic: Reliability

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

CH-008: No Differentiation Between "Not Found" and "API Error"

Severity: Minor Quality Sub-Characteristic: Fault Tolerance / Analysability Screen(s): Item Detail (/[page]), Product Detail (/product/[handle]), Search Detail (/search/[collection]) Component(s): app/[page]/page.tsx, app/product/[handle]/page.tsx, app/search/[collection]/page.tsx

Description: On all three screens that call notFound(), both a "resource not found in Shopify" condition and a "Shopify API network/infrastructure failure" condition result in the same notFound() call (or an unhandled exception that surfaces as a generic 500). Users and monitoring systems cannot distinguish between a legitimately missing page/product and a Shopify API outage from the rendered output. During an outage, users would see 404 pages for products that actually exist, which is misleading and could suppress incident detection.

Evidence:

• Item Detail (/[page]): §10 — "Both 'page not found' and 'API error' scenarios result in the same notFound() call, making it impossible for users or monitoring systems to distinguish between a missing page and a Shopify API outage." §17 — "No error differentiation."
• Product Detail (/product/[handle]): §10 — "If getProduct throws, Next.js will render the error boundary (error.tsx) if present."
• Search Detail (/search/[collection]): §10 — "Shopify API network failure: Unhandled at this level — would surface as an unhandled server exception."

Risk: During a Shopify API outage, product and content pages return 404 responses. This suppresses the true error signal, makes incident detection harder, and could cause SEO crawlers to de-index pages that are temporarily unavailable rather than permanently removed.

Recommendation:

• In lib/shopify, distinguish between a "not found" response (Shopify returns null data for a valid query) and a network/API error (thrown exception or non-200 HTTP status). Return a typed result or throw a typed error class.
• In page components, catch typed errors and call notFound() only for genuine 404 conditions; allow API errors to propagate to the error.tsx boundary, which can display a "temporarily unavailable" message.
• Example pattern:

// In page component
try {
  const page = await getPage(params.page);
  if (!page) notFound();
  // render...
} catch (err) {
  if (err instanceof ShopifyNotFoundError) notFound();
  throw err; // propagate to error.tsx
}

Effort: High (4–8 hours, primarily in lib/shopify to introduce typed error classes)

SQALE Characteristic: Reliability

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

CH-009: No Observability SDK Identifiable in Project Manifest

Severity: Minor Quality Sub-Characteristic: Analysability Screen(s): All five assessed screens Component(s): All page components; package.json

Description: No error tracking, application performance monitoring, or logging SDK is identifiable in the project manifest (package.json). No observability-related calls appear in any of the five documented screen files. This means that server-side rendering errors, Shopify API failures, and null-dereference crashes (such as CH-002) may go undetected until a user reports them.

Evidence:

• package.json: No packages matching common observability SDKs (e.g., @sentry/nextjs, @datadog/browser-rum, newrelic, @opentelemetry/sdk-node) appear in dependencies or devDependencies.
• §10 of every assessed screen: "No console.log, console.warn, console.error, error tracking service calls (Sentry, Datadog, etc.), or analytics event calls are present in this screen's component file."

Risk: Production errors on any of the five assessed routes will be invisible to the engineering team unless a user reports them or the team actively monitors server logs. The null-dereference bug in CH-002 is a concrete example of an error that would be silent without instrumentation.

Recommendation:

• Verify whether observability is configured at the infrastructure level (Vercel's built-in logging, a Next.js instrumentation hook in instrumentation.ts) before treating this as a gap. [Not documented — WHO: DevOps/platform engineer; WHAT: Is error tracking (e.g., Sentry, Datadog, Vercel observability) configured at the infrastructure or instrumentation.ts level?; WHERE: Insert confirmation or finding upgrade in this section.]
• If no instrumentation exists, add an error tracking SDK. For Next.js on Vercel, @sentry/nextjs or Vercel's native observability integration are the lowest-friction options.
• At minimum, ensure that unhandled server-side exceptions are captured and alerted on.

Effort: Medium (2–4 hours to integrate an SDK; Low if Vercel observability is already active)

SQALE Characteristic: Maintainability / Reliability

Source Evidence: All five assessed screens (§10); package.json

Security (Score: 4/5)

Overview

The security posture of the assessed screens is generally strong. All screens are React Server Components, which eliminates the risk of leaking server-side secrets to the client bundle. No user input is processed on any screen except as URL parameters passed to the Shopify API abstraction layer. The two findings below are a latent XSS vector in JSON-LD injection and a minor type-safety bypass in URL parameter handling (the latter is also captured under Maintainability as CH-003).

[Diagram: Security boundary diagram showing the RSC server boundary, lib/shopify abstraction layer, and Shopify Storefront API — illustrating where credentials are held and where user-supplied input enters the system]

CH-006: JSON.stringify Without HTML-Character Escaping in JSON-LD Injection

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

Description: The Product Detail page injects structured data into the page using dangerouslySetInnerHTML={{ __html: JSON.stringify(productJsonLd) }}. JSON.stringify does not escape HTML special characters such as <, >, &, or /. If a Shopify product's title, description, or any other field included in productJsonLd contains the sequence </script>, the browser's HTML parser will interpret it as closing the <script> tag, potentially allowing injected content to execute as JavaScript. While Shopify sanitizes merchant-authored content, this assumption is a single point of failure: a compromised Shopify account, a supply-chain issue in Shopify's content pipeline, or a future change to Shopify's sanitization policy would expose this vector.

Evidence: Product Detail (/product/[handle]): §14 — "JSON.stringify does not escape HTML special characters like <, >, or & by default, which could theoretically allow script injection if a product title or description contained </script> sequences. A safer approach would use a JSON serializer that escapes these characters."

Risk: If exploited, this could allow arbitrary JavaScript execution in the user's browser (XSS), enabling session hijacking, credential theft, or malicious redirects. The risk is currently mitigated by Shopify's content sanitization, but defense-in-depth requires that the application not rely solely on the upstream provider's sanitization.

Recommendation:

• Replace JSON.stringify with a serializer that escapes HTML special characters. A minimal, dependency-free approach:

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

• Use this function in place of JSON.stringify in the dangerouslySetInnerHTML call:

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

• This is a well-established pattern; the serialize-javascript npm package provides a battle-tested implementation if a dependency is acceptable.

Effort: Low (< 1 hour)

SQALE Characteristic: Security

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

CH-007: page.body HTML Rendered Without Application-Level Sanitization

Severity: Minor Quality Sub-Characteristic: Security — Integrity Screen(s): Item Detail (/[page]) Component(s): app/[page]/page.tsx, components/prose

Description: The page.body field — a raw HTML string authored in Shopify's admin — is passed directly to the Prose component via an html prop. The documentation notes that the Prose component likely uses dangerouslySetInnerHTML to render this content. No application-level HTML sanitization is applied before rendering. The safety of this pattern depends entirely on Shopify's server-side sanitization of page body content. This is a defense-in-depth gap: if Shopify's sanitization is bypassed (e.g., via a compromised merchant account or a Shopify platform vulnerability), the application has no secondary protection.

Evidence: Item Detail (/[page]): §14 — "The safety of this rendering depends entirely on the Prose component's implementation — if it uses dangerouslySetInnerHTML without sanitization, XSS is theoretically possible if Shopify's content pipeline is compromised. In practice, Shopify sanitizes page body content server-side, but this screen performs no additional sanitization."

Risk: Severity is rated Minor (not Critical) because: (a) Shopify's content sanitization is a well-established, actively maintained control; (b) the content is merchant-authored, not user-submitted; and (c) this is a server-rendered page with no client-side state that could be exfiltrated. The risk is real but requires a multi-layer compromise to exploit.

Recommendation:

• Verify the Prose component's implementation to confirm whether it uses dangerouslySetInnerHTML and whether any sanitization is applied. [Not documented — WHO: the developer who owns components/prose; WHAT: Does Prose use dangerouslySetInnerHTML? Is any HTML sanitization (e.g., DOMPurify) applied before rendering?; WHERE: Insert finding severity adjustment in this section based on the answer.]
• If Prose uses dangerouslySetInnerHTML without sanitization, consider adding a server-side sanitization step using a library such as isomorphic-dompurify before passing content to Prose.
• Document the trust assumption (Shopify sanitizes content) as an explicit comment in the code so future developers understand the security model.

Effort: Medium (2–4 hours to add sanitization; Low to add documentation comment)

SQALE Characteristic: Security

Source Evidence: Item Detail (/[page])

Performance Efficiency (Score: 3/5)

Overview

The RSC-first architecture is a strong performance foundation: zero client-side JavaScript on all five assessed screens, full-route caching via Next.js, and AVIF/WebP image optimization configured in next.config.ts. The three performance findings below are architectural gaps rather than implementation errors: the absence of pagination on product listing screens, the duplicate API call pattern (also captured as CH-001), and the missing loading skeleton for ProductDescription.

[Diagram: Data flow diagram for Product Detail page showing parallel vs. sequential fetch paths — getProduct (called twice), getProductRecommendations, and the Suspense streaming boundaries]

CH-005: No Pagination on Product Listing Screens

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

Description: Both product listing screens fetch and render all matching products in a single Shopify API request. Shopify's Storefront API caps results at 250 products per request. For stores with large catalogs or popular collections, this means: (a) the Shopify API response payload is large, (b) the server-rendered HTML is large, (c) the Time to First Byte increases proportionally with catalog size, and (d) the browser must parse and render a large DOM. No pagination, infinite scroll, or cursor-based loading is implemented at either screen level.

Evidence:

• Search (/search): §12 — "The getProducts call fetches all matching products in a single request. There is no pagination, infinite scroll, or virtual list implementation." §17 — "No pagination: All matching products are fetched and rendered in a single pass. For stores with large catalogs, this is a scalability concern."
• Search Detail (/search/[collection]): §12 — "The screen fetches and renders all products in the collection in a single request." §17 — "No pagination: All products are fetched and rendered in a single request."

Risk: For stores with more than ~50 products per collection or search result, page load times will degrade noticeably. At 250 products (Shopify's API limit), the rendered HTML and image loading will be substantial. This is a scalability cliff: the application works well for small catalogs but degrades predictably as the catalog grows.

Recommendation:

• Implement cursor-based pagination using Shopify's Storefront API pageInfo.hasNextPage and endCursor fields. This is the idiomatic Shopify pagination pattern.
• For the Search screen, implement URL-based pagination (e.g., ?page=2 or ?after=<cursor>) so paginated results are deep-linkable and server-rendered.
• For Search Detail, the same approach applies with the collection handle as the primary filter.
• As an interim measure, cap the number of products fetched in getProducts and getCollectionProducts to a reasonable limit (e.g., 24 or 48) and add a "Load More" or paginated navigation UI.

Effort: Very High (16+ hours to implement cursor-based pagination across both screens and the lib/shopify service layer)

SQALE Characteristic: Efficiency

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

CH-011: Missing Loading Skeleton for ProductDescription Suspense Boundary

Severity: Minor Quality Sub-Characteristic: Time Behaviour / Usability Screen(s): Product Detail (/product/[handle]) Component(s): app/product/[handle]/page.tsx — ProductDescription Suspense boundary

Description: The Suspense boundary wrapping ProductDescription uses fallback={null}, meaning no placeholder UI is shown while the component resolves. The Gallery component correctly uses a blank square placeholder to prevent layout shift, but the right-side panel (title, price, variant selectors, add-to-cart) renders nothing during loading. On slow connections, the product image appears but the purchase UI is absent, which is disorienting and may cause users to believe the page is broken.

Evidence: Product Detail (/product/[handle]): §17 — "No loading feedback for ProductDescription: The Suspense fallback for ProductDescription is null, meaning users see nothing while the component loads. This could cause layout shift and a poor experience on slow connections."

Risk: On slow connections or during high server load, users see a product image with no title, price, or add-to-cart button. This degrades the purchase experience and may increase bounce rate on the most commercially important page in the application.

Recommendation:

• Implement a skeleton loading state for ProductDescription that mirrors the component's layout: a placeholder for the title (e.g., a gray rectangle), a placeholder for the price, and a disabled-state button placeholder.
• Use Tailwind's animate-pulse utility for the skeleton effect, consistent with the existing blank-square placeholder used for Gallery.
• Example:

<Suspense fallback={<ProductDescriptionSkeleton />}>
  <ProductDescription product={product} />
</Suspense>

Effort: Medium (1–3 hours to design and implement the skeleton component)

SQALE Characteristic: Usability / Efficiency

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

Functional Suitability (Score: 3/5)

Overview

The five screens implement their documented feature sets correctly. The two findings in this dimension are a missing page-level heading on Search Detail (a functional gap that affects both usability and SEO) and a hardcoded placeholder SEO description on the Home screen that should be replaced before production use.

CH-012: Search Detail Renders No Collection Heading

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

Description: The Search Detail page renders no <h1> or collection title in the page body. The collection name appears only in the browser tab title (via generateMetadata), but the page body contains only a product grid or an empty-state message. Users have no visual confirmation of which collection they are viewing. This is both a functional gap (users cannot confirm their navigation context) and an accessibility issue (no page heading for screen readers).

Evidence: Search Detail (/search/[collection]): §17 — "No collection heading rendered: The page body renders no <h1> or collection title, which is both an accessibility concern (no page heading) and a UX gap (users have no visual confirmation of which collection they are viewing beyond the browser tab title)."

Risk: Users who navigate to a collection page from a menu or search filter have no on-page confirmation of their location. If the collection name is not visible in the surrounding navigation (e.g., on mobile where the nav is collapsed), the page context is entirely ambiguous. This also means the page has no <h1>, which is a significant SEO signal gap for collection pages.

Recommendation:

• Add a collection title heading to the page body. The getCollection call in generateMetadata already fetches the collection title; use React's cache() (see CH-001) to share this data with the page component without an additional API call.
• Render the collection title as an <h1> above the product grid:

<h1 className="text-2xl font-bold mb-6">{collection.title}</h1>

• If the collection has a description, consider rendering it below the heading for additional context and SEO value.

Effort: Low (< 1 hour, assuming CH-001 is addressed first to avoid a third getCollection call)

SQALE Characteristic: Functional Completeness

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

CH-013: Hardcoded Template Placeholder in Home Screen SEO Metadata

Severity: Minor Quality Sub-Characteristic: Functional Correctness Screen(s): Home (/) Component(s): app/page.tsx — metadata export

Description: The metadata export on the Home screen contains a hardcoded description string: "High-performance ecommerce store built with Next.js, Vercel, and Shopify." This is a generic stack description from the Next.js Commerce starter template, not a meaningful, store-specific SEO description. It will appear in Google search results and social media link previews for the store's homepage, presenting a technical description rather than brand or product copy.

Evidence: Home (/): §17 — "The description in the metadata export is hardcoded as a generic stack description ('High-performance ecommerce store built with Next.js, Vercel, and Shopify.') rather than a meaningful, store-specific SEO description. This is likely a placeholder from a starter template and should be updated with actual brand/store copy before production use."

Risk: Low technical risk. The business risk is that the store's homepage appears in search results with a developer-facing description rather than a customer-facing one, reducing click-through rates from organic search.

Recommendation:

• Replace the hardcoded description with a store-specific value sourced from an environment variable (e.g., SITE_DESCRIPTION) or from a Shopify shop metadata query.
• The SITE_NAME environment variable is already used in the same metadata export — apply the same pattern for description:

const { SITE_NAME, SITE_DESCRIPTION } = process.env;

export const metadata = {
  description: SITE_DESCRIPTION,
  // ...
};

Effort: Low (< 30 minutes)

SQALE Characteristic: Functional Correctness

Source Evidence: Home (/)

Usability (Score: 3/5)

Overview

The screens handle the most common empty and error states correctly (no-results messages, notFound() for missing resources). The usability findings below are a cluster of smaller gaps: a missing semantic <time> element, a <span> used where <strong> is semantically correct, and the missing ProductDescription loading skeleton (also captured under Performance as CH-011).

CH-014: Missing <time> Element for Machine-Readable Date

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

Description: The last-updated date on the Item Detail screen is rendered as a plain formatted string inside a <p> tag. The HTML <time> element with a datetime attribute is the semantically correct element for dates and times — it provides a machine-readable ISO 8601 timestamp alongside the human-readable display string, which assistive technologies, search engines, and browser extensions can consume.

Evidence: Item Detail (/[page]): §15 — "The Intl.DateTimeFormat date string is rendered as visible text only; there is no <time> element with a datetime attribute, which would be more semantically correct and machine-readable for assistive technologies." §17 — "No <time> element for the updated date."

Risk: Low. Screen readers can read the formatted date string. The gap is semantic correctness and machine-readability, not a functional failure.

Recommendation:

• Replace the plain string rendering with a <time> element:

<p className="text-sm italic">
  {`${page.title} 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>

• Note: this recommendation also addresses the locale-dependency finding (CH-015) by hardcoding 'en-US'.

Effort: Low (< 30 minutes)

SQALE Characteristic: Usability

Source Evidence: Item Detail (/[page])

CH-016: <span> Used for Semantic Emphasis Where <strong> Is Correct

Severity: Info Quality Sub-Characteristic: Usability / Accessibility Screen(s): Search (/search) Component(s): app/search/page.tsx — results summary paragraph

Description: The search term in the results summary paragraph is wrapped in <span className="font-bold"> for visual bold styling. The semantically correct element for text that has strong importance or emphasis is <strong>, which conveys semantic meaning to screen readers and search engines in addition to the visual weight. Using <span> with a CSS class achieves the visual effect but loses the semantic signal.

Evidence: Search (/search): §15 — "The search term is wrapped in <span className='font-bold'> — a presentational element. Using <strong> instead would convey semantic emphasis to screen readers."

Risk: Minimal. Screen readers will still read the search term; they simply will not announce it as emphasized. This is a best-practice gap, not a functional failure.

Recommendation:

• Replace <span className="font-bold"> with <strong> (which is bold by default in browsers, so the font-bold class may be removable, or can be retained for Tailwind reset compatibility):

<strong>{searchValue}</strong>

Effort: Low (< 15 minutes)

SQALE Characteristic: Usability

Source Evidence: Search (/search)

Compatibility (Score: 4/5)

Overview

The application targets modern browsers via the es2015 TypeScript compilation target and uses CSS features (Tailwind v4, container queries) that have broad modern browser support. One compatibility concern is identified: locale-dependent date rendering tied to the server's runtime locale.

CH-015: Locale-Dependent Date Rendering Tied to Server Runtime Locale

Severity: Minor Quality Sub-Characteristic: Co-existence / Adaptability Screen(s): Item Detail (/[page]) Component(s): app/[page]/page.tsx — date formatting

Description: The updatedAt date is formatted using new Intl.DateTimeFormat(undefined, { ... }). Passing undefined as the locale instructs the runtime to use the system/environment default locale. On a Vercel deployment, the Node.js runtime locale is typically en-US, but this is not guaranteed across all deployment environments, regions, or future infrastructure changes. If the server locale changes, the date format changes silently (e.g., from "January 15, 2024" to "15. Januar 2024"), which may be unexpected for an English-language storefront.

Evidence: Item Detail (/[page]): §8 — "Using undefined as the locale argument to Intl.DateTimeFormat ... may differ from the user's locale and could produce inconsistent output across deployment environments." §17 — "Locale-dependent date rendering: Using undefined as the locale for Intl.DateTimeFormat ties the date format to the server's runtime locale."

Risk: Low in practice on Vercel, but the behavior is environment-dependent and non-deterministic across deployment targets. A future infrastructure change or multi-region deployment could produce inconsistent date formats.

Recommendation:

• Hardcode the locale to 'en-US' (or the store's primary language) to make the output deterministic:

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

• If the store needs to support multiple locales, derive the locale from the request's Accept-Language header or a locale context, rather than relying on the server default.

Effort: Low (< 15 minutes)

SQALE Characteristic: Portability / Compatibility

Source Evidence: Item Detail (/[page])

Portability (Score: 4/5)

Overview

The application is well-positioned for portability: the Shopify integration is cleanly abstracted behind lib/shopify, environment variables are server-only, and the RSC architecture avoids client-side framework lock-in. One portability concern is the use of three experimental Next.js features in next.config.ts on a canary release.

CH-017: Canary Next.js Version with Three Experimental Flags

Severity: Minor Quality Sub-Characteristic: Installability / Adaptability Screen(s): All five assessed screens Component(s): next.config.ts, package.json

Description: The project uses next: "15.6.0-canary.60" — a canary (pre-release) build of Next.js — with three experimental flags enabled: ppr: true (Partial Prerendering), inlineCss: true, and useCache: true. Canary releases are not production-stable; APIs, behavior, and configuration options can change between canary versions without a semver major bump. The useCache API in particular is documented as experimental and subject to change. Running a canary build in production means the application may break on a routine pnpm update if the canary API surface changes.

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

Risk: Moderate upgrade risk. If the team updates Next.js (e.g., to a newer canary or to the stable 15.x release), any of the three experimental APIs could have breaking changes. The useCache API is the highest-risk flag as it is the newest and most likely to change. This is not an immediate production risk if the version is pinned, but it creates upgrade debt.

Recommendation:

• Pin the exact canary version in package.json (use "15.6.0-canary.60" without the ^ caret) to prevent accidental upgrades.
• Track the Next.js 15 stable release timeline and plan a migration from canary to stable once the experimental APIs are promoted.
• Document the rationale for each experimental flag in next.config.ts with a comment explaining what it enables and when it can be removed.
• Monitor the Next.js changelog for breaking changes to ppr, inlineCss, and useCache before any upgrade.

Effort: Low (< 1 hour to pin and document; Medium for the eventual stable migration)

SQALE Characteristic: Portability

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

Technical Debt Inventory

Finding Inventory

Needs Verification

The following findings are based on inference from technology patterns or incomplete documentation evidence. They are not counted in severity totals and are not scheduled in the Remediation Roadmap. Each requires a specific verification action before it can be promoted to the main Finding Inventory.

Remediation Roadmap

Phase 1: Immediate (This Sprint)

Phase 2: Short-Term (30 Days)

Phase 3: Medium-Term (90 Days)

Phase 4: Long-Term (Backlog)

Positive Patterns

Screen Health Matrix

Note: Finding counts per screen reflect the number of findings where the screen is listed as an affected screen. Findings affecting all five screens (CH-009, CH-010, CH-017) are counted once per screen in this matrix.

Glossary

Quality Terms

Domain Terms

Technical Terms