# 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 /). ├── 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), cookies, query (TanStack), toast ├── services/ Domain services: {domain}/{types,keys,apis,hooks} ├── store/ AppStore (React context + reducer) for client 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`), managed through `src/lib/cookies/` and the `src/services/auth/` hooks. The API base URL comes from `NEXT_PUBLIC_API_URL`.