Frontend

Results change every minute and nobody needs an emergency search page in Google, so there's nothing to pre-build (no SSG) and no SEO reason for server rendering (no SSR). A small Vite SPA loads once and then only moves JSON.

Everything for one feature (its pages, components, hooks and API calls) lives together, so working on holds means opening one folder.

client/src/
├─ main.tsx              providers: QueryClient, AuthProvider, Router
├─ app/
│  ├─ router.tsx         createBrowserRouter, lazy routes
│  ├─ RootLayout.tsx     header, toaster, error boundary
│  ├─ RequireAuth.tsx
│  └─ RequireRole.tsx
├─ api/
│  ├─ client.ts          apiFetch: token, refresh, ApiError
│  └─ types.ts           Pharmacy, StockItem, Hold, User
├─ features/
│  ├─ auth/              LoginPage RegisterPage AuthContext
│  ├─ search/            SearchPage ResultCard useSearch
│  ├─ pharmacy/          PharmacyDetailPage
│  ├─ holds/             MyHoldsPage usePlaceHold useCountdown
│  ├─ pharmacist/        Onboarding Stock Hours IncomingHolds
│  └─ admin/             Verifications Compliance SearchIndex
├─ components/ui/        Button Input Badge Skeleton Modal Toast
├─ hooks/                useDebounce useGeolocation useOnline
└─ lib/                  schemas.ts format.ts constants.ts

Route groups mirror the backend's roles. Hiding a page here is convenience only; the API's RBAC middleware is the real check.

Each wrapper does one job, in this order, from the outside in.

// app/router.tsx
const PharmacistArea = lazy(() => import('../features/pharmacist/PharmacistArea'));
const AdminArea      = lazy(() => import('../features/admin/AdminArea'));

export const router = createBrowserRouter([{
  element: <RootLayout />, errorElement: <RouteError />,
  children: [
    { path: '/',             element: <SearchPage /> },
    { path: '/pharmacy/:id', element: <PharmacyDetailPage /> },
    { path: '/login',        element: <LoginPage /> },
    { path: '/register',     element: <RegisterPage /> },
    { element: <RequireAuth />, children: [
      { element: <RequireRole roles={['PATIENT']} />,
        children: [{ path: '/holds', element: <MyHoldsPage /> }] },
      { element: <RequireRole roles={['PHARMACIST']} />,
        children: [{ path: '/pharmacist/*', element: <Suspense fallback={<PageSkeleton/>}><PharmacistArea/></Suspense> }] },
      { element: <RequireRole roles={['ADMIN']} />,
        children: [{ path: '/admin/*', element: <Suspense fallback={<PageSkeleton/>}><AdminArea/></Suspense> }] },
    ]},
    { path: '*', element: <NotFound /> },
  ],
}]);

Container pages own the data; the pieces inside only take props.

The most common React mistake is putting API data into useState or a global store. Each kind of state has a different lifetime, so each gets its own tool.

Every data call and every browser API is wrapped in a hook, so components stay small and the logic can be tested without rendering anything.

Every request goes through apiFetch. It adds the token, turns error bodies into one ApiError type, and on a 401 runs a single refresh that every waiting request shares.

// api/client.ts
let refreshing: Promise<string | null> | null = null;   // shared by every 401

async function refreshOnce() {
  refreshing ??= fetch('/api/v1/auth/refresh', { method: 'POST', credentials: 'include' })
    .then(r => (r.ok ? r.json() : null))
    .then(body => { const t = body?.accessToken ?? null; auth.setToken(t); return t; })
    .finally(() => { refreshing = null; });
  return refreshing;
}

export async function apiFetch<T>(path: string, init: RequestInit = {}, retried = false): Promise<T> {
  const res = await fetch('/api/v1' + path, {
    ...init, credentials: 'include',
    headers: { 'Content-Type': 'application/json',
               ...(auth.token ? { Authorization: `Bearer ${auth.token}` } : {}),
               ...init.headers },
  });
  if (res.status === 401 && !retried && !path.startsWith('/auth/')) {
    const token = await refreshOnce();
    if (token) return apiFetch<T>(path, init, true);
    auth.logout();                                        // clears cache, goes to /login
  }
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new ApiError(res.status, body.error?.message ?? 'Something went wrong', body.error?.details);
  }
  return res.status === 204 ? (undefined as T) : res.json();
}

React Hook Form keeps typing fast; Zod checks the same rules the API checks, so most mistakes are caught before a request is sent. The API still validates everything.

// lib/schemas.ts
export const onboardingSchema = z.object({
  name:          z.string().min(3),
  address:       z.string().min(10),
  area:          z.string(),
  lat:           z.number().min(-90).max(90),
  lng:           z.number().min(-180).max(180),
  phone:         z.string().regex(/^[6-9]\d{9}$/, 'Enter a 10-digit mobile number'),
  licenseNumber: z.string().min(5),
  issueDate:     z.coerce.date(),
  expiryDate:    z.coerce.date(),
}).refine(d => d.expiryDate > new Date(),
          { path: ['expiryDate'], message: 'Licence has already expired' });

A blank screen in an emergency reads as "the app is broken". Each data view designs all six.

Designed for one thumb, a slow phone, bad light and a stressed person.

The number that matters is time from opening the app to the first useful result on a mid-range phone on 4G.

The frontend and API look like one site to the browser, so the refresh cookie is first-party and there is no CORS to configure.

// vite.config.ts: dev only
server: { proxy: { '/api': 'http://localhost:4000' } }

// vercel.json: production
{
  "rewrites": [
    { "source": "/api/:path*",
      "destination": "https://velora-api.herokuapp.com/api/:path*" },
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

// package.json scripts
"dev": "vite", "build": "tsc -b && vite build",
"lint": "eslint .", "test": "vitest"

Vitest + React Testing Library. Test behaviour a user would notice, not implementation details.