# Balout Pastry — Dashboards (setup context)

Admin dashboard for شیرینی‌فروشی بلوط. React + Vite SPA that talks to the NestJS API.

Repo: `https://git.meshkee.com/BaloutPastry/dashboards.git`  
API repo: `https://git.meshkee.com/BaloutPastry/backend.git`

## Stack

- React 19 + TypeScript + Vite 8
- React Router 7
- Lucide icons
- Auth via JWT (access + refresh) stored in `localStorage`
- API client: `src/lib/api.ts` → `VITE_API_BASE_URL`

## Prerequisites

- Node.js **20+** (LTS recommended)
- npm
- Running **Backend** API on port **3100** (see backend `README.md`)
- A `superAdmin` / `admin` user in the API database

## Setup on a new device

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

cp .env.example .env
# Edit if API is not on localhost:3100
# VITE_API_BASE_URL=http://localhost:3100/api/v1

npm install
npm run dev
```

Open **http://localhost:5173**

### Backend must be up first

From the backend repo (separate clone):

```bash
cp .env.example .env
npm install
npm run db:up
npx prisma migrate deploy
npm run create-super-admin -- --phone 09120000000 --password secret123
npm run start:dev   # http://localhost:3100/api/v1
```

Then log into the dashboard with that phone/password.

CORS: backend `CORS_ORIGIN` should include `http://localhost:5173` (default in `.env.example`).

## Scripts

| Command | What it does |
|---------|----------------|
| `npm run dev` | Vite dev server → `http://localhost:5173` |
| `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 match backend base URL including `/api/v1` |

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

After changing env vars, restart `npm run dev` (Vite only reads them at startup).

## App routes

| Path | Page |
|------|------|
| `/login` | Admin login (mobile + password) |
| `/` | Home |
| `/products` | Products hub |
| `/products/list` | Product list |
| `/products/new` | Add product |
| `/products/categories` | Categories |
| `/users` | Users |
| `/orders` | Orders |
| `/settings` | Settings (shipping, branches) |

Protected routes redirect to `/login` when there is no session.

## Auth / session notes

- Login: `POST /auth/login` with `cellNumber` + `password`
- Only `admin` and `superAdmin` can use this dashboard
- Tokens live in `localStorage` (`src/lib/auth.ts`)
- `apiRequest` refreshes access token on `401` via `/auth/refresh`
- Logout clears the session

## Project layout (important paths)

```
src/
  lib/api.ts          HTTP client + ApiError
  lib/auth.ts         Session / tokens
  lib/authApi.ts      Login / refresh / logout / me
  lib/*Api.ts         Domain API helpers
  pages/              Route pages
  components/         Modals, header, shared UI
  data/               Shared types & constants (titles, roles, …)
  utils/              Helpers (price, digits, …)
```

## Production build

```bash
npm run build
# Serve dist/ behind nginx/Caddy, or:
npm run preview
```

Set `VITE_API_BASE_URL` to the real API URL **before** `npm run build` (it is baked into the bundle).

## Common issues

| Symptom | Likely cause |
|---------|----------------|
| «اتصال به سرور» / save failed | Backend not running, or wrong `VITE_API_BASE_URL` |
| Login works then immediate logout | Refresh token rejected; check JWT secrets / DB |
| CORS errors in browser | Backend `CORS_ORIGIN` missing dashboard origin |
| Empty users/products | API up but empty DB, or not logged in as admin |

## Related

- Backend docs: clone `BaloutPastry/backend` and read its `README.md`
- Postgres for local API: Docker Compose on host port **5434**