init

2026-06-16 01:32:43 +03:30
commit 69bbd28bb0
298 changed files with 24728 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 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.