# 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.