Skip to content

CLAUDE.md

Latest commit

 

History

History
123 lines (87 loc) · 5.45 KB

CLAUDE.md

File metadata and controls

123 lines (87 loc) · 5.45 KB

CLAUDE.md

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 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 (@/* → 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. 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().

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:

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:

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:

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