# Frontend - Global Catalogue (React + Vite)

React 19 + Vite + Tailwind CSS v4 single-page app for browsing the catalog,
running semantic search, chatting with the RAG assistant, and (on
`/admin`) triggering ingestion of new brands.

Full setup steps are in the project documentation (`../docs/`). This file
is a fast local reference.

## Quick start

### One command (from the Project root)

```bash
python run_project.py
```

Starts the FastAPI backend, waits until `/api/health` answers, then starts
this Vite dev server - so the API is always up before the UI first calls it.
Use `--frontend-only` to start just Vite against a backend you're already
running yourself.

### Manual

```bash
cd frontend
npm install
npm run dev
```

Open http://localhost:5173 - the Vite dev server proxies `/api/*` to
`http://localhost:8000` automatically (see `vite.config.js`), so make
sure the backend is running there first (see `../backend/README.md`).

Note that Vite binds `localhost` as IPv6 (`[::1]`), which browsers handle
fine. Only relevant if you probe it with a tool pinned to IPv4 - use
`http://[::1]:5173` there, or pass `--host 127.0.0.1`.

If your backend runs somewhere else, set `VITE_API_BASE_URL` in a local
`.env` file (copy `.env.example`) instead of relying on the proxy.

## Production build

```bash
npm run build      # outputs to dist/ - for the DEPLOYED site only
npm run preview    # serve the production build locally to sanity-check it
```

`npm run build` loads `.env.production`, which pins `VITE_API_BASE_URL` to
`https://mcp.nearle.ai.in`. That is right for the deployed site and wrong for
anything you run locally, because the backend serves `frontend/dist` itself
whenever that directory exists - so `http://localhost:8000` would hand you a
page that sends `/api/auth/login` to the remote host and fails with "Could not
reach the API" even though the local backend is up. For a build you intend to
run locally, use:

```bash
npm run build:unified   # same optimised build, blank VITE_API_BASE_URL
```

That leaves API calls relative, so they go back to whichever server delivered
the page - port 8000 for the backend's single-port mode, or `npm run preview`,
which proxies `/api/*` to `127.0.0.1:8000` the same way the dev server does.

## Pages

- `/` - Browse & Search (sidebar brand/category filters, product grid,
  semantic search bar) with a toggle to **Ask AI**, a conversational RAG
  chat panel that cites which catalog products it used for each answer.
- `/admin` - Trigger ingestion of a new brand and watch job status.

## Structure

```
src/
├── api/client.js          # fetch wrapper for every backend endpoint
├── components/
│   ├── Sidebar.jsx / TopBar.jsx
│   ├── ProductCard.jsx / ProductGrid.jsx / ProductModal.jsx
│   ├── ChatPanel.jsx / ChatMessage.jsx
│   └── Atoms.jsx           # Spinner, EmptyState
├── pages/
│   ├── HomePage.jsx
│   └── AdminPage.jsx
├── App.jsx                 # routes
├── main.jsx
└── index.css                # Tailwind v4 theme tokens ("Global Catalogue Ledger" palette)
```