# Alqove Web — Next.js 15

App Router frontend for the Alqove marketplace.

## Route Groups

- `(buyer)` — Public marketplace: browse, search, item detail, cart, checkout, purchases
- `(seller)` — Store dashboard: listings, orders, settings, payouts (requires seller role)
- `(admin)` — Platform admin: stores, orders, users, settings (requires admin role)
- `(auth)` — Login, register, OAuth callback (minimal layout)
- `(storefront)` — Store-owned public websites at `/s/{slug}` and `/s/{slug}/{page}`. Themed from the store's own settings, with no marketplace nav — a store can point its own domain here and it should read as their site, not ours.
- `(checkin)` — Public QR check-in lane, served on its own subdomain

Each route group has its own layout.tsx providing appropriate navigation and context.

## Host-based routing (`src/proxy.ts`)

Next 16 renamed `middleware` → `proxy`; there is exactly one such file and both
host-routed lanes live in it:

- `checkin.alqove.com` serves only `/c/...`; everything else 404s.
- Any host that isn't an Alqove host is looked up against
  `GET /v1/storefronts/resolve` and, if it belongs to a store, rewritten to
  `/s/{slug}/*`. Resolutions (hits and misses) are cached for a minute in
  module scope. `NEXT_PUBLIC_PLATFORM_HOSTS` lists the hosts we serve ourselves.

Storefront links therefore have to work from two addresses at once. Use the
helpers in `components/storefront/links.ts`: `pagePath()` for links inside the
storefront and `marketplaceUrl()` for anything that leaves it (item and store
pages), which must be absolute or the proxy will rewrite it back.

## Conventions

### Components
- Server components by default (for SEO)
- Client components only when interactive (`'use client'` directive)
- Shared components in `src/components/`
- Page-specific components colocated with the page

### State Management
- **TanStack Query** for server state (API data, caching, invalidation)
- **Zustand** for client state (cart + auth only)
- No Redux, no Context API for state

### Styling
- Tailwind CSS utility classes
- Design tokens from `@alqove/design-tokens`
- shadcn/ui component library (added as needed)

### API Consumption
- Import `@alqove/api-client` — never write raw fetch calls
- Types from `@alqove/types` — auto-generated from OpenAPI spec
- Shared hooks from `@alqove/shared`

### Naming
- Pages: `page.tsx` (Next.js convention)
- Layouts: `layout.tsx`
- Components: PascalCase (`ItemCard.tsx`)
- Hooks: camelCase with `use` prefix (`useCart.ts`)
- Utilities: camelCase (`formatPrice.ts`)

## Commands

```bash
npm run dev      # Start dev server (localhost:3000)
npm run build    # Production build
npm run lint     # Run ESLint
```