# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview **ClinicPro** — a clinic management and appointment booking platform migrated from Drupal to Symfony 7. It consists of a Symfony REST API backend and a React 19 admin SPA bundled inside Symfony via Webpack Encore. - **Local URL:** `https://clinic-pro.ddev.site` - **Admin panel:** `https://clinic-pro.ddev.site/admin` - **Swagger UI:** `https://clinic-pro.ddev.site/api/doc` --- ## Commands All commands run inside ddev: prefix with `ddev exec` unless noted. ### First-time setup ```bash ddev exec composer install ddev exec php bin/console lexik:jwt:generate-keypair # generate JWT keys ddev exec php bin/console doctrine:migrations:migrate --no-interaction ddev exec yarn install && ddev exec yarn dev ddev exec php bin/console app:create-admin # create first admin user ``` ### Backend (PHP/Symfony) ```bash ddev exec php bin/console cache:clear ddev exec php bin/console doctrine:migrations:migrate --no-interaction ddev exec php bin/console doctrine:migrations:diff --no-interaction # generate migration after entity change ddev exec php bin/console debug:router | grep api ddev exec php bin/console messenger:consume async # start queue worker (SMS, async jobs) ddev exec php bin/console messenger:consume scheduler_default # run scheduled tasks (expires unpaid bookings every 1 min) # Tests ddev exec php bin/phpunit ddev exec php bin/phpunit tests/SomeTest.php # single test file # Static analysis (level 5, with Symfony + Doctrine extensions) ddev exec php vendor/bin/phpstan analyse ``` ### Frontend (React/TypeScript) ```bash ddev exec yarn dev # one-off dev build (use this to check for errors) ddev exec yarn watch # watch mode ddev exec yarn build # production build # Type check only (faster) ddev exec npx tsc --noEmit --project tsconfig.json ``` > **Note:** The CSS build has a known `lightningcss.linux-arm64-gnu.node` native module error inside ddev — this is pre-existing and does not block JS/TS compilation. TypeScript errors only appear in TSC output. --- ## Architecture ### Backend — `src/` Domain-driven structure; each domain is its own namespace under `App\\`: ``` src/ Admin/Controller/AdminApiController.php # all admin-only list/stats endpoints Appointment/ Doctor/ Clinic/ Auth/ Payment/ Rating/ Blog/ Representation/ Secretary/ Category/ Settlement/ Sms/ Shared/Controller/BaseController.php # all controllers extend this Shared/Constant/ErrorCodes.php ``` **Every controller extends `BaseController`** which provides four response helpers: | Method | Shape | When to use | |--------|-------|-------------| | `$this->success($data)` | `{ success, data: $data }` | Single resource / action | | `$this->paginated($items, $total, $page, $limit)` | `{ success, data: $items[], meta: { totalRecords, totalPages, currentPage } }` | Admin list endpoints | | `$this->error($code, $message, $status)` | `{ success:false, errors:[{code,message}] }` | All error responses | | `$this->validationError($violations)` | `{ success:false, errors:[{code,field,message}] }` HTTP 422 | Input validation failures | **Domain exceptions:** throw `AppException(ErrorCodes::ERR_XXX, null, $httpStatus)` anywhere in the domain — `ExceptionSubscriber` catches it and calls `$this->error()` automatically. All error codes and their Persian messages live in `src/Shared/Constant/ErrorCodes.php`. **Critical pitfall — double-nested responses:** `$this->success(['data' => $rep->toArray()])` produces `{ data: { data: {...} } }`, so the frontend must extract with `data?.data?.data`. The `paginated()` helper does NOT nest — it returns `data` as a flat array. ### Frontend — `assets/admin/` Single-page app mounted at `/admin/*`: ``` assets/admin/ App.tsx # React Router routes pages/ # one file per page components/ ui/ # DataTable, Modal, ConfirmDialog, PageHeader, StatusBadge, Pagination, # SearchableSelect, PersianDateInput, PersianCalendar, AppointmentStatusDropdown layout/ # AdminLayout, Sidebar, Topbar hooks/ # custom React hooks lib/api.ts # fetch wrapper (reads JWT from localStorage key: clinicpro-auth) lib/utils.ts # formatRial, formatNumber, formatDate, formatDateTime types/index.ts # all TypeScript interfaces stores/ authStore.ts # Zustand auth store (persisted to localStorage) uiStore.ts # sidebar open/close state ``` **Data fetching pattern:** TanStack Query v5 (`useQuery` / `useMutation`). Query keys use `['resource-name', page, filters]`. **API response types in `lib/api.ts`:** - `ApiResponse` — for single-resource responses: extract with `data?.data` - `PaginatedResponse` — for admin lists: items at `data?.data`, total at `data?.meta?.totalRecords` **Forms:** React Hook Form + Zod resolver. Schema defined with `z.object()`, type inferred with `z.infer`. ### Auth - JWT stored in Zustand store → `localStorage['clinicpro-auth']` → `state.token` - `api.ts` reads it automatically for every request - Admin routes require `ROLE_ADMIN`. `#[IsGranted('ROLE_ADMIN')]` on controller class or method. - Public endpoints listed in `config/packages/security.yaml` under `public_endpoints` firewall pattern ### Category / Bundle system Categories are polymorphic via a `bundle` string field. Used for: `state`, `city`, `specially_doctor`, `doctor_services`, `insurance_type`, `supplementary_insurance`, `tag`. City IDs (integer FK to `categories.id` where `bundle='city'`) are stored on entities like `Representation.cityId`. To get the city name, LEFT JOIN the categories table in DQL. ### Database - MariaDB 11.8 via ddev - Doctrine ORM with integer Unix timestamps (`createdAt`, `updatedAt`) — **not** DateTime objects - All admin list queries in `AdminApiController` use DQL array hydration (`.getArrayResult()`) to avoid triggering non-existent getter errors on entities - Migrations in `migrations/` — always run `doctrine:migrations:diff` after entity changes --- ## Key Patterns **Adding a new admin list endpoint (backend):** 1. Add method to `src/Admin/Controller/AdminApiController.php` 2. Use `$this->em->createQueryBuilder()` with `->getArrayResult()` (never use entity getters in admin list queries) 3. Return `$this->paginated($items, $total, $page, $limit)` **Adding a new admin page (frontend):** 1. Create `assets/admin/pages/XxxPage.tsx` 2. Use `PaginatedResponse` with `useQuery` 3. Extract: `data?.data` for items, `data?.meta?.totalRecords` for total 4. Add route in `App.tsx` 5. Add UI components: ``, ``, ``, `` **Category API endpoint pattern:** `GET /api/v1/categorys/{bundle}` (note: typo `categorys` is intentional — existing route). Response is double-nested: extract array with `data?.data?.data ?? []`. --- ## Standing Rule — API Documentation **Whenever any API endpoint is created or modified** (controller file, route, request/response structure, error code, permission), the corresponding file in `docs/api/` **must be updated in the same session**. | Changed file | Doc to update | |---|---| | `src/Auth/*` | `docs/api/auth.md` | | `src/Doctor/*` | `docs/api/doctor.md` | | `src/Clinic/*` | `docs/api/clinic.md` + `docs/api/clinic-invitation.md` | | `src/Appointment/Controller/AppointmentController.php` | `docs/api/appointment.md` | | `src/Appointment/Controller/AppointmentSettings*` | `docs/api/appointment-settings.md` | | `src/Payment/*` | `docs/api/payment.md` | | `src/Settlement/*` | `docs/api/settlement.md` | | `src/Rating/*` | `docs/api/rating.md` | | `src/Secretary/*` | `docs/api/secretary.md` | | `src/Representation/*` | `docs/api/representation.md` | | `src/Sms/*` | `docs/api/sms.md` | | `src/Blog/*` | `docs/api/blog.md` | | `src/Admin/*` | `docs/api/admin.md` | | Category/Province/City controllers | `docs/api/location.md`, `docs/api/specialty.md`, `docs/api/insurance.md`, `docs/api/doctor-service.md`, `docs/api/tag.md` |