Add instructions for claude

Author: bodhish

CLAUDE.md

@@ -2,20 +2,122 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## What is CARE?
+
+CARE is a Digital Public Good building an open source EMR + Hospital Management system. This is the React frontend (React 19 + TypeScript + Vite).
+
 ## Build/Lint/Test Commands
-- `npm run dev`: Start development server
-- `npm run build`: Build for production 
-- `npm run lint`: Run ESLint
-- `npm run lint-fix`: Run ESLint with auto-fix
-- `npm run format`: Format code with Prettier
-- `npm run playwright:test`: Run Playwright tests in headless mode
-- `npm run playwright:test:ui`: Run Playwright tests in interactive UI mode
+
+- `npm run dev` — Start dev server at http://localhost:4000
+- `npm run build` — Production build (takes 2+ minutes, set timeout to 180s+)
+- `npm run lint` — Run ESLint (takes 85s+, set timeout to 120s+)
+- `npm run lint-fix` — ESLint with auto-fix
+- `npm run format` — Prettier formatting
+- `npm run playwright:test` — Run all Playwright E2E tests headlessly
+- `npm run playwright:test -- tests/auth/login.spec.ts` — Run a single test file
+- `npm run playwright:test -- -g "test name"` — Run tests matching a pattern
+- `npm run playwright:test:ui` — Interactive Playwright UI mode
+
+Playwright requires a local backend running (`REACT_CARE_API_URL=http://127.0.0.1:9000` in `.env.local`) and `npm run playwright:install` for browsers.
 
 ## Code Style Guidelines
-- **TypeScript**: Strict mode, ES2022 target, path aliases (`@/*` for src)
+
+- **TypeScript**: Strict mode, ES2022 target, path aliases (`@/*` → `src/*`, `@careConfig` → `care.config.ts`)
 - **Formatting**: Double quotes, 2-space indent, semicolons required
-- **Imports**: Order by 3rd-party → library → CAREUI → UI → components → hooks → utils → relative
-- **Types**: Use `interface` for objects, avoid explicit `any`, proper nullability
-- **Naming**: PascalCase for components/classes, camelCase for variables/functions
-- **Components**: Organized by feature, maintain separation of concerns
-- **Error Handling**: Use dedicated error handlers, TypeScript strict null checks
+- **Imports**: Order by 3rd-party → library → CAREUI → UI → components → hooks → utils → relative. Prettier plugin auto-sorts on format.
+- **Types**: Use `interface` for objects, avoid `any`, prefer maps over enums
+- **Naming**: PascalCase for component files (`AuthWizard.tsx`), camelCase for hooks/utils (`useAuth.ts`), kebab-case for directories
+- **Components**: Functional components only, named exports preferred, one component per file
+- **i18n**: All user-facing strings must use i18next. English translations go in `public/locale/en.json`. Non-English managed via Crowdin — do not edit directly.
+
+## Architecture
+
+### Routing (Raviger)
+
+Routes defined in `src/Routers/routes/` (e.g., `FacilityRoutes.tsx`, `PatientRoutes.tsx`). Combined in `src/Routers/AppRouter.tsx`. Three routers: `PublicRouter`, `PatientRouter`, `AppRouter` — selected by auth state. Plugin routes injected via `usePluginRoutes()`.
+
+```typescript
+const FacilityRoutes: AppRoutes = {
+  "/facility/:facilityId/overview": ({ facilityId }) => <FacilityOverview facilityId={facilityId} />,
+};
+```
+
+Use `navigate()` from raviger for programmatic navigation.
+
+### API Layer (TanStack Query + custom wrappers)
+
+API routes defined in `src/types/{domain}/{domain}Api.ts` using typed route objects:
+
+```typescript
+export default {
+  list: {
+    path: "/api/v1/users/",
+    method: HttpMethod.GET,
+    TRes: Type<PaginatedResponse<UserReadMinimal>>(),
+  },
+} as const;
+```
+
+Queries use `query()` wrapper from `src/Utils/request/query.ts`:
+
+```typescript
+const { data } = useQuery({
+  queryKey: ["users"],
+  queryFn: query(userApi.list),
+});
+// With path/query params:
+queryFn: query(userApi.get, { pathParams: { username }, queryParams: { search } })
+```
+
+Mutations use `mutate()` wrapper from `src/Utils/request/mutate.ts`:
+
+```typescript
+const { mutate } = useMutation({
+  mutationFn: mutate(userApi.create),
+});
+```
+
+Also available: `query.debounced()` and `query.paginated()` for specialized use cases.
+
+Errors handled globally — session expiry redirects to `/session-expired`, 400/406 show toast notifications. Use `silent: true` to suppress.
+
+### State Management
+
+- **TanStack Query** — Server state (API data caching, refetching)
+- **Jotai atoms** (`src/atoms/`) — Lightweight client state (user, nav, filters)
+- **React Context** (`src/context/`) — Permissions (`PermissionContext`), keyboard shortcuts
+
+### UI Components
+
+Built on **shadcn/uishadcn/ui** + **Radix UI primitives** + **Tailwind CSS v4** (shadcn/ui pattern):
+- `src/components/ui/` — Base UI primitives (Button, Dialog, Form, Select, etc.). Do not modify these directly.
+- `src/CAREUI/` — Custom healthcare icon library, use `lucide-react` unless you are explicitly asked to use CAREUI icons. 
+- Forms use `react-hook-form` + `zod` validation with the custom `<Form>` component
+
+### Plugin System (Module Federation)
+
+Micro-frontend architecture via `@originjs/vite-plugin-federation`. Plugins configured via `REACT_ENABLED_APPS` env var. Plugin manifests define routes, components, tabs, and devices they provide. Key files: `src/PluginEngine.tsx`, `src/pluginTypes.ts`.
+
+### Auth Flow
+
+JWT tokens in localStorage. `AuthUserProvider` handles login/logout, token refresh (every 5 minutes), 2FA, and cross-tab session sync. Patient login uses separate OTP-based flow via `PatientRouter`.
+
+### Key Directories
+
+- `src/components/` — Feature-organized components (Auth, Facility, Patient, Encounter, Medicine, etc.)
+- `src/pages/` — Page components by feature (Admin, Appointments, Facility, Organization, Patient)
+- `src/types/` — Domain type definitions with corresponding `*Api.ts` route files
+- `src/Utils/request/` — API request infrastructure (query, mutate, error handling)
+- `src/hooks/` — Custom React hooks (auth, file management, plugins, etc.)
+- `src/Providers/` — Auth, history, patient user providers
+- `src/Routers/` — App routing and route definitions
+
+### Configuration
+
+`care.config.ts` centralizes runtime config (API URLs, feature flags, locale settings, plugin config). Environment variables prefixed with `REACT_`.
+
+## Git Workflow
+
+- Branch naming: `issues/{issue#}/{short-name}`
+- Default branch: `develop` (staging auto-deploys)
+- Pre-commit hooks via husky run Prettier and ESLint on staged files