frontend phase 0: app shells, design system & data/contract patterns

Turn the starter into the Balinyaar foundation for the three actor
experiences and lock in the patterns later phases copy.

- Cleanup: remove toastDemo namespace, placeholder home page, and the two
  dead icons; fix BottomBar to use usePathname (locale-aware active tab).
- Three actor shells under (private-routes), no layout above [locale]:
  customer (customer) group with the 5-tab bottom nav; nurse (/nurse) and
  admin (/admin) on the shared sidebar engine. Role model via constants/roles
  + useActorRole (defaults to customer until roles land in f1-b2).
- services/{domain} reference (patients) with a mock behind a config seam,
  hierarchical query keys, deliberate staleTime, and mutation invalidation;
  shared ApiEnvelope/Paginated wire types + unwrap() in lib/api/types.
- Money (integer-safe IRR/Toman) + Shamsi-date utils; toEnglishDigits helper.
- Shared composites, each tested: OtpInput, PhoneNumberField, StepperHeader,
  StatusChip, PlaceholderScreen.
- i18n: seed nav/common/shell/patients in both locales; document namespace
  conventions. Update client/CLAUDE.md Project Structure + fix ColorSchemeScript
  doc drift. Add phase report, STATUS, and REQ-001 (envelope/casing/pagination).

Gate: npm run check + test:ci green (72 tests); build green with NEXT_PUBLIC_API_URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

client/src/layout/AdminLayout.tsx

@@ -0,0 +1,37 @@
+'use client';
+import { FunctionComponent, PropsWithChildren, useMemo } from 'react';
+import { useTranslations } from 'next-intl';
+import { ROUTES } from '@/constants';
+import { LinkToPage } from '@/utils';
+import TopBarAndSideBarLayout from './TopBarAndSideBarLayout';
+
+/**
+ * Admin / backoffice shell — desktop-oriented ops console (f15). Uses the shared
+ * TopBar + SideBar engine with a persistent sidebar on desktop.
+ * @layout AdminLayout
+ */
+const AdminLayout: FunctionComponent<PropsWithChildren> = ({ children }) => {
+  const t = useTranslations('nav');
+  const tShell = useTranslations('shell');
+
+  const sidebarItems: Array<LinkToPage> = useMemo(
+    () => [
+      { title: t('overview'), path: ROUTES.ADMIN, icon: 'admin' },
+      { title: t('users'), path: ROUTES.ADMIN_USERS, icon: 'users' },
+      { title: t('notifications'), path: ROUTES.ADMIN_NOTIFICATIONS, icon: 'notifications' },
+    ],
+    [t]
+  );
+
+  return (
+    <TopBarAndSideBarLayout
+      sidebarItems={sidebarItems}
+      title={tShell('admin_console')}
+      variant="sidebarPersistentOnDesktop"
+    >
+      {children}
+    </TopBarAndSideBarLayout>
+  );
+};
+
+export default AdminLayout;

client/src/layout/CustomerLayout.tsx

@@ -0,0 +1,64 @@
+'use client';
+import { FunctionComponent, PropsWithChildren, useMemo } from 'react';
+import { Box, Stack } from '@mui/material';
+import { useTranslations } from 'next-intl';
+import { ErrorBoundary } from '@/components';
+import { CONTENT_MAX_WIDTH } from '@/components/config';
+import { ROUTES } from '@/constants';
+import { LinkToPage } from '@/utils';
+import { useIsMobile } from '@/hooks';
+import { TopBar, BottomBar } from './components';
+import { DarkModeToggleButton } from './components/DarkModeButton';
+import { TOP_BAR_DESKTOP_HEIGHT, TOP_BAR_MOBILE_HEIGHT } from './config';
+
+/**
+ * Customer (family) app shell — the primary, mobile-first experience.
+ * A slim TopBar, a scrollable content column constrained to reading width, and the
+ * 5-tab BottomBar (Home/Bookings/Patients/Wallet/Profile) from the wireframe.
+ * @layout CustomerLayout
+ */
+const CustomerLayout: FunctionComponent<PropsWithChildren> = ({ children }) => {
+  const t = useTranslations('nav');
+  const tShell = useTranslations('shell');
+  const onMobile = useIsMobile();
+
+  const bottomNavItems: Array<LinkToPage> = useMemo(
+    () => [
+      { title: t('home'), path: ROUTES.HOME, icon: 'home' },
+      { title: t('bookings'), path: ROUTES.BOOKINGS, icon: 'bookings' },
+      { title: t('patients'), path: ROUTES.PATIENTS, icon: 'patients' },
+      { title: t('wallet'), path: ROUTES.WALLET, icon: 'wallet' },
+      { title: t('profile'), path: ROUTES.PROFILE, icon: 'profile' },
+    ],
+    [t]
+  );
+
+  return (
+    <Stack sx={{ height: '100dvh' }}>
+      <Stack component="header">
+        <TopBar title={tShell('customer_app')} endNode={<DarkModeToggleButton />} />
+      </Stack>
+
+      <Box
+        component="main"
+        sx={{
+          flexGrow: 1,
+          overflowY: 'auto',
+          width: '100%',
+          maxWidth: CONTENT_MAX_WIDTH,
+          mx: 'auto',
+          px: 2,
+          py: 2,
+          // AppBar is position: fixed — offset content by the top-bar height.
+          pt: `calc(${onMobile ? TOP_BAR_MOBILE_HEIGHT : TOP_BAR_DESKTOP_HEIGHT} + 8px)`,
+        }}
+      >
+        <ErrorBoundary name="Customer">{children}</ErrorBoundary>
+      </Box>
+
+      <BottomBar items={bottomNavItems} />
+    </Stack>
+  );
+};
+
+export default CustomerLayout;

client/src/layout/NurseLayout.tsx

@@ -0,0 +1,38 @@
+'use client';
+import { FunctionComponent, PropsWithChildren, useMemo } from 'react';
+import { useTranslations } from 'next-intl';
+import { ROUTES } from '@/constants';
+import { LinkToPage } from '@/utils';
+import TopBarAndSideBarLayout from './TopBarAndSideBarLayout';
+
+/**
+ * Nurse app shell — the "نمای پرستار" experience (verification, dashboard, EVV visits).
+ * Uses the shared TopBar + SideBar engine: a temporary drawer on mobile, persistent on
+ * desktop. Nav is role-scoped to the nurse routes.
+ * @layout NurseLayout
+ */
+const NurseLayout: FunctionComponent<PropsWithChildren> = ({ children }) => {
+  const t = useTranslations('nav');
+  const tShell = useTranslations('shell');
+
+  const sidebarItems: Array<LinkToPage> = useMemo(
+    () => [
+      { title: t('dashboard'), path: ROUTES.NURSE, icon: 'dashboard' },
+      { title: t('verification'), path: ROUTES.NURSE_VERIFICATION, icon: 'verification' },
+      { title: t('visits'), path: ROUTES.NURSE_VISITS, icon: 'visits' },
+    ],
+    [t]
+  );
+
+  return (
+    <TopBarAndSideBarLayout
+      sidebarItems={sidebarItems}
+      title={tShell('nurse_app')}
+      variant="sidebarPersistentOnDesktop"
+    >
+      {children}
+    </TopBarAndSideBarLayout>
+  );
+};
+
+export default NurseLayout;

client/src/layout/components/BottomBar.tsx

@@ -1,7 +1,8 @@
 'use client';
-import { FunctionComponent, useCallback } from 'react';
-import { useRouter } from 'next/navigation';
-import { BottomNavigation, BottomNavigationAction } from '@mui/material';
+import { FunctionComponent, useCallback, useMemo } from 'react';
+import { usePathname, useRouter } from 'next/navigation';
+import { useLocale } from 'next-intl';
+import { BottomNavigation, BottomNavigationAction, Paper } from '@mui/material';
 import { LinkToPage } from '@/utils';
 import { AppIcon } from '@/components';
 
@@ -9,30 +10,56 @@ interface Props {
   items: Array<LinkToPage>;
 }
 
+/** Prefixes an app-relative path with the active locale (e.g. `/bookings` → `/fa/bookings`). */
+function withLocale(locale: string, path: string) {
+  return path === '/' ? `/${locale}` : `/${locale}${path}`;
+}
+
 /**
- * Renders horizontal Navigation Bar using MUI BottomNavigation component
+ * Shared horizontal navigation bar (customer app tabs) built on MUI BottomNavigation.
+ * Locale-aware: it highlights the active tab from the real pathname (via usePathname,
+ * not the global `location`) and pushes locale-prefixed routes.
  * @component BottomBar
  */
 const BottomBar: FunctionComponent<Props> = ({ items }) => {
   const router = useRouter();
+  const pathname = usePathname();
+  const locale = useLocale();
+
+  // The active tab is the longest item path that prefixes the current pathname,
+  // so `/patients/123` still selects the `/patients` tab and `/` never over-matches.
+  const activePath = useMemo(() => {
+    const matches = items
+      .map((item) => item.path)
+      .filter((path): path is string => Boolean(path))
+      .filter((path) => {
+        const prefixed = withLocale(locale, path);
+        return path === '/' ? pathname === prefixed : pathname.startsWith(prefixed);
+      })
+      .sort((a, b) => b.length - a.length);
+    return matches[0] ?? false;
+  }, [items, pathname, locale]);
 
   const onNavigationChange = useCallback(
     (_event: unknown, newValue: string) => {
-      router.push(newValue);
+      router.push(withLocale(locale, newValue));
     },
-    [router]
+    [router, locale]
   );
 
   return (
-    <BottomNavigation
-      value={location.pathname} // Automatically highlights bottom navigation for current page
-      showLabels // Always show labels on bottom navigation, otherwise label visible only for active page
-      onChange={onNavigationChange}
+    <Paper
+      elevation={3}
+      square
+      component="nav"
+      sx={{ borderTop: '1px solid', borderColor: 'divider' }}
     >
-      {items.map(({ title, path, icon }) => (
-        <BottomNavigationAction key={`${title}-${path}`} label={title} value={path} icon={<AppIcon icon={icon} />} />
-      ))}
-    </BottomNavigation>
+      <BottomNavigation value={activePath} showLabels onChange={onNavigationChange}>
+        {items.map(({ title, path, icon }) => (
+          <BottomNavigationAction key={`${title}-${path}`} label={title} value={path} icon={<AppIcon icon={icon} />} />
+        ))}
+      </BottomNavigation>
+    </Paper>
   );
 };
 

client/src/layout/index.tsx

@@ -1,4 +1,7 @@
 import PrivateLayout from './PrivateLayout';
 import PublicLayout from './PublicLayout';
+import CustomerLayout from './CustomerLayout';
+import NurseLayout from './NurseLayout';
+import AdminLayout from './AdminLayout';
 
-export { PublicLayout, PrivateLayout };
+export { PublicLayout, PrivateLayout, CustomerLayout, NurseLayout, AdminLayout };