# Balinyaar — Web Client

Frontend for the Balinyaar application, built with **Next.js (App Router)**, **React**, **TypeScript**, and **Material UI (MUI)**.

It ships with a small library of reusable `App*` components, a theming system (light/dark), a lightweight global store, and public/private layouts wired for an authentication flow.

## 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).

## Available scripts

| Script             | Description                                              |
| ------------------ | ------------------------------------------------------- |
| `npm run dev`      | Start the development server with hot reload            |
| `npm run build`    | Production build (static export to `out/`)              |
| `npm run start`    | Serve a production build                                |
| `npm run lint`     | Run ESLint (`eslint-config-next`)                       |
| `npm run format`   | Format the codebase with Prettier                       |
| `npm test`         | Run Jest in watch mode                                  |
| `npm run test:ci`  | Run Jest once (CI)                                      |
| `npm run type`     | Type-check with `tsc`                                   |

## Project structure

```
src/
├── app/            Next.js App Router routes (home, about, auth, me) + root layout
├── components/     Reusable UI: common App* components (AppButton, AppIcon, ...) + UserInfo
├── hooks/          Custom hooks (auth, layout, events, window size)
├── layout/         PublicLayout / PrivateLayout + TopBar, SideBar, BottomBar
├── store/          Global app store (React context + reducer)
├── theme/          MUI theme provider, light/dark palettes, colors
└── utils/          Helpers (storage, navigation, env, text, types)
```

The `@/*` import alias maps to `src/*` (see `tsconfig.json`).

> For a deeper, agent-oriented map of conventions and where to make changes, see [AGENTS.md](AGENTS.md).

## Notes

- `next.config.mjs` uses `output: 'export'`, producing a static site in `out/`.
- Authentication in `src/hooks/auth.ts` and `src/app/auth/login/LoginForm.tsx` is currently a stub (look for `// TODO: AUTH:`); wire it to the backend's JWT endpoints when implementing real auth.