# Balinyaar — Web Client

Frontend for **Balinyaar**, a trust-first home-nursing marketplace in Iran. Built with
**Next.js 16 (App Router)**, **React 19**, **TypeScript**, and **Material UI (MUI) v9**.

It ships with internationalization (`fa`/`en`, RTL-first), a no-flash light/dark theme system, a small
library of reusable `App*` components, TanStack Query for server state, and public/private layout
shells wired for cookie-based authentication.

> **AI agents:** read [CLAUDE.md](CLAUDE.md) — it is the engineering contract (architecture, providers,
> data fetching, theming, i18n, cookies, and the rules every change must follow).

## Requirements

- Node.js 18+ and npm
- The backend API (see [`../server`](../server)) running for authenticated features

## Getting started

1. Install dependencies:

   ```bash
   npm install
   ```

2. Create your local environment file from the sample and adjust values:

   ```bash
   cp .env.sample .env
   ```

   Key variables (all `NEXT_PUBLIC_*` are exposed to the browser):

   | Variable                 | Purpose                                              |
   | ------------------------ | ---------------------------------------------------- |
   | `NEXT_PUBLIC_ENV`        | `development` \| `preview` \| `production`           |
   | `NEXT_PUBLIC_DEBUG`      | `true` enables extra console logging                 |
   | `NEXT_PUBLIC_PUBLIC_URL` | Public URL of the site                               |
   | `NEXT_PUBLIC_API_URL`    | Base URL of the backend API (the `server` project)   |

3. Run the dev server:

   ```bash
   npm run dev
   ```

   Open [http://localhost:3000](http://localhost:3000). The root path redirects to `/fa` (default locale).

## Available scripts

| Script             | Description                                              |
| ------------------ | ------------------------------------------------------- |
| `npm run dev`      | Start the development server (Turbopack) with hot reload |
| `npm run build`    | Production build                                         |
| `npm run start`    | Serve a production build                                 |
| `npm run lint`     | Lint with ESLint (flat config, `eslint .`)              |
| `npm run lint:fix` | Lint and auto-fix                                        |
| `npm run type`     | Type-check with `tsc --noEmit`                          |
| `npm run check`    | Type-check **and** lint (the quality gate)             |
| `npm run format`   | Format the codebase with Prettier                       |
| `npm test`         | Run Jest in watch mode                                  |
| `npm run test:ci`  | Run Jest once (CI)                                      |

## Project structure

```
src/
├── app/[locale]/    App Router routes, grouped into (public-routes) and (private-routes).
│                    [locale]/layout.tsx is the ROOT layout (renders <html>/<body>).
├── components/      Reusable UI: common App* components (AppButton, AppIcon, …) + UserInfo
├── constants/       App-wide named constants (routes, headers, …)
├── hooks/           Custom hooks (auth, layout/mobile, events, window size)
├── i18n/            next-intl routing + request config
├── layout/          PublicLayout / PrivateLayout + TopBar, SideBar, BottomBar
├── lib/             api (client/server fetch), auth (JWT/session helpers), cookies, query, toast
├── services/        Domain services: {domain}/{types,keys,apis,hooks}
├── context/         React context providers — auth/ is AuthContext (server-seeded session state)
├── theme/           ThemeProvider, palettes, tokens.css, typography, direction
└── utils/           Helpers (storage, navigation, env, text, types)
```

The `@/*` import alias maps to `src/*` (see `tsconfig.json`).
Translation files live in [`messages/`](messages) (`en.json` / `fa.json`) and must stay in sync.

> For the full agent-oriented map of conventions and where to make changes, see [CLAUDE.md](CLAUDE.md).

## Notes

- This is a server-rendered Next.js app (App Router + middleware + server-side cookies) — **not** a
  static export.
- Internationalization is locale-prefixed (`/fa`, `/en`); `fa` is the default and is RTL.
- Authentication is cookie-based (`access_token` / `refresh_token`). Session state lives in
  `AuthContext` (`src/context/auth/`), seeded on the server from the request cookie so the first
  render reflects the real session; cookies are managed through `src/lib/cookies/` and the
  `src/services/auth/` hooks. The API base URL comes from `NEXT_PUBLIC_API_URL`.
