# Winofy Frontend Guide

Internal engineering reference for the Winofy customer/seller web frontend. Source comments elsewhere in this repo (`errors.ts`, `proxy.ts`, `lib/location/client.ts`, ...) cite section numbers from this file directly — keep the numbering stable when editing.

## 1. Overview

Winofy is a Persian/Farsi (RTL) hyperlocal multi-vendor marketplace: customers browse nearby stores by neighborhood/city or GPS location, order products, and track deliveries; sellers manage their own storefront, products, and orders. This repo is the web frontend, built on Next.js 16 against two backends:

- **Winofy API** (Django/DRF) — stores, products, cart, checkout, orders, addresses, reviews. Staging: `https://winofy-staging.winsoo.ir/api`. **No CORS** — every call must happen server-side (Server Component, Server Action, or Route Handler), never directly from the browser.
- **Gooyal accounts** — the shared OAuth2 identity provider used across Winsoo group products, for phone + OTP login. Staging: `https://accounts-staging.gooyal.ir`. CORS is open there, so the login form calls it directly from the browser.

## 2. Tech stack

- Next.js 16.3.1, App Router, Turbopack, `output: "standalone"`
- React 19.2.8 / TypeScript 5 (`strict`)
- Tailwind CSS v4 (`@theme inline` token system — see §5)
- Radix UI primitives (dialog, select, tabs, toast, checkbox, label) + `class-variance-authority` / `tailwind-merge`, wrapped by the small `cn()`-based component layer in `src/components/ui/`
- `jose` — JWE encryption for the session cookie
- `lucide-react` — icon set
- `@tanstack/react-query` — the provider is wired in (`src/lib/query-provider.tsx` → `src/app/layout.tsx`), but nothing in the app calls `useQuery`/`useMutation` yet; all data currently comes from Server Components. The plumbing exists if you're the first to need client-side fetching.
- `zod` — installed, not yet used anywhere. Same note as above.

## 3. Getting started

Prereqs: Node 24 (matches the Docker image), npm.

```bash
git clone <repo>
cd winofy
npm install
cp .env.example .env.local   # fill in real values — ask a teammate for staging Gooyal credentials
npm run dev                  # http://localhost:3000
```

Scripts (`package.json`):

| Script | Runs |
|---|---|
| `npm run dev` | `next dev` (Turbopack) |
| `npm run build` | `next build` |
| `npm run start` | `next start` (the standalone build) |
| `npm run lint` | ESLint, flat config (`eslint-config-next`) |

No test runner is configured yet.

## 4. Architecture

### 4.1 Route structure

App Router route groups split the app by audience and auth requirement:

- `(auth)/login` — phone + OTP login (Gooyal)
- `(customer)/` — pages without the persistent shop header (home, location onboarding)
- `(customer)/(shop)/` — everything with the shop chrome: stores, products, cart, checkout, orders, addresses, profile
- `(seller)/seller` — seller-side dashboard (early stage)
- `src/proxy.ts` — Next 16's renamed `middleware.ts` (see §4.3)
- `src/app/api/*` — same-origin route handlers, used only where the browser needs to call something itself (session probe, logout, the neighborhood-search proxy — see §4.6)

### 4.2 Winofy API client & error envelope

All calls to the Winofy API go through `winofyFetch()` in `src/lib/api/winofy.ts`. It:

- prefixes `WINOFY_API_BASE_URL`, attaches query params, JSON-encodes the body
- attaches `Authorization: Bearer <accessToken>` from the session, unless called with `{ auth: false }`
- always sets `cache: "no-store"` — nothing from this API is safe to cache past the current request
- logs every request/response in dev via `src/lib/api/dev-logger.ts` (pretty-printed, truncated, color-coded by status) — this is your Network tab, since these calls never reach the browser
- throws `ApiError` on non-2xx, parsed from the API's error envelope:

```json
{
  "success": false,
  "status_code": 400,
  "status_message": "...",
  "details": { "message": "...", "error": "...", "timestamp": "..." }
}
```

`details.message` is either a plain string or a `{ field: string[] }` map of validation errors — `ApiError.fieldErrors` normalizes that for forms.

Server Actions wrap `winofyFetch` calls in `callApi()` (`src/lib/api/result.ts`), which never throws — it returns a typed `ActionResult<T>` (`{ ok: true, data }` or `{ ok: false, status, message, fieldErrors }`), so client components can branch on failure without try/catch.

### 4.3 Auth & sessions

Login is phone number + OTP against Gooyal, via the OAuth2 password grant with `auth_fields=phone_number:otp`. Two client modules exist because Gooyal is called from two different places:

- `src/lib/auth/gooyal-client.ts` — browser-side (`"use client"`), used by the login/OTP form. Gooyal's CORS is open, so this calls `accounts-staging.gooyal.ir` directly — it does **not** proxy through our own API routes. Uses the `NEXT_PUBLIC_*` env vars (§8).
- `src/lib/auth/gooyal.ts` — server-side, used only for refresh-token exchange. Uses the non-public env vars.

Once tokens come back, `createSession()` (`src/lib/auth/session.ts`) encrypts them into a JWE (`jose`, `alg: dir`, `enc: A256GCM`) and stores it as the `winofy_session` httpOnly cookie — a 30-day cookie lifetime, independent of the much shorter-lived Gooyal access token inside it.

`getValidSession()` is the actual source of truth for "is this user logged in": it decrypts the cookie, and if the access token is expired (30s skew), transparently refreshes it and re-persists the new session — deduped per-request via React's `cache()`. Prefer this over the raw `getSession()` everywhere.

`src/proxy.ts` (Next 16 renamed `middleware.ts` → `proxy.ts`; the export is now `export default function proxy(request)`, not `middleware`) does an **optimistic, cookie-presence-only** check against `AUTH_REQUIRED_PREFIXES` and redirects to `/login?next=...` if the cookie is missing entirely. It deliberately does not decrypt or validate the session — that would mean an extra round-trip on every request. A present-but-expired-and-unrefreshable session still reaches the page; that's what `requireSession(path)` is for — call it at the top of any page under an auth-required prefix, before fetching data, so a dead session redirects cleanly instead of the page crashing on an uncaught 401.

Cookie writes (`createSession`/`deleteSession`) are wrapped in try/catch: Next.js forbids mutating cookies during a plain Server Component render (only Server Actions and Route Handlers may), but `getValidSession()` can legitimately be called from either. When called from a render, a refreshed token is still used for the rest of that request — it just silently fails to persist, and the next request repeats the refresh. That's intentional, not a bug to "fix" by moving the call elsewhere.

### 4.4 API layer organization

`src/lib/api/` is organized by feature, one file per resource, all built on `winofyFetch`:

```
addresses.ts   cart.ts       catalog.ts        checkout.ts
locations.ts   media.ts      notifications.ts  orders.ts
reviews.ts     stores.ts     result.ts         errors.ts
winofy.ts      dev-logger.ts
seller/
  analytics.ts  orders.ts  products.ts  reviews.ts  store.ts
```

Mutations (`add/update/remove/create/cancel...`) are Server Actions, called directly from client components as props — no fetch/API-route indirection. Reads are plain async functions called from Server Components. There's no separate "actions" layer — an earlier version split reads/writes into `src/lib/actions/`, and it was folded into these feature files because the split added indirection without a real benefit.

### 4.5 Data fetching pattern

Almost everything renders server-side: pages are `async function` Server Components that call `src/lib/api/*` reads directly and pass plain data down as props. This is why requests are invisible in Chrome's Network tab — they never leave the Next.js server process. Two consequences worth knowing before you go looking for a bug in the wrong place:

- To *see* these requests, read the dev logger output in your terminal (or `next.config.ts`'s `logging.fetches`, which shows URL/status/timing only, no body).
- Client-side navigation between pages (e.g. clicking a store card) can show up in the Network tab as just an RSC fetch (`?_rsc=...`). The store-detail data fetch still happened server-side to produce that payload — it's just bundled into that one request instead of a separate visible `GET /stores/:id`.

Cart/mutation UI (`ProductGridCard`, `ProductPurchasePanel`, etc.) is the exception: those are client components that call Server Actions via `useTransition`, update local state only after the action confirms success, then `router.refresh()` to reconcile with the true server state.

### 4.6 Location & neighborhoods

Location is stored client-side as a plain (unencrypted — not sensitive) cookie, `winofy_location`, via `src/lib/location/{client,server,types}.ts`. Two modes:

```ts
{ mode: "geo"; lat; lng }
{ mode: "manual"; cityUuid; cityName; neighborhoodUuid; neighborhoodName }
```

The home page (`(customer)/page.tsx`) reads it server-side to filter `getStores()`; the location picker (`location/search`) writes it client-side after a manual neighborhood pick or a successful geolocation read, and can clear it back to "no location selected."

Neighborhood **search** goes through a same-origin route handler, `src/app/api/locations/neighborhoods/route.ts`, rather than the client calling the Winofy API directly — necessary because the browser can't reach the non-CORS Winofy API itself. That handler also patches a real backend gap (see gap 1 below).

Known gaps in this area, numbered so future work can reference them:

1. Backend does not implement server-side neighborhood search filtering — worked around client-of-the-route-handler-side against both `name` and `city.name`.
2. The location cookie is 180 days — deliberate, so the L01 "share your location" onboarding screen doesn't refire every session.
3. Geolocation errors are surfaced by `GeolocationPositionError.code` (`PERMISSION_DENIED` / `POSITION_UNAVAILABLE` / `TIMEOUT`) with distinct Persian copy per case. macOS's `kCLErrorLocationUnknown` surfaces here as `POSITION_UNAVAILABLE` — that's CoreLocation reporting "no fix yet," not a frontend bug.

## 5. Design system

- RTL throughout: `<html dir="rtl" lang="fa">` in `src/app/layout.tsx`. Write layout CSS RTL-first (`text-right`, logical properties) rather than retrofitting an LTR layout.
- Font: Vazirmatn (`next/font/google`, `arabic` + `latin` subsets), exposed as the `--font-vazirmatn` CSS variable and mapped to Tailwind's `font-sans`.
- All design tokens live in `src/app/globals.css` as plain hex custom properties under `:root`, re-exposed to Tailwind via `@theme inline`. **Tailwind v4's built-in palette (emerald, slate, etc.) is OKLCH internally** — close to, but not bit-for-bit, the hex values in the design spec — so every color that must match a spec exactly is defined as its own token here rather than borrowed from Tailwind's defaults. Adding a new spec color means adding a token here, not reaching for e.g. `emerald-500` directly.
- Persian digit handling: `src/lib/format/persian-digits.ts` (`toPersianDigits` / `toLatinDigits`) — needed anywhere user-facing numbers are displayed, or anywhere user-typed numbers (phone, OTP) are parsed, since Persian keyboards type Persian-Arabic digit glyphs that fail plain `\d` regexes.
- Iranian week: Saturday is the first day. Convert from JS's `Date.getDay()` (Sunday = 0) with `(jsDay + 1) % 7` wherever a weekday needs to be shown.

## 6. Docker & deployment

Multi-stage `Dockerfile`, `output: "standalone"` — the runtime image ships only `server.js`, `.next/static`, and `public/`, runs as a non-root user, listens on `$PORT` (default `3000`).

The one thing not to get wrong: **`NEXT_PUBLIC_*` vars are baked into the client bundle at *build* time.** Everything else (API base URL, Gooyal secret, session secret) is read at container *runtime* instead, and must never be baked into an image layer.

```bash
cp .env.example .env.local
docker compose --env-file .env.local up --build
```

The `--env-file .env.local` flag is required — without it, Compose looks for a `.env` file (this repo doesn't have one) to fill the `NEXT_PUBLIC_*` build args in `docker-compose.yml`, and you'll silently get a client bundle built with empty values.

Plain `docker build`/`run` needs the same `NEXT_PUBLIC_*` values passed explicitly as `--build-arg`s (see `README.md`) plus `--env-file .env.local` at `docker run` time for everything else.

## 7. Known backend gaps

These are backend-side, not something to "fix" in this repo — flagged so you don't spend time debugging frontend code that's actually correct:

- **Cart item `PATCH`/`DELETE` return `403 permission_denied`** on staging, for both the per-item endpoint and the collection endpoints, with a token that can otherwise `GET`/`POST` the same cart. Blocks quantity-decrement and remove-from-cart app-wide until the backend/OAuth scope issue is resolved.
- **Addresses and order-groups `GET` return `403`** — current OAuth scope doesn't cover them.
- **Neighborhood search isn't filtered server-side** — worked around client-side, see §4.6 gap 1.

## 8. Environment variables

Copy `.env.example` to `.env.local` and fill in real values — never commit `.env.local`.

| Variable | Scope | Purpose |
|---|---|---|
| `WINOFY_API_BASE_URL` | server-only | Base URL of the Winofy Django/DRF API, e.g. `https://winofy-staging.winsoo.ir/api` |
| `GOOYAL_ACCOUNTS_BASE_URL` | server-only | Gooyal OAuth base, used for server-side refresh-token calls |
| `GOOYAL_CLIENT_ID` | server-only | OAuth client id, server-side calls |
| `GOOYAL_CLIENT_SECRET` | server-only | OAuth client secret, server-side calls |
| `GOOYAL_OAUTH_SCOPE` | server-only | Space-separated OAuth scope string, server-side calls |
| `NEXT_PUBLIC_GOOYAL_ACCOUNTS_BASE_URL` | public (client bundle) | Same Gooyal base, usable from the browser — the login form talks to Gooyal directly |
| `NEXT_PUBLIC_GOOYAL_CLIENT_ID` | public (client bundle) | Client id for the browser-side OAuth exchange |
| `NEXT_PUBLIC_GOOYAL_CLIENT_SECRET` | public (client bundle) | Intentionally public — the browser must send this in a Basic Auth header to complete the OTP token exchange directly against Gooyal, so it can never actually be kept confidential in a client-side flow. Gooyal's client registration for this app is configured accordingly; treat it like a client id, not a real secret |
| `NEXT_PUBLIC_GOOYAL_OAUTH_SCOPE` | public (client bundle) | Scope string for the browser-side OAuth exchange |
| `SESSION_SECRET` | server-only | 32-byte base64 key used to encrypt the session cookie (JWE). Generate with `openssl rand -base64 32` |

Docker note: the `NEXT_PUBLIC_*` values must be supplied as build args (they're compiled into the client bundle), not just runtime env — see §6.

## 9. Folder structure reference

```
src/
├─ app/
│  ├─ (auth)/login/
│  ├─ (customer)/
│  │  ├─ (shop)/
│  │  │  ├─ addresses/  cart/  checkout/  orders/
│  │  │  ├─ order-groups/[uuid]/  products/[uuid]/  stores/[uuid]/
│  │  │  ├─ profile/  layout.tsx
│  │  ├─ location/{error,permission,search}/
│  │  ├─ page.tsx (home)  error.tsx
│  ├─ (seller)/seller/
│  ├─ api/{auth/{logout,session}, locations/neighborhoods}/route.ts
│  └─ layout.tsx  globals.css
├─ components/
│  ├─ auth/  customer/  home/  location/  product/  store/  ui/
├─ lib/
│  ├─ api/          — §4.2 / §4.4
│  ├─ auth/          — §4.3
│  ├─ location/      — §4.6
│  ├─ format/  validation/  utils/  order-status.ts  query-provider.tsx
├─ proxy.ts          — §4.3
└─ types/api.ts
```