Commerce — Codebase Health Scorecard

Document Title: Codebase Health Scorecard

April 2026

╔══════════════════════════════════════════╗
║  OVERALL CODEBASE HEALTH: B             ║
║  Score: 3.5 / 5.0                        ║
║  Assessment Date: April 2026             ║
║  Screens Assessed: 4                     ║
║  Assessment Basis: Documentation Review  ║
╚══════════════════════════════════════════╝

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

[Diagram: radar/spider chart showing scores across all 10 health dimensions]

Executive Summary: The Commerce storefront is a well-structured Next.js/Shopify application that demonstrates strong architectural discipline — consistent use of React Server Components, clean separation of concerns via a lib/shopify service layer, and appropriate public-access patterns for a read-only catalog. The primary risks are concentrated in reliability and operational readiness: no error boundaries, no observability instrumentation, and no confirmed test suite leave the application exposed to silent failures in production. The most impactful near-term investment is adding error boundaries (error.tsx), structured logging, and a test harness; these three actions would materially improve the B grade toward an A.

Dimension Scores

Overall Score: 3.5 / 5.0 — Grade B

Dimension Detail

1. Code Maintainability — 4.0 / B 🟢

(Based on documentation review) All four screens follow a consistent architectural pattern: async React Server Components, searchParams/params awaited at the top of the component, data fetched via the lib/shopify service layer, and conditional rendering driven by data presence. Component responsibilities are clearly separated — page files compose child components rather than embedding logic, and business rules (sort resolution, pluralization, 404 guards) are small and well-scoped. The repeated searchParams as { [key: string]: string } unsafe cast across the Search and Search Detail screens is a minor consistency debt. The lib/shopify abstraction layer prevents Shopify GraphQL details from leaking into page components, which is a strong maintainability signal.

Evidence: Consistent RSC pattern across all four page.tsx files; lib/shopify service layer used uniformly; sort fallback logic duplicated identically in /search and /search/[collection].

2. Reliability & Error Handling — 2.5 / D 🔴

(Based on documentation review) No page component on any of the four screens contains a try/catch block, an error.tsx boundary reference, or a React <ErrorBoundary>. API failures in getProducts, getPage, getProduct, or getCollectionProducts will propagate as unhandled server-side exceptions, falling through to Next.js's default error page with no user-friendly messaging. The notFound() guard is applied correctly for missing resources, and conditional rendering handles empty states cleanly — these are positive reliability signals. However, the complete absence of error observability (no Sentry, Datadog, or equivalent) means production failures would be invisible until users report them.

Evidence: §10 of all four screens explicitly documents "No explicit error handling" and "No logging or monitoring"; notFound() usage documented in §10 of Item Detail, Product Detail, and Search Detail.

3. Security Posture — 3.5 / B 🟡

(Based on documentation review) The security fundamentals are sound: all Shopify API credentials are server-only environment variables, no sensitive data is rendered on any screen, all pages are read-only GET operations (no CSRF surface), and React JSX auto-escaping prevents XSS for user-supplied search terms. The dangerouslySetInnerHTML usage for JSON-LD on the Product Detail screen is low-risk given the Shopify-controlled data source, but lacks explicit sanitization. The searchParams as { [key: string]: string } type cast on the Search and Search Detail screens is the most consistent security-adjacent gap: a URL with array-valued parameters (e.g., ?q=a&q=b) could produce unexpected behavior in the Shopify query layer. The Prose component's HTML rendering security depends on its implementation, which is not documented here.

Evidence: §14 of all screens; dangerouslySetInnerHTML noted in Product Detail §14; unsafe cast documented in Search §17 and Search Detail §17; Prose HTML rendering noted in Item Detail §14.

4. Performance Efficiency — 3.0 / C 🟡

(Based on documentation review) The application makes good use of Next.js performance primitives: all screens are React Server Components (zero client JS for page shells), the Product Detail screen uses <Suspense> for streaming SSR, and related product links use prefetch={true}. However, no screen implements pagination, infinite scroll, or virtual lists — all matching products or collection items are fetched and rendered in a single pass, which is a documented scalability risk for large catalogs. The duplicate getProduct/getPage API calls in generateMetadata and the page component (on Product Detail and Item Detail) may result in redundant Shopify API requests if Next.js fetch deduplication does not apply. Caching configuration is entirely opaque, delegated to lib/shopify internals not covered in this documentation.

Evidence: No pagination documented on any screen (§12 and §17 of Search, Search Detail, Product Detail); duplicate API call pattern in Item Detail §17 and Product Detail §17; Suspense streaming in Product Detail §11; prefetch={true} in Product Detail §6.

5. Test Coverage & Quality — 1.5 / F 🔴

(Based on documentation review) No existing test files are referenced or imported in any of the four screens assessed. All four screens explicitly state "No existing tests are referenced in the source code provided." Each screen's documentation does include a well-structured §16 Testing Approach with unit, integration, and E2E test recommendations — this demonstrates team awareness of what should be tested, which is a positive signal, but the absence of any implemented tests is a critical gap. The test strategies documented are appropriate and actionable (mocking getProducts, verifying notFound() behavior, E2E navigation flows), meaning the path to coverage is clear once prioritized.

Evidence: §16 of all four screens explicitly states no existing tests; test approach sections are present and detailed in all four screens.

6. Documentation Quality — 4.5 / A 🟢

(Based on documentation review) The per-screen documentation is exceptionally thorough, covering all 18 sections including data flow, business rules, security considerations, accessibility gaps, known issues, and testing approach for every screen. Known issues are explicitly catalogued in §17 of each screen, demonstrating active team awareness of technical debt. The documentation is consistent in structure and depth across all four screens, suggesting a disciplined documentation practice. Minor gaps include the absence of documented CI/CD pipeline details, deployment configuration, and caching strategy specifics (all delegated to lib/shopify internals). The hardcoded SEO description on the Home screen is flagged in §17, which is a good example of the documentation's honesty.

Evidence: All 18 sections populated across all four screens; §17 Known Issues present and specific on all screens; Home §17 flags hardcoded SEO description.

7. Architecture & Scalability — 4.0 / B 🟢

(Based on documentation review) The architecture is clean and idiomatic for a Next.js 15 App Router application: RSC-first rendering, a centralized lib/shopify service layer abstracting all Shopify GraphQL calls, shared component libraries (components/grid, components/layout), and URL-driven state (no client-side state management library needed). The Home screen's composition-only pattern (delegating all data fetching to child components) is a good scalability pattern. The primary architectural scalability concern is the absence of pagination across all product listing screens — as catalog size grows, single-pass fetches will degrade. The duplicate API call pattern (calling getProduct/getPage in both generateMetadata and the page component) is a minor architectural inconsistency that React cache() would resolve.

Evidence: RSC pattern consistent across all screens; lib/shopify abstraction documented in §5 and §13 of all screens; no pagination on any screen (§12); duplicate call pattern in Item Detail §17 and Product Detail §17.

8. Dependency Health — 3.5 / B 🟡

(Based on documentation review) Direct dependencies in page-level files are minimal and appropriate: Next.js framework utilities (next/link, next/navigation), React (Suspense), and internal modules only. No third-party UI libraries, data-fetching libraries, or utility packages are imported directly in any of the four page components. The Shopify integration is fully encapsulated in lib/shopify, which is a healthy dependency boundary. The risk is opacity: the internal implementation of lib/shopify (including which Shopify SDK version, HTTP client, and caching strategy it uses) is not documented in any of the four screens, making it impossible to assess the health of the most critical dependency from this documentation alone.

Evidence: §13 of all screens documents "no third-party packages imported directly"; lib/shopify encapsulation noted consistently; SDK/client details not documented.

[Not documented — WHO: the tech lead or library owner for lib/shopify; WHAT: What Shopify Storefront API client library (if any) is used, what version, and are there known CVEs or deprecation notices?; WHERE: Insert in Dependency Health dimension section above.]

9. Accessibility Compliance — 2.5 / D 🔴

(Based on documentation review) Semantic HTML is used appropriately where it appears in page-level code: <h1> for page titles, <p> for descriptive text, <ul>/<li> for related product lists, and <section> for content regions. However, documented accessibility gaps are consistent and significant across screens: no aria-live regions for dynamic result count announcements (Search), no <time datetime="..."> element for machine-readable dates (Item Detail), no ARIA attributes on Suspense loading fallbacks (Product Detail), and no role="status" on empty-state messages (Search Detail). The Carousel component on the Home screen is flagged as a known accessibility risk but its implementation is not documented. Accessibility compliance for rendered content depends heavily on child components (Prose, ProductGridItems, Gallery) whose implementations are not covered in this documentation.

Evidence: §15 Known Accessibility Gaps documented on all four screens; aria-live absence in Search §15; <time> element gap in Item Detail §15 and §17; Suspense fallback gap in Product Detail §15; Carousel risk in Home §15.

10. Operational Readiness — 2.0 / D 🔴

(Based on documentation review) No screen contains any logging, error tracking, or analytics instrumentation at the page level. All four screens explicitly document the absence of console.log, console.warn, console.error, Sentry, Datadog, or equivalent calls. No loading.tsx files are referenced for any route, meaning slow Shopify API responses may produce blank or stalled pages. No error.tsx boundaries are referenced. The caching and revalidation strategy is entirely undocumented at the page level (delegated to lib/shopify). CI/CD pipeline, deployment configuration, and environment variable management are not documented in any screen.

Evidence: §10 of all four screens explicitly states no logging or monitoring; loading.tsx absence noted in Search §17; error.tsx absence noted in Search §17 and Product Detail §17.

[Not documented — WHO: the engineering manager or DevOps lead; WHAT: What CI/CD pipeline, deployment process, and environment variable management strategy is in place?; WHERE: Insert in Operational Readiness dimension section above.]

[Not documented — WHO: the tech lead; WHAT: Are error.tsx and loading.tsx files defined at the app directory level, even if not at the route level?; WHERE: Insert in Operational Readiness dimension section above.]

Screen Health Overview

[Diagram: heat map of screen health scores across all four screens and five dimensions]

⚠️ This workflow continues beyond the documented screens. Steps involving cart management, checkout, account authentication, and order confirmation are not covered in this document. Verify the complete purchase workflow with the development team before treating this as a comprehensive process description.

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); 0.5 increments used where evidence supports a between-grade assessment
• Assessment Type: Documentation-based review — not static analysis, runtime profiling, or CI/CD metrics
• Scope: 4 screens assessed: Home (/), Search (/search), Search Detail (/search/[collection]), Item Detail (/[page]), Product Detail (/product/[handle])
• Known Issues Credit: Explicitly documented issues in §17 of each screen were factored positively into Maintainability and Documentation Quality scores, as they demonstrate active team awareness
• Limitations: Scores reflect documented patterns only. Child component implementations (Gallery, ProductDescription, Carousel, ThreeItemGrid, Prose, ProductGridItems), the lib/shopify service layer internals, CI/CD configuration, and runtime behavior are not covered in the source documentation. Supplement with SonarQube, Lighthouse, and test coverage tools for quantitative confirmation.

Glossary

Quality Dimensions

Grade Scale

Technical Terms