Architect — F-013 Storefront shell (Next.js)

Decision

Create a dedicated frontend package at project/storefront/. The backend remains the modular monolith package in project/; the storefront never imports project/src/** backend internals.

Package boundary

project/storefront/package.json owns Next.js, React, Tailwind and frontend scripts.
Root/backend lint can ignore storefront/**; storefront quality gates run inside project/storefront.
Frontend API access goes through project/storefront/src/lib/api.ts only.

Stack

Next.js App Router with TypeScript.
React Server Components by default.
Tailwind CSS for shell styling.
No client components in this slice unless unavoidable; home/layout can be server components.

API client

Add a typed public API client:

ProductSummary type mirrors public catalog response fields needed by the shell.
searchProducts(input) calls backend GET /products/search.
getProductBySlug(slug) calls backend GET /productos/:slug for future detail pages.
Backend base URL from NEXT_PUBLIC_API_BASE_URL or API_BASE_URL, default http://localhost:3000.
Client throws sanitized errors; no backend internals or DB types imported.

UI shell

App layout with top navigation and footer.
Home page renders server-side with navigation, hero, basic category/search affordances and a small product preview fed by the typed API client when backend is available.
If backend is unavailable, render a graceful empty state; build must not require a live backend.

Quality gates

Frontend commands:

npm run lint
npm run typecheck
npm run build

Root gates:

Existing backend npm run lint, npm run typecheck, npm test should remain green.
./scripts/verify.sh green.

Out of scope

No catalog detail pages, category pages, cart UI, checkout UI, authentication UI, SSG/ISR catalog behavior, or image optimization pipeline in this ticket.

1.9 KiB Raw Blame History