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/app/[locale]/(private-routes)/(customer)/bookings/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function BookingsPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="bookings" title={t('bookings')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/(customer)/layout.tsx

@@ -0,0 +1,12 @@
+'use client';
+import type { ReactNode } from 'react';
+import { CustomerLayout } from '@/layout';
+
+/*
+ * Customer (family) route group — the primary mobile-first experience with the
+ * 5-tab bottom nav. A route group `(customer)` adds chrome without adding a URL
+ * segment, so these screens live at the app root (/, /bookings, /patients, …).
+ */
+export default function CustomerRouteLayout({ children }: { children: ReactNode }) {
+  return <CustomerLayout>{children}</CustomerLayout>;
+}

client/src/app/[locale]/(private-routes)/(customer)/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function CustomerHomePage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="home" title={t('home')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/(customer)/patients/page.tsx

@@ -0,0 +1,101 @@
+'use client';
+import { ChangeEvent, useState } from 'react';
+import { useLocale, useTranslations } from 'next-intl';
+import { Box, Chip, List, ListItem, ListItemText, MenuItem, Stack, TextField, Typography } from '@mui/material';
+import { useSnackbar } from 'notistack';
+import { AppButton, AppLoading } from '@/components';
+import { usePatients, useAddPatient } from '@/services/patients';
+import type { Gender } from '@/services/patients/types';
+import { formatShamsiDate } from '@/utils';
+
+/**
+ * Reference screen for the services/{domain} + React Query pattern (§3.3). It reads the
+ * mocked patients list via usePatients (cached with a staleTime) and adds one via
+ * useAddPatient, whose onSuccess invalidates the list so the new row appears without a
+ * manual refetch — visible in the React Query Devtools.
+ */
+export default function PatientsPage() {
+  const t = useTranslations('patients');
+  const locale = useLocale();
+  const { enqueueSnackbar } = useSnackbar();
+
+  const { data, isLoading } = usePatients();
+  const addPatient = useAddPatient();
+
+  const [name, setName] = useState('');
+  const [gender, setGender] = useState<Gender>('female');
+
+  const genderLabel = (value: Gender) => (value === 'male' ? t('gender_male') : t('gender_female'));
+
+  const handleAdd = () => {
+    const fullName = name.trim();
+    if (!fullName) return;
+    addPatient.mutate(
+      { fullName, gender },
+      {
+        onSuccess: () => {
+          setName('');
+          enqueueSnackbar(t('added'), { variant: 'success' });
+        },
+      }
+    );
+  };
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 3 }}>
+      <Box>
+        <Typography variant="h5" component="h1">
+          {t('title')}
+        </Typography>
+        <Typography variant="body2" sx={{ color: 'text.secondary' }}>
+          {t('subtitle')}
+        </Typography>
+      </Box>
+
+      <Stack direction={{ xs: 'column', sm: 'row' }} spacing={1} sx={{ alignItems: { sm: 'flex-start' } }}>
+        <TextField
+          label={t('name_label')}
+          value={name}
+          onChange={(event: ChangeEvent<HTMLInputElement>) => setName(event.target.value)}
+          fullWidth
+        />
+        <TextField
+          select
+          label={t('gender_label')}
+          value={gender}
+          onChange={(event: ChangeEvent<HTMLInputElement>) => setGender(event.target.value as Gender)}
+          sx={{ minWidth: 140 }}
+        >
+          <MenuItem value="female">{t('gender_female')}</MenuItem>
+          <MenuItem value="male">{t('gender_male')}</MenuItem>
+        </TextField>
+        <AppButton
+          color="primary"
+          startIcon="add"
+          onClick={handleAdd}
+          disabled={!name.trim() || addPatient.isPending}
+        >
+          {t('add')}
+        </AppButton>
+      </Stack>
+
+      {isLoading ? (
+        <AppLoading />
+      ) : !data || data.items.length === 0 ? (
+        <Typography sx={{ color: 'text.secondary' }}>{t('empty')}</Typography>
+      ) : (
+        <List>
+          {data.items.map((patient) => (
+            <ListItem
+              key={patient.id}
+              divider
+              secondaryAction={<Chip size="small" label={genderLabel(patient.gender)} />}
+            >
+              <ListItemText primary={patient.fullName} secondary={formatShamsiDate(patient.createdAtUtc, locale)} />
+            </ListItem>
+          ))}
+        </List>
+      )}
+    </Box>
+  );
+}

client/src/app/[locale]/(private-routes)/(customer)/profile/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function ProfilePage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="profile" title={t('profile')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/(customer)/wallet/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function WalletPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="wallet" title={t('wallet')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/admin/layout.tsx

@@ -0,0 +1,11 @@
+'use client';
+import type { ReactNode } from 'react';
+import { AdminLayout } from '@/layout';
+
+/*
+ * Admin / backoffice route group (/admin/…) — desktop-oriented ops console (f15)
+ * with a persistent sidebar.
+ */
+export default function AdminRouteLayout({ children }: { children: ReactNode }) {
+  return <AdminLayout>{children}</AdminLayout>;
+}

client/src/app/[locale]/(private-routes)/admin/notifications/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function AdminNotificationsPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="notifications" title={t('notifications')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/admin/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function AdminOverviewPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="admin" title={t('overview')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/admin/users/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function AdminUsersPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="users" title={t('users')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/nurse/layout.tsx

@@ -0,0 +1,11 @@
+'use client';
+import type { ReactNode } from 'react';
+import { NurseLayout } from '@/layout';
+
+/*
+ * Nurse route group (/nurse/…) — its own shell (dashboard, verification, EVV visits).
+ * A real path segment keeps nurse screens namespaced under /nurse.
+ */
+export default function NurseRouteLayout({ children }: { children: ReactNode }) {
+  return <NurseLayout>{children}</NurseLayout>;
+}

client/src/app/[locale]/(private-routes)/nurse/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function NurseDashboardPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="dashboard" title={t('dashboard')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/nurse/verification/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function NurseVerificationPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="verification" title={t('verification')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/nurse/visits/page.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from 'next-intl/server';
+import { PlaceholderScreen } from '@/components';
+
+export default async function NurseVisitsPage() {
+  const t = await getTranslations('nav');
+  const tShell = await getTranslations('shell');
+  return <PlaceholderScreen icon="visits" title={t('visits')} description={tShell('placeholder_body')} />;
+}

client/src/app/[locale]/(private-routes)/page.tsx

@@ -1,13 +0,0 @@
-import { useTranslations } from 'next-intl'
-import Box from '@mui/material/Box'
-import Typography from '@mui/material/Typography'
-
-export default function HomePage() {
-  const t = useTranslations('toastDemo')
-
-  return (
-    <Box sx={{ p: 4 }}>
-     <Typography>Balin yaar</Typography>
-    </Box>
-  )
-}