website/CONTEXT.md

# Balout Pastry — Website (setup context)

Public storefront for شیرینی‌فروشی بلوط. React + Vite SPA that browses products and places orders via the NestJS API. Design matched to [shirinibalout.com](https://www.shirinibalout.com/).

Repo: `https://git.meshkee.com/BaloutPastry/website.git`  
API repo: `https://git.meshkee.com/BaloutPastry/backend.git`  
Dashboards (customer login / account): `https://git.meshkee.com/BaloutPastry/dashboards.git`

## Stack

- React 19 + TypeScript + Vite 8
- React Router 7
- Lucide icons
- Cart in `localStorage` (`balout.cart`)
- Auth session cookie `balout.auth` (shared with customer dashboard on `*.baloutpastry.com`)
- API client: `src/lib/api.ts` → `VITE_API_BASE_URL`

## Prerequisites

- Node.js **20+** (LTS recommended)
- npm
- Running **Backend** API on port **3100**
- Optional: customer dashboard on **5173** for login / account (SSO via cookie or hash handoff)

## Setup on a new device

```bash
git clone https://git.meshkee.com/BaloutPastry/website.git
cd website

cp .env.example .env
# Edit if API / customer app URLs differ

npm install
npm run dev
```

Open **http://localhost:5174** (or **http://baloutpastry.com:5174** with local DNS).

### Local hosts (recommended)

Add to `/etc/hosts`:

```
127.0.0.1 baloutpastry.com www.baloutpastry.com
127.0.0.1 admin.baloutpastry.com customer.baloutpastry.com
```

Then:

| App | URL |
|-----|-----|
| Website | `http://baloutpastry.com:5174` |
| Customer dashboard | `http://customer.baloutpastry.com:5173` |
| Admin dashboard | `http://admin.baloutpastry.com:5173` |
| API | `http://localhost:3100/api/v1` |

Backend `CORS_ORIGIN` must include the website origin(s), e.g.  
`http://baloutpastry.com:5174,http://www.baloutpastry.com:5174,http://localhost:5174`

### Backend must be up

From the backend repo:

```bash
cp .env.example .env
npm install
npm run db:up
npx prisma migrate deploy
npm run start:dev   # http://localhost:3100/api/v1
```

## Scripts

| Command | What it does |
|---------|----------------|
| `npm run dev` | Vite dev server → **http://localhost:5174** |
| `npm run build` | Typecheck + production build → `dist/` |
| `npm run preview` | Serve production build locally |
| `npm run lint` | Oxlint |

## Environment

| Variable | Required | Default | Notes |
|----------|----------|---------|-------|
| `VITE_API_BASE_URL` | no | `http://localhost:3100/api/v1` | Must include `/api/v1` |
| `VITE_CUSTOMER_APP_URL` | no | `http://customer.baloutpastry.com:5173` | Login / profile redirects |
| `VITE_COOKIE_DOMAIN` | no | `.baloutpastry.com` (when on that host) | Shared auth cookie domain |

Copy from `.env.example`. Do **not** commit `.env`.

After changing env vars, restart `npm run dev`.

## App routes

| Path | Page |
|------|------|
| `/` | Home (hero, categories, featured products) |
| `/products` | Product list + filters |
| `/products/:slugOrId` | Category by slug **or** product detail by id |
| `/quick-info` | Quick info |
| `/about-us` | About |
| `/contact-us` | Contact |

Cart drawer and toasts are global (not separate routes). Checkout / login hand off to the customer dashboard when needed.

## Auth / cart notes

- Guest browsing and cart work without login
- Session cookie: `balout.auth` (also accepts `#balout_auth=…` hash handoff from customer app)
- Access token sent as `Authorization: Bearer …` on authenticated API calls
- Cart key: `balout.cart` in `localStorage`; change event `balout:cart-change`
- Prices are integer **تومان**

## Project layout

```
src/
  App.tsx                 Routes + shell (Header / Footer / Cart / Toast)
  pages/                  Home, products, about, contact, quick-info
  components/             Header, Footer, CartDrawer, ProductCard, …
  lib/
    api.ts                HTTP client + catalog / checkout helpers
    auth.ts               Cookie session + customer-app redirects
    cart.ts               localStorage cart
    types.ts              Shared types + formatPriceFa
    ids.ts                cuid vs category-slug detection
```

## Production build

```bash
cp .env.example .env   # set real API + customer app URLs
npm ci
npm run build
# Serve dist/ behind nginx/Caddy, or:
npm run preview
```

Set `VITE_*` **before** `npm run build` (they are baked into the bundle).

## Common issues

| Symptom | Likely cause |
|---------|----------------|
| Empty catalog / fetch errors | Backend not running, or wrong `VITE_API_BASE_URL` |
| CORS errors in browser | Backend `CORS_ORIGIN` missing website origin (port **5174**) |
| Port already in use | Another process on **5174** (`strictPort: true`) |
| Login redirect fails | Customer dashboard down, or wrong `VITE_CUSTOMER_APP_URL` |
| Auth not shared across apps | Missing `/etc/hosts` + `VITE_COOKIE_DOMAIN=.baloutpastry.com` |

## Related

- Backend setup: clone `BaloutPastry/backend` and read `CONTEXT.md`
- Customer / admin UI: clone `BaloutPastry/dashboards` and read `CONTEXT.md`