# Balinyaar Client — Claude Code Guidelines ## Project Structure ``` client/ ├── messages/ # Translation files (add keys to BOTH files) │ ├── en.json │ └── fa.json ├── middleware.ts # next-intl routing middleware (locale detection + redirect) ├── next.config.mjs # createNextIntlPlugin wires i18n into Next.js └── src/ ├── app/ │ ├── layout.tsx # Root RSC: reads locale + cookie → sets HTML attrs │ ├── globals.css │ ├── fonts/ # Local font files (woff2) — Mikhak for fa │ └── [locale]/ │ ├── layout.tsx # RSC: setRequestLocale + NextIntlClientProvider + ThemeProvider + AppStoreProvider │ ├── (private-routes)/ │ │ ├── layout.tsx # 'use client' — wraps PrivateLayout │ │ └── page.tsx │ └── (public-routes)/ │ └── layout.tsx # 'use client' — wraps PublicLayout ├── components/ # Shared UI components (each with .test.tsx if imported >1 place) ├── i18n/ │ ├── routing.ts # defineRouting — locales: ['en', 'fa'], defaultLocale: 'fa' │ └── request.ts # getRequestConfig — loads messages/${locale}.json ├── layout/ │ ├── PrivateLayout.tsx # 'use client' — authenticated shell; uses useTranslations('nav') │ ├── PublicLayout.tsx # unauthenticated shell │ ├── TopBarAndSideBarLayout.tsx # 'use client' — TopBar + SideBar composition │ ├── config.ts │ ├── index.ts │ └── components/ │ ├── TopBar.tsx │ ├── SideBar.tsx │ ├── SideBarNavList.tsx │ ├── SideBarNavItem.tsx │ ├── DarkModeButton.tsx # 'use client' — only subscriber to useColorScheme() │ └── index.tsx ├── lib/ │ ├── api/ │ │ ├── client.ts # clientFetch — throws ApiError on error; use in hooks/client components │ │ ├── server.ts # serverFetch — throws ApiError on error; use in RSCs/Server Actions │ │ └── errors.ts # ApiError class (status, message, code) │ ├── query/ │ │ ├── queryClient.ts # makeQueryClient factory + getQueryClient() SSR-safe singleton │ │ └── QueryProvider.tsx # 'use client' — QueryClientProvider + ReactQueryDevtools │ └── cookies/ # Cookie manager — strict server/client separation │ ├── constants.ts # COOKIE_NAMES, CookieOptions, AUTH_*_COOKIE_OPTIONS │ ├── server.ts # getServerCookie, getThemeMode, setServerCookie │ ├── client.ts # getClientCookie, setClientCookie, deleteClientCookie │ └── index.ts # Re-exports constants ONLY (never server/client) ├── services/ # Domain services — no top-level barrel; import directly from the file │ └── {domain}/ │ ├── types.ts # Request/response types for this domain │ ├── keys.ts # React Query key factory │ ├── apis/ │ │ ├── clientApi.ts # Namespace object wrapping clientFetch calls │ │ └── serverApi.ts # Namespace object wrapping serverFetch calls (only when needed) │ └── hooks/ │ └── use{Action}.ts # One hook per file — useQuery or useMutation ├── store/ # AppStore (Redux-like client state) ├── theme/ │ ├── ColorSchemeScript.tsx # Inline