Commerce — Codebase Health Scorecard

Document Title: Codebase Health Scorecard Date: May 2026 Assessment Basis: Documentation Review — 5 screens

Dimension Scores

1. Code Maintainability

Score: 4.0 / B. The codebase applies a consistent compositor pattern across all five screens — page components act as pure layout orchestrators with zero business logic, delegating data fetching and interactivity to named child components. TypeScript strict mode is enabled (strict: true, noUncheckedIndexedAccess: true in tsconfig.json), which enforces type safety across the codebase. The Shopify integration is cleanly abstracted behind lib/shopify, preventing API coupling from leaking into page components. The one recurring maintainability concern is the double-invocation of getProduct / getPage in both generateMetadata and the page component — documented in §17 of two screens — which should be resolved with React.cache(). Prettier is enforced via CI ("test": "pnpm prettier:check"), ensuring consistent formatting.

Evidence: tsconfig.json strict flags; §4 and §17 of Item Detail and Product Detail screens; package.json test script.

2. Reliability & Error Handling

Score: 3.0 / C. All five screens consistently call notFound() when Shopify returns a falsy value, providing a reliable 404 boundary for missing resources. However, no ErrorBoundary components wrap the Suspense blocks on Product Detail, meaning a rendering failure in Gallery or ProductDescription propagates to the root Next.js error boundary rather than being contained. A documented null-dereference bug exists: product.featuredImage.url in the JSON-LD block on Product Detail has no null guard, unlike the equivalent code in generateMetadata on the same screen. The Item Detail screen also conflates "page not found" and "API error" into a single notFound() call, making outage diagnosis harder. No error differentiation or structured error logging is present at the page-component level across any screen.

Evidence: §10 and §17 of Product Detail; §10 of Item Detail; §10 of Search and Search Detail.

3. Security Posture

Score: 4.0 / B. The Server Component architecture is the primary security strength: all Shopify API credentials remain server-side and are never included in the client bundle across all five screens. No screen accepts user-supplied data that is rendered without React's automatic JSX escaping — the one exception is the JSON-LD <script> block on Product Detail, which uses dangerouslySetInnerHTML with JSON.stringify. As documented in §14 of that screen, JSON.stringify does not escape <, >, or &, creating a theoretical script-injection vector if a product title contains </script>. The params.page and params.collection URL segments are passed directly to Shopify service functions without component-level sanitization, though parameterized GraphQL queries at the lib/shopify layer mitigate injection risk. CSP headers and rate limiting are not visible in the provided project context.

Evidence: §14 of all screens; §14 of Product Detail (JSON-LD); next.config.ts (no security headers configured); ROOT LAYOUT (no middleware visible).

4. Performance Efficiency

Score: 4.0 / B. The project configuration (next.config.ts) enables three experimental Next.js 15 performance features: Partial Pre-Rendering (ppr: true), inline CSS (inlineCss: true), and the new useCache API — all of which reduce TTFB and client bundle size. AVIF and WebP image formats are configured, and GridTileImage uses Next.js fill with responsive sizes. Suspense streaming boundaries on Product Detail allow the page shell to reach the browser before data-heavy components resolve. The primary performance gap is the absence of pagination on both the Search and Search Detail screens: all matching products are fetched in a single Shopify API call, which will degrade for large catalogs. The duplicate getProduct/getPage API calls (one per generateMetadata, one per page render) are a secondary concern that React.cache() would resolve.

Evidence: next.config.ts; §12 of Product Detail (Suspense, prefetch); §12 and §17 of Search and Search Detail (no pagination); §17 of Item Detail and Product Detail (double fetch).

5. Test Coverage & Quality

Score: 1.0 / F (Provisional). No co-located test files were found in any of the five documented screens. The package.json "test" script runs only prettier:check — there is no Jest, Vitest, Playwright, or Cypress configuration present in the project manifest. This means the project has no automated functional test coverage from the evidence available. Each screen's §16 provides a detailed recommended testing strategy (unit, integration, and E2E), indicating team awareness of the gap. All five screens document this absence explicitly.

Provisional score — grade-swing disclosure: This score is based on observable evidence in the 5 documented screens and the project manifest. If a test suite (e.g., a __tests__/, e2e/, or cypress/ directory) exists outside the per-screen files and is not reflected in package.json, the dimension would be rated D. Resolve before treating this dimension's grade as final.

[Not documented — WHO: Engineering lead; WHAT: Does a test directory (__tests__/, e2e/, cypress/, vitest.config.ts) exist in the repository outside the documented screen files?; WHERE: Update Test Coverage & Quality score and provisional disclosure above if yes.]

Evidence: §16 of all 5 screens; package.json scripts block (no test runner present).

6. Documentation Quality

Score: 4.0 / B. All five screens are documented to a high standard across 18 consistent sections covering UI layout, data flow, API calls, business rules, security, accessibility, testing strategy, and known issues. Known issues and technical debt are explicitly called out in §17 of every screen, demonstrating active team awareness rather than silent accumulation. The glossary sections are thorough and domain-appropriate. The primary gap is that the documentation covers page-level components only — child components (Gallery, ProductDescription, ThreeItemGrid, Carousel, lib/shopify) are referenced but not documented, meaning a developer must read multiple undocumented files to understand full screen behavior. The hardcoded SEO description placeholder noted in §17 of the Home screen is a minor content quality issue.

Evidence: §17 and §18 of all screens; §13 of all screens (undocumented child components); §17 of Home (placeholder metadata).

7. Architecture & Scalability

Score: 4.0 / B. The application uses Next.js 15 App Router with React Server Components throughout, which is the current industry-leading pattern for e-commerce storefronts. The Shopify integration is fully abstracted behind lib/shopify, enabling the API client to be swapped without touching page components. PPR (ppr: true) in next.config.ts enables static shell delivery with dynamic data streaming — a strong scalability pattern for high-traffic storefronts. The useCache experimental flag signals adoption of Next.js's next-generation caching model. The primary architectural gap is the absence of pagination on collection and search result pages, which creates a hard scalability ceiling for large catalogs. The lack of error boundaries at the component level is also an architectural concern for fault isolation.

Evidence: next.config.ts (PPR, useCache); ROOT LAYOUT (CartProvider, streaming cart); §4 of all screens (RSC pattern); §17 of Search and Search Detail (no pagination).

8. Dependency Health

Score: 4.0 / B. The dependency set is intentionally lean: 8 runtime dependencies covering the framework (Next.js, React), UI utilities (Headless UI, Heroicons, clsx), fonts (Geist), and toast notifications (Sonner). There are no heavy client-side data-fetching libraries, no redundant utility packages, and no deprecated dependencies. TypeScript 5.8, Tailwind CSS 4, and React 19 are all current major versions. The one notable risk is next: "15.6.0-canary.60" — a canary (pre-release) build of Next.js. Canary builds can introduce breaking changes between patch versions and are not recommended for production without a pinned upgrade strategy. The experimental flags (ppr, inlineCss, useCache) are tied to this canary channel and may change API shape before stable release.

Evidence: package.json dependencies and devDependencies; next.config.ts experimental flags.

9. Accessibility Compliance

Score: 2.0 / D. Multiple accessibility gaps are documented across the five screens. The most significant is the absence of an <h1> heading on the Search Detail screen (§17), leaving users without a page-level landmark. The Item Detail screen uses a plain <p> tag for the last-updated date rather than a semantic <time datetime="..."> element (§15, §17). The Search screen uses <span> for the bolded search term where <strong> would convey semantic emphasis to assistive technologies (§15). The Product Detail screen's Suspense fallbacks carry no aria-busy or role="status" attributes, providing no loading feedback to screen readers (§15). The ROOT LAYOUT correctly sets lang="en" on the <html> element, which is a positive baseline. Carousel accessibility (keyboard navigation, aria-live) is delegated to child components and not verifiable from the documented screens.

Evidence: §15 and §17 of Search Detail (missing h1); §15 and §17 of Item Detail (no <time>); §15 of Search (<span> vs <strong>); §15 of Product Detail (Suspense ARIA); ROOT LAYOUT (lang="en").

10. Operational Readiness

Score: 2.0 / D (Provisional). No observability SDK (error tracking, APM, or analytics) is identifiable from the project manifest (package.json) or ROOT LAYOUT. The ROOT LAYOUT mounts Sonner's <Toaster> for user-facing toast notifications and a <WelcomeToast> component, but these are UX features, not operational instrumentation. All five screens' §10 sections explicitly state that no error tracking service calls (Sentry, Datadog, etc.) are present at the page-component level. The "test" script in package.json runs only Prettier, confirming no CI test gate. Deployment target (Vercel) is referenced in screen documentation and implied by the Next.js configuration, which would provide platform-level logging, but no application-level instrumentation is visible.

Provisional score — grade-swing disclosure: This score is based on observable evidence in the 5 documented screens and the project manifest. If infrastructure-level observability (e.g., Sentry, Datadog, or a Next.js instrumentation file at instrumentation.ts) is configured outside the per-screen scope, the dimension would be rated C. Resolve before treating this dimension's grade as final.

[Not documented — WHO: DevOps / Platform engineer; WHAT: Is there an instrumentation.ts file, a Sentry DSN, or equivalent error-tracking configuration in the repository outside the documented screen files?; WHERE: Update Operational Readiness score and provisional disclosure above if yes.]

Evidence: package.json (no observability SDK); ROOT LAYOUT (Sonner only, no error SDK); §10 of all 5 screens (explicit "no error tracking" statements).

Arithmetic: Sum = 4.0 + 3.0 + 4.0 + 4.0 + 1.0 + 4.0 + 4.0 + 4.0 + 2.0 + 2.0 = 32.0. Scored 10 of 10 dimensions. Mean = 32.0 / 10 = 3.2. Grade = C (3.2 falls in the 3.0–3.4 range → C).

Overall Health Summary

╔══════════════════════════════════════════╗
║  OVERALL CODEBASE HEALTH: C             ║
║  Score: 3.2 / 5.0                        ║
║  Assessment Date: May 2026               ║
║  Screens Assessed: 5                     ║
║  Assessment Basis: Documentation Review  ║
╚══════════════════════════════════════════╝

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

[Diagram: radar/spider chart showing scores across all 10 health dimensions — Code Maintainability 4.0, Reliability 3.0, Security 4.0, Performance 4.0, Test Coverage 1.0, Documentation 4.0, Architecture 4.0, Dependency Health 4.0, Accessibility 2.0, Operational Readiness 2.0]

Executive Summary: The Commerce storefront demonstrates a technically strong foundation — consistent React Server Component architecture, a lean modern dependency set, and thorough per-screen documentation place it solidly above average across most quality dimensions. The critical gaps pulling the overall score to C are the complete absence of automated testing (no test runner in package.json), weak accessibility compliance across multiple screens, and no identifiable operational observability instrumentation. Immediate investment in a test suite and accessibility remediation would have the highest impact on production readiness; the architecture and security posture are already well-positioned for scale.

Screen Health Overview

[Diagram: heat map of screen health scores across 5 screens and 4 dimensions]

Top Risks

Top Strengths

Recommended Actions

Methodology

• Quality Model: ISO/IEC 25010:2023 — 10 dimensions adapted for executive reporting
• Scoring: 1–5 scale based on documentation evidence (not quantitative metrics)
• Assessment Type: Documentation-based review — not static analysis or runtime profiling
• Scope: 5 screens assessed: Home (/), Item Detail (/[page]), Product Detail (/product/[handle]), Search (/search), Search Detail (/search/[collection])
• Project context used: package.json, next.config.ts, tsconfig.json, postcss.config.mjs, app/layout.tsx — cited by file path where referenced
• Limitations: Scores reflect documented patterns in page-level components. Child components (Gallery, ProductDescription, ThreeItemGrid, Carousel), the lib/shopify service layer, and middleware are referenced but not assessed. Supplement with SonarQube, Lighthouse, and test coverage tools for quantitative confirmation.
• Grade scale:

• Assessability disclosure: 10 of 10 dimensions scored. 2 dimensions carry a grade-swing disclosure pending verification of external evidence. Provisional dimensions: Test Coverage & Quality, Operational Readiness. Both provisional scores are included in the aggregate Mean of 3.2.

Glossary