baya-monorepo/client/AGENTS.md

AGENTS.md — Balinyaar Web Client

Agent-oriented guide to the frontend. For human setup/run instructions see README.md.

Stack

• Next.js with the App Router (src/app/), statically exported (output: 'export' in next.config.mjs → builds to out/)
• React + TypeScript (strict mode)
• Material UI (MUI) for components and theming (Emotion under the hood)
• Jest + Testing Library for unit tests
• ESLint (eslint-config-next) + Prettier

Commands

Task	Command
Dev server	npm run dev
Build	npm run build
Lint	npm run lint
Type-check	npm run type
Format	npm run format
Test (watch)	npm test
Test (CI)	npm run test:ci

Always run npm run lint and npm run type after a change. Run npm run test:ci when you touch a component that has a *.test.tsx.

Directory map

src/
├── app/                 Routes (App Router). Each folder = a route; page.tsx = the page.
│   ├── layout.tsx       Root layout: store + theme providers, global <metadata>
│   ├── page.tsx         "/" entry (delegates to home)
│   ├── home/ about/     Content pages
│   ├── auth/login|signup   Auth pages (LoginForm is currently a stub)
│   └── me/              Authenticated user page
├── components/
│   ├── common/          Reusable App* primitives (see below) + ErrorBoundary
│   └── UserInfo/        Logged-in user summary
├── hooks/               useIsAuthenticated, useIsMobile, event hooks, useWindowSize
├── layout/              PublicLayout / PrivateLayout + TopBar, SideBar, BottomBar, config
├── store/               Global state: React context + reducer (AppStore, AppReducer)
├── theme/               ThemeProvider, light/dark palettes, colors, MUI-for-Next bridge
└── utils/               storage (local/session), navigation, environment, text, types

Conventions (follow these)

• Imports: use the @/* alias for anything under src/ (e.g. import { AppButton } from '@/components'). The alias is defined in tsconfig.json.
• Barrel files: most folders export through an index.ts(x). Add new public exports there (e.g. a new common component is re-exported from src/components/common/index.tsx, which src/components/index.tsx re-exports).
• Common components live in src/components/common/<Name>/ as a folder containing <Name>.tsx, index.tsx (re-export), and an optional <Name>.test.tsx. Existing ones: AppAlert, AppButton, AppIcon, AppIconButton, AppImage, AppLink, AppLoading. Prefer reusing these over raw MUI where one exists.
• Icons: reference icons by string name through AppIcon. The name→icon map is in src/components/common/AppIcon/config.ts; add new icons there (custom SVGs go in AppIcon/icons/).
• Navigation: sidebar/bottom-bar items are arrays of LinkToPage defined inside PublicLayout.tsx / PrivateLayout.tsx. Add a route → add an entry there to surface it in the nav.
• Two layouts: PrivateLayout (after auth) and PublicLayout (before auth); CurrentLayout picks between them based on auth state. The app name lives in the TITLE_PRIVATE / TITLE_PUBLIC constants in those files.
• Auth is a stub. src/hooks/auth.ts and src/app/auth/login/LoginForm.tsx fake login by writing a placeholder token to session storage (// TODO: AUTH:). When implementing real auth, replace those spots and point requests at NEXT_PUBLIC_API_URL (the server project's JWT endpoints).
• Theming: use the theme/palette via MUI's sx / useTheme; don't hardcode colors. Light/dark values are in src/theme/light.ts and dark.ts; dark-mode toggle flows through the store.
• Client vs server components: files needing hooks/browser APIs start with 'use client'; (see LoginForm.tsx). Pages that only render markup can stay server components.

Environment

Browser-exposed config comes from NEXT_PUBLIC_* variables (copy .env.sample → .env). The ones actually read in code: NEXT_PUBLIC_ENV, NEXT_PUBLIC_DEBUG, NEXT_PUBLIC_PUBLIC_URL (see src/config.ts) and NEXT_PUBLIC_VERSION (see src/utils/environment.ts). NEXT_PUBLIC_API_URL is the backend base URL.

Gotchas

• Static export (output: 'export') means no server-side runtime — no API routes, no SSR-only features, images.unoptimized is on.
• Don't reintroduce the removed demo/showcase route (src/app/dev) or Demo* components — they were template content.