docs: add comprehensive repository review pack

docs/cursor/repository-review-2026-04-01/00-index.md

@@ -0,0 +1,108 @@
+# StormCom Repository Review Pack
+
+Date: 2026-04-01
+Repository: `stormcom`
+Reviewer mode: static code audit + partial runtime validation
+
+## Scope covered
+
+- `src/**` repository review, with emphasis on:
+  - App Router pages, layouts, loading/error boundaries
+  - API route handlers in `src/app/api/**`
+  - shared libraries, auth, permissions, security, and navigation
+- `prisma/**` schema and migration review
+- `package.json` and dependency usage cross-check
+- `next.config.ts`, `vercel.json`, auth, proxy, and environment setup review
+- `docs/cursor/**` cross-validation against the live codebase
+- targeted online research for:
+  - traceability matrix best practices
+  - CRUD matrix best practices
+  - architecture blueprint / interaction map best practices
+  - Next.js 16 + Prisma + PostgreSQL + Vercel best practices
+
+## Output files
+
+1. `01-environment-setup-and-validation.md`
+2. `02-routes-and-doc-cross-validation.md`
+3. `03-src-prisma-dependency-review.md`
+4. `04-security-issues-and-architecture-findings.md`
+5. `05-ui-walkthrough-findings-and-limitations.md`
+6. `06-traceability-matrix.md`
+7. `07-crud-matrix.md`
+8. `08-architecture-blueprint-interaction-map.md`
+9. `09-progress-blockers-and-next-steps.md`
+
+## Executive summary
+
+This repository is a large multi-tenant commerce SaaS built on Next.js App Router with:
+
+- 110 page routes under `src/app/**/page.tsx`
+- 291 API route modules under `src/app/api/**/route.ts`
+- 3 layouts, 7 loading boundaries, 7 error boundaries, and no explicit `not-found.tsx`
+- Prisma/PostgreSQL schema covering auth, organizations, stores, catalog, orders, subscriptions, webhooks, integrations, AI/chat, analytics, and landing pages
+
+## Key verified findings
+
+- Existing route docs in `docs/cursor/api-routes.md` and `docs/cursor/general/all-routes.md` are directionally strong, but they are not fully aligned with the current repository.
+- `npm run build` does **not** currently succeed end-to-end. It fails during prerendering of `/_not-found` after repeated React key warnings in the metadata/head rendering path.
+- Clean environment reproducibility is weak:
+  - local Docker was unavailable on this machine, so PostgreSQL could not be started from the committed `docker-compose.yml`
+  - `package-lock.json` is out of sync with `package.json`, so `npm ci` fails on a clean machine
+- The repo uses strong central patterns (`apiHandler`, Prisma singleton, NextAuth, proxy-based route protection), but also has important consistency gaps:
+  - stale Prisma helper selects
+  - duplicated subscription state in both `Store` and normalized subscription tables
+  - route naming overlap (`/api/store` vs `/api/stores`, `/api/subscription` vs `/api/subscriptions`, `/api/webhook` vs `/api/webhooks`)
+  - insecure/legacy security header defaults and CSP trade-offs
+  - TypeScript build errors are currently masked in production builds via `ignoreBuildErrors: true`
+
+## Important limitation
+
+The requested page-by-page live walkthrough as merchant/store owner could not be completed in this session because:
+
+1. the machine had no Docker binary available
+2. there was no native PostgreSQL server installed
+3. the app build currently fails before successful full route export
+
+Because of that, the walkthrough documentation records:
+
+- what was verified from code and test scaffolding
+- the seeded merchant credentials and Playwright auth flow
+- the exact blockers and the next commands to run on a machine with Postgres/Docker
+
+## Review methodology
+
+- Repository exploration across `src/**`, `prisma/**`, `docs/cursor/**`, root config, and tests
+- Route inventory from filesystem plus build log validation attempt
+- Prisma schema and migration review
+- Dependency-to-usage cross-check from `package.json` against repo search signals
+- Environment setup attempt on this machine
+- Current online research for RTM / CRUD matrix / architecture documentation best practices
+
+## Machine facts used during validation
+
+- OS: Linux 6.12
+- Node: `v22.22.1`
+- npm: `10.9.4`
+- Docker: not installed on this machine
+- Native PostgreSQL binaries (`psql`, `postgres`, `pg_ctl`, `initdb`): not installed on this machine
+
+## Primary evidence sources
+
+- `package.json`
+- `next.config.ts`
+- `vercel.json`
+- `proxy.ts`
+- `src/lib/auth.ts`
+- `src/lib/prisma.ts`
+- `src/lib/security.ts`
+- `src/lib/prisma-selects.ts`
+- `src/components/app-sidebar.tsx`
+- `prisma/schema.prisma`
+- `prisma/migrations/**`
+- `prisma/seed.mjs`
+- `playwright.config.ts`
+- `e2e/auth.setup.ts`
+- `docs/cursor/api-routes.md`
+- `docs/cursor/general/all-routes.md`
+- `docs/cursor/nav-permissions.md`
+

docs/cursor/repository-review-2026-04-01/01-environment-setup-and-validation.md

@@ -0,0 +1,227 @@
+# Environment Setup and Validation
+
+Date: 2026-04-01
+
+## Objective
+
+Set up a reproducible local development environment, validate the build, and establish whether the requested merchant walkthrough could be executed on this machine.
+
+## Verified repository setup inputs
+
+### Runtime and package manager
+
+- Node: `v22.22.1`
+- npm: `10.9.4`
+- Package manager in repo: npm (`package-lock.json` present, no pnpm/yarn lockfile)
+
+### Relevant scripts from `package.json`
+
+- `npm run dev` -> `next dev`
+- `npm run build` -> `node scripts/build.js`
+- `npm run start` -> `next start`
+- `npm run prisma:generate`
+- `npm run prisma:migrate:dev`
+- `npm run prisma:migrate:deploy`
+- `npm run prisma:seed`
+- `npm run test:e2e`
+
+### Local database path defined by repository
+
+The repo includes `docker-compose.yml` with:
+
+- service: `postgres`
+- image: `postgres:16-alpine`
+- database: `stormcom_dev`
+- user: `stormcom_user`
+- password: `stormcom_password_dev`
+- port: `5432`
+
+This is the intended local PostgreSQL bootstrap path.
+
+## Environment file prepared for validation
+
+A temporary local `.env.local` was created for build validation with these values:
+
+- `DATABASE_URL=postgresql://stormcom_user:stormcom_password_dev@localhost:5432/stormcom_dev`
+- `NEXTAUTH_URL=http://localhost:3000`
+- `NEXTAUTH_SECRET=dev-nextauth-secret-for-local-review-only-32chars`
+- `NEXT_PUBLIC_APP_URL=http://localhost:3000`
+- `NEXT_PUBLIC_APP_DOMAIN=localhost:3000`
+- `RESEND_API_KEY=re_dummy_key_for_local_review`
+- `EMAIL_FROM=noreply@example.com`
+- `SEARCH_ENGINE=postgres`
+
+This file was used only to probe environment behavior and should not be committed.
+
+## What succeeded
+
+### Dependency installation
+
+`npm install` succeeded.
+
+Observed notes:
+
+- deprecated stub: `@types/bcryptjs`
+- `npm audit --omit=dev` reported 3 low vulnerabilities
+
+### Prisma client generation
+
+`npm run prisma:generate` succeeded.
+
+Observed output:
+
+- Prisma schema loaded from `prisma/schema.prisma`
+- Prisma Client generated successfully
+
+## What failed or blocked execution
+
+### 1. Docker unavailable on machine
+
+The committed `docker-compose.yml` could not be used because the machine does not have a Docker binary installed.
+
+Observed result:
+
+- `docker compose up -d postgres` -> `docker: command not found`
+
+Impact:
+
+- local PostgreSQL could not be started from repo-provided infrastructure
+- migrations and seed execution could not be completed locally
+- authenticated merchant walkthrough could not be performed with real runtime data
+
+### 2. No native PostgreSQL server tools installed
+
+Checked binaries:
+
+- `psql`
+- `postgres`
+- `pg_ctl`
+- `initdb`
+
+None were available.
+
+Impact:
+
+- there was no alternate local PostgreSQL startup path after Docker failed
+
+### 3. `package-lock.json` is out of sync with `package.json`
+
+`npm ci` failed on a clean install.
+
+Observed error:
+
+- missing from lock file: `nodemailer@7.0.13`
+- missing from lock file: `magicast@0.3.5`
+
+Impact:
+
+- clean environment reproducibility is currently broken
+- CI or new developers using `npm ci` will fail unless the lockfile is regenerated and committed
+
+Severity:
+
+- High for reproducibility and CI confidence
+
+### 4. `npm run build` does not currently complete
+
+The build advanced through compile and partial prerendering, then failed.
+
+Observed build path:
+
+- compiled successfully
+- type validation skipped
+- static generation started
+- repeated React warnings about missing `key` props in top-level `meta`, `head`, `html`, and viewport-related render paths
+- final failure while prerendering `/_not-found`
+
+Observed terminal failure:
+
+- `Error occurred prerendering page "/_not-found"`
+- `TypeError: Cannot read properties of null (reading 'useState')`
+
+Impact:
+
+- route output from the final successful build table could not be captured from `npm run build`
+- deployment confidence is reduced
+- runtime walkthrough was blocked even before DB availability was solved
+
+## Additional validation notes
+
+### Build configuration observations
+
+From `next.config.ts`:
+
+- `reactCompiler: true`
+- `typescript.ignoreBuildErrors: true`
+- experimental `optimizePackageImports`
+
+Important implication:
+
+- production build is configured to skip TypeScript errors, so a green build would not guarantee type safety
+
+### Postinstall behavior mismatch
+
+`scripts/postinstall.js` reads `.env`, not `.env.local`.
+
+`scripts/build.js` reads `.env.local`.
+
+Impact:
+
+- local install and local build do not use the same environment file convention
+- Prisma generation may be skipped during install even when the project is otherwise configured in `.env.local`
+
+## Requested merchant/store-owner walkthrough status
+
+### Seeded credentials found in repository
+
+Merchant owner credentials are documented in:
+
+- `prisma/seed.mjs`
+- `README.md`
+- `e2e/auth.setup.ts`
+
+Verified merchant owner account:
+
+- email: `rafiq@techbazar.io`
+- password: `Owner@123456`
+
+### Playwright support exists
+
+The repo includes:
+
+- Playwright config
+- auth setup script
+- multiple merchant flow specs
+
+However, these could not be executed meaningfully here because:
+
+1. no Postgres runtime
+2. no seeded database
+3. build/runtime instability
+
+## Recommended environment fix order
+
+1. Install Docker or PostgreSQL locally
+2. Start database:
+   - preferred: `docker compose up -d postgres`
+3. Regenerate and commit `package-lock.json`
+4. Run:
+   - `npm run prisma:generate`
+   - `npm run prisma:migrate:dev`
+   - `npm run prisma:seed`
+5. Fix the `/_not-found` prerender failure
+6. Re-run:
+   - `npm run build`
+   - `npm run dev`
+   - `npx playwright test e2e/auth.setup.ts`
+7. Execute merchant walkthrough
+
+## Environment readiness verdict
+
+Current status: Partially prepared, not fully runnable.
+
+The repository can be statically audited and partially built, but full local execution is currently blocked by:
+
+- unavailable database runtime on this machine
+- lockfile drift
+- application build failure during prerender