Review docs

Author: rezwana-karim

docs/reviews/INDEX.md

@@ -0,0 +1,46 @@
+# StormCom Code Review Index
+
+Date: 2025-11-10
+Branch: copilot/sub-pr-50
+
+This index links to categorized review summaries generated for the Next.js 16 multi-tenant e‑commerce application. Each document contains per-file notes using a consistent rubric (architecture, Next.js 16 compliance, multi-tenancy, security, performance, accessibility, testing, size limits).
+
+- Architecture Overview: ./architecture-overview.md
+- Database Schema: ./database/prisma-schema.md
+- App Router: ./app.md
+- Components
+  - Analytics: ./components/analytics.md
+  - Attributes: ./components/attributes.md
+  - Audit Logs: ./components/audit-logs.md
+  - Auth: ./components/auth.md
+  - Brands: ./components/brands.md
+  - Bulk Import: ./components/bulk-import.md
+  - Categories: ./components/categories.md
+  - Checkout: ./components/checkout.md
+  - GDPR: ./components/gdpr.md
+  - Integrations: ./components/integrations.md
+  - Layout: ./components/layout.md
+  - Orders: ./components/orders.md
+  - Products: ./components/products.md
+  - Storefront: ./components/storefront.md
+  - Stores: ./components/stores.md
+  - Theme: ./components/theme.md
+  - UI: ./components/ui.md
+  - Root (theme-provider): ./components/root.md
+- Libraries (lib): ./lib.md
+- Services: ./services.md
+- Hooks: ./hooks.md
+- Contexts: ./contexts.md
+- Providers: ./providers.md
+- Emails: ./emails.md
+- Types: ./types.md
+
+Review Rubric (applies to every file):
+- Next.js 16 compliance (async params/searchParams; cookies/headers/draftMode as async; Proxy usage)
+- Server vs Client boundaries (no client-only APIs in server components; 'use client' where needed)
+- Multi-tenancy (storeId filtering, soft delete awareness)
+- Validation & security (Zod, auth checks, CSRF, rate limiting, secrets handling)
+- Performance (select fields, Suspense/loading, caching, bundle size, N+1 avoidance)
+- Accessibility (WCAG AA, ARIA, focus rings, contrast, keyboard support)
+- Testing (unit/integration coverage hints, E2E critical paths)
+- Size limits (file < 300 lines, function < 50 lines)

docs/reviews/app.md

@@ -0,0 +1,66 @@
+---
+title: App Router Review
+sourcePath: src/app
+category: app
+riskLevel: medium
+---
+
+# App Router Review
+
+Overview:
+- Next.js 16 App Router with route groups `(auth)`, `(dashboard)`, and storefront under `shop/`.
+- Global files: `layout.tsx`, `page.tsx`, `error.tsx`, `loading.tsx`, `not-found.tsx`, `globals.css` present.
+- API routes: Extensive coverage under `src/app/api/*` (products, categories, brands, checkout, analytics, auth/MFA, inventory, webhooks, integrations, GDPR, notifications, stores, subscriptions, docs, csrf, dev helpers).
+
+Global Layout (src/app/layout.tsx):
+- Uses Inter font, includes Vercel Analytics and Speed Insights.
+- Wraps app with `SessionProvider` (client) and `ThemeProvider` (client) inside body—OK for server layout composing client providers.
+- Recommendation: Verify providers are minimal in client surface and avoid heavy client dependencies at root; ensure no client-only code leaks into other server components.
+
+Route Groups:
+- (auth): login, register, forgot-password, reset-password, mfa/enroll, mfa/challenge.
+  - Expectations: Client forms with server actions or API calls, Zod validation, no SSR-disabled dynamic in server components.
+- (dashboard): dashboard, products (list, [id], loading/error states), orders (list, [id]), categories, brands, attributes, inventory, marketing, analytics, integrations, settings (theme, privacy), stores (list, [id], new), subscription (plans, billing).
+  - Expectations: Server Components for data display; interactive tables/forms via client components. All tenant queries filtered by session.storeId; respect soft delete; use loading.tsx skeletons.
+- Storefront (shop): home, products (list, [slug]), categories ([slug]), cart, checkout, orders, profile, search, wishlists.
+  - Expectations: Predominantly Server Components with client components for cart/checkout interactions; caching strategy for catalog pages (consider cache tags and cacheLife profiles).
+
+API Routes (high-level checks to apply per file):
+- Must use Next.js 16 patterns: `const { id } = await params;` and async `cookies()/headers()` if used.
+- Validate inputs with Zod and return standard { data | error } response shape.
+- Enforce auth (NextAuth session) and tenant isolation (storeId) where applicable.
+- Apply rate limiting to sensitive endpoints; add audit logs for admin mutations.
+
+File inventory captured (partial listing; see route-list.md for full):
+- Global: page.tsx, layout.tsx, error.tsx, loading.tsx, not-found.tsx, globals.css
+- Storefront pages: shop/page.tsx, shop/products/page.tsx, shop/products/[slug]/page.tsx, shop/categories/[slug]/page.tsx, shop/cart/page.tsx, shop/checkout/page.tsx, shop/orders/[id]/confirmation/page.tsx, shop/orders/page.tsx, shop/profile/page.tsx, shop/search/page.tsx, shop/wishlists/page.tsx
+- (auth): (auth)/login/page.tsx, register/page.tsx, forgot-password/page.tsx, reset-password/page.tsx, mfa/enroll/page.tsx, mfa/challenge/page.tsx
+- (dashboard): layout.tsx, dashboard/page.tsx, products/page.tsx, products/[id]/page.tsx, products/loading.tsx, products/error.tsx, orders/page.tsx, orders/[id]/page.tsx, orders/loading.tsx, orders/error.tsx, categories/page.tsx, brands/page.tsx, attributes/page.tsx, attributes/loading.tsx, inventory/page.tsx, inventory/loading.tsx, analytics/page.tsx, analytics/sales/page.tsx, analytics/customers/page.tsx, marketing/campaigns/page.tsx, marketing/coupons/page.tsx, settings/page.tsx, settings/theme/page.tsx, settings/privacy/page.tsx, settings/privacy/privacy-settings-client.tsx, stores/page.tsx, stores/new/page.tsx, stores/[id]/page.tsx, audit-logs/page.tsx, integrations/page.tsx, subscription/plans/page.tsx, subscription/billing/page.tsx
+- API routes: see below sections by domain.
+
+Recommendations (global):
+- Ensure all pages import only what they need; heavy charts and editors should be client-only and dynamically imported inside client components, not server parents.
+- Confirm Next.js 16 async param usage across dynamic routes ([slug]/[id]).
+- Provide loading.tsx where lists or detail pages fetch data; prefer Suspense in composite pages.
+- For storefront, consider cache strategies with cache tags for products, categories, brands; invalidate on admin mutations.
+
+Appendix: API endpoints list (from inventory)
+- products: /api/products, /api/products/[id], /api/products/export, /api/products/import, /api/products/[id]/stock, /api/products/[id]/stock/check, /api/products/[id]/stock/decrease
+- categories: /api/categories, /api/categories/[id], /api/categories/[id]/move, /api/categories/reorder
+- brands: /api/brands, /api/brands/[id], /api/brands/[id]/products
+- attributes: /api/attributes, /api/attributes/[id], /api/attributes/[id]/products
+- orders: /api/orders, /api/orders/[id], /api/orders/[id]/status, /api/orders/[id]/invoice
+- checkout: /api/checkout/validate, /api/checkout/payment-intent, /api/checkout/complete, /api/checkout/shipping
+- auth: /api/auth/login, /api/auth/logout, /api/auth/register, /api/auth/forgot-password, /api/auth/reset-password, /api/auth/[...nextauth], /api/auth/mfa/*, /api/auth/custom-session, /api/auth/test
+- analytics: /api/analytics/dashboard, /api/analytics/sales, /api/analytics/customers, /api/analytics/products, /api/analytics/revenue
+- inventory: /api/inventory, /api/inventory/adjust
+- notifications: /api/notifications, /api/notifications/[id]/read
+- stores: /api/stores, /api/stores/[id], /api/stores/[id]/admins, /api/stores/[id]/theme
+- subscriptions: /api/subscriptions, /api/subscriptions/[storeId], /api/subscriptions/[storeId]/cancel, /api/themes
+- webhooks: /api/webhooks/stripe, /api/webhooks/stripe/subscription
+- integrations: /api/integrations/* (shopify/mailchimp connect/export/disconnect)
+- emails: /api/emails/send
+- docs: /api/docs
+- csrf: /api/csrf-token
+- dev: /api/dev/* (session-info, create-session, echo-cookies)
+- GDPR: /api/gdpr/export, /api/gdpr/delete, /api/gdpr/consent

docs/reviews/architecture-overview.md

@@ -0,0 +1,25 @@
+# Architecture Overview
+
+This document summarizes the project structure and counts per category, based on repository scan at 2025-11-10.
+
+Top-level categories under `src/` with file counts (approximate):
+- app/: 136 files
+- components/: 83 files
+- lib/: 34 files
+- services/: 30 files
+- hooks/: 6 files
+- contexts/: 1 file
+- providers/: 1 file
+- emails/: 4 files
+- types/: 5 files
+
+Key conventions observed:
+- Next.js 16 App Router present with route groups (auth, dashboard, storefront) and extensive API routes under `src/app/api/*`.
+- Server Components by default; Client Components explicitly marked with `'use client'` in select hooks, providers, and UI components.
+- Multi-tenant boundaries enforced in Prisma schema (extensive storeId indexes) and mirrored in services.
+- Tailwind and Radix UI used; global styles at `src/app/globals.css`.
+
+Recommendations:
+- Keep files under 300 lines and functions under 50 lines; refactor large components into smaller composables.
+- Ensure App Router pages and route handlers use Next.js 16 async patterns (await params, await searchParams; cookies/headers/draftMode now async).
+- Maintain 70%+ Server Components; minimize client bundle by isolating client-only interactivity.

docs/reviews/components/analytics.md

@@ -0,0 +1,42 @@
+---
+title: Components – Analytics
+category: components/analytics
+files:
+  - analytics-dashboard.tsx
+  - analytics-date-picker.tsx
+  - revenue-chart.tsx
+  - sales-revenue-chart.tsx
+  - sales-report.tsx
+  - sales-metrics-cards.tsx
+  - metrics-cards.tsx
+  - top-products.tsx
+  - top-products-table.tsx
+  - top-products-chart.tsx
+  - customer-metrics.tsx
+  - customer-metrics-chart.tsx
+riskLevel: medium
+---
+
+# Analytics Components Review
+
+General Observations:
+- All files expected to be Client Components if they use charts, hooks, or interactivity; verify `'use client'` directive present where hooks (state, effects) are used.
+- Performance: Heavy chart components should leverage dynamic import with suspense boundaries inside client shells, not at server level.
+- Data Fetching: Prefer server-side data aggregation passed as props to minimize client data mass; use lean datasets.
+- Accessibility: Charts require textual summaries (ARIA live regions or descriptive text) for screen readers.
+- Multi-tenancy: Ensure analytics queries filter by storeId and respect soft deletion; avoid leaking cross-tenant aggregates.
+
+Per-File Notes (Heuristic):
+- analytics-dashboard.tsx: Likely orchestrates multiple metric cards—should split layout vs data fetching; server component parent + client metric cards is preferred.
+- analytics-date-picker.tsx: Ensure keyboard navigation, focus management, and proper aria-labels for date inputs.
+- revenue-chart.tsx / sales-revenue-chart.tsx / top-products-chart.tsx / customer-metrics-chart.tsx: Confirm canvas/svg elements have fallback textual descriptions. Avoid large bundle of charting libs; tree-shake.
+- sales-report.tsx: If generating tabular PDF/CSV export, do so server-side; avoid heavy client loops.
+- sales-metrics-cards.tsx / metrics-cards.tsx / customer-metrics.tsx: Keep each card small (<50 lines), use semantic elements (<section>, <h2>). Provide skeleton loading states.
+- top-products-table.tsx / top-products.tsx: Paginate tables; limit columns; ensure responsive design.
+
+Recommendations:
+1. Add explicit `<figure>` + `<figcaption>` for each chart for accessibility.
+2. Provide loading/error boundaries (Suspense + error boundary) wrapping chart components.
+3. Export pure data transformation utilities into `lib/analytics-utils.ts` to reduce duplication and improve testability.
+4. Add unit tests for data bucketing and sorting logic (e.g., top products, revenue grouping).
+5. Consider cache tags (e.g., `analytics:revenue`) for server-fetched aggregations to reduce recalculation.

docs/reviews/components/attributes.md

@@ -0,0 +1,23 @@
+---
+title: Components – Attributes
+category: components/attributes
+files:
+  - attribute-form.tsx
+  - attributes-filters.tsx
+  - attributes-table.tsx
+riskLevel: low
+---
+
+# Attribute Components Review
+
+Notes:
+- Forms: attribute-form.tsx should use controlled inputs, Zod validation server-side; client form should handle optimistic UI updates.
+- Filters/table: Ensure table is paginated and accessible (table headers <th>, sortable columns with aria-sort).
+- Multi-tenancy: All modify/read operations must filter attributes by storeId indirectly through products/categories if applicable.
+- Performance: Debounce filter inputs; avoid fetching large attribute lists at once.
+- Accessibility: Provide labels for filters, keyboard navigation in table.
+
+Recommendations:
+1. Add skeleton states for table loading.
+2. Add unit tests for value list normalization (e.g., parsing JSON arrays of attribute values).
+3. Ensure attribute-form enforces unique attribute names if required.

docs/reviews/components/audit-logs.md

@@ -0,0 +1,20 @@
+---
+title: Components – Audit Logs
+category: components/audit-logs
+files:
+  - audit-logs-table.tsx
+  - audit-logs-filters.tsx
+riskLevel: low
+---
+
+# Audit Logs Components Review
+
+Notes:
+- Read-only views; must be server-fetched and paginated.
+- Ensure filters (date range, user, action) debounce requests and use accessible controls.
+- Security: Mask sensitive changes; avoid displaying secrets.
+- Performance: Use indexed fields (createdAt, userId, entityType) as per schema; select necessary columns only.
+
+Recommendations:
+1. Add CSV export server-side with permission checks.
+2. Provide row-level details in a dialog with keyboard accessible triggers.

docs/reviews/components/auth.md

@@ -0,0 +1,20 @@
+---
+title: Components – Auth
+category: components/auth
+files:
+  - form-error.tsx
+  - form-success.tsx
+  - password-strength-indicator.tsx
+riskLevel: low
+---
+
+# Auth Components Review
+
+Notes:
+- Pure UI components; ensure no secrets exposed; provide clear aria-live regions for error/success messages.
+- Password-strength-indicator: Perform checks client-side only; do not transmit raw passwords beyond submission.
+- Internationalization: Ensure messages are translatable if i18n is planned.
+
+Recommendations:
+1. Add unit tests for strength indicator heuristics.
+2. Sanitize error content before rendering.

docs/reviews/components/brands.md

@@ -0,0 +1,20 @@
+---
+title: Components – Brands
+category: components/brands
+files:
+  - brands-table.tsx
+  - brands-filters.tsx
+  - brands-bulk-actions.tsx
+riskLevel: low
+---
+
+# Brand Components Review
+
+Notes:
+- Table: Paginated; ensure accessible sorting and selection for bulk actions.
+- Filters: Debounce; provide clear labels and ARIA descriptions; maintain state in URL params for deep linking.
+- Bulk actions: Confirm authorization (STORE_ADMIN only) and optimistic updates with server validation.
+
+Recommendations:
+1. Add integration tests for bulk publish/unpublish flows.
+2. Use Suspense boundaries around table data for streaming updates if applicable.

docs/reviews/components/bulk-import.md

@@ -0,0 +1,23 @@
+---
+title: Components – Bulk Import
+category: components/bulk-import
+files:
+  - bulk-import-upload.tsx
+  - bulk-import-templates.tsx
+  - bulk-import-history.tsx
+riskLevel: medium
+---
+
+# Bulk Import Components Review
+
+Notes:
+- Upload: Enforce file size/type restrictions; provide progress UI; use server-side streaming parse for scalability.
+- Templates: Offer downloadable sample CSV/JSON; keep versioning if schema evolves.
+- History: Paginate results; show status (success/partial/failed) with links to error reports.
+- Security: Sanitize filenames; prevent path traversal; scan content for malicious payloads.
+- Performance: Offload heavy parsing to worker/job queue; UI should poll or subscribe for status updates.
+
+Recommendations:
+1. Implement optimistic UI for job submission.
+2. Provide accessible status indicators (aria-live for completion).
+3. Add tests covering error handling for malformed files.

docs/reviews/components/categories.md

@@ -0,0 +1,19 @@
+---
+title: Components – Categories
+category: components/categories
+files:
+  - category-form.tsx
+  - categories-tree.tsx
+riskLevel: low
+---
+
+# Categories Components Review
+
+Notes:
+- Tree: Use accessible tree patterns (aria-expanded, role=tree); keyboard navigation for expand/collapse.
+- Form: Validate slug uniqueness per store; show preview URL.
+- Performance: Virtualize long trees; lazy load children.
+
+Recommendations:
+1. Include drag-and-drop reordering with keyboard fallback.
+2. Add unit tests for tree manipulation utilities.