hamid
96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# 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`.
|