dashboards/CONTEXT.md

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

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):

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

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 CONTEXT.md
• Website (storefront): clone BaloutPastry/website and read CONTEXT.md (dev port 5174)
• Postgres for local API: Docker Compose on host port 5434