# Repository Guidelines

## Project Structure & Module Organization

- `packages/clinic-web/`: main React UI (esbuild via `gulp`); source in `src/`, static assets in `public/`, build output in `dist/`.
- `packages/clinic-client/`: TypeScript API client generated from OpenAPI (`swagger/`).
- `packages/drill-test-client/`: additional generated API client.
- `docker/`: Dockerfiles and `release-version` used for image tagging.
- `changelog/`: release note helper script (`changelog/release.sh`).
- `patches/`: `pnpm` patched dependencies.
- `packages/clinic-web/src/pages/`: route pages, organized by feature.
- `packages/clinic-web/src/components/`: shared UI components.
- `packages/clinic-web/src/hooks/`: custom hooks, including Zustand-backed state in `state.ts`.
- `packages/clinic-web/src/api/`: API wrapper functions around generated clients.
- `packages/clinic-web/src/utils/`: shared utilities, including `env-config.ts` for `REACT_APP_*` variables.
- `packages/clinic-web/src/mocks/`: MSW handlers for mocked development.

## Architecture Notes

- Routing uses React Router v6 with `HashRouter`; top-level routes live in `packages/clinic-web/src/App.tsx`, and feature route trees commonly use descendant routes such as `orgs/*`.
- State is mainly managed with Zustand stores in `packages/clinic-web/src/hooks/state.ts`; data fetching uses SWR broadly, with react-query also present in some feature areas.
- Generated axios clients are imported from `@clinic/client` and `@drill-test/client`; the web app wraps requests through `packages/clinic-web/src/api/base.ts` for CSRF headers, auth redirects, and default error handling.
- Styling combines Tailwind CSS, Mantine UI, and Ant Design v4. Keep existing component-library choices within the touched area unless there is a concrete reason to change.
- i18n uses react-i18next with YAML translations under `packages/clinic-web/src/translations/` and feature-specific translation folders.
- Path aliases: `~/*` maps to `packages/clinic-web/src/*`; `@clinic/client` and `@drill-test/client` are workspace generated clients.

## Build, Test, and Development Commands

- `pnpm i`: install workspace dependencies (installs Husky hooks).
- `pnpm dev`: run all packages in watch mode; UI serves at `http://localhost:8181/clinic/`.
- `pnpm dev:mock`: run dev with MSW mocking enabled (`REACT_APP_MSW=true`).
- `pnpm build`: build all packages (CI runs this on PRs).
- `pnpm gen:api`: regenerate API clients (runs `packages/*/swagger/gen_api.sh`).
- `UPDATE_SPEC=false pnpm gen:api`: regenerate API clients from existing local `swagger/doc.json` files.
- `DEPLOY_ENV=staging pnpm gen:api`: regenerate API clients from the staging Clinic spec where supported.
- Web-only checks: `pnpm --filter @clinic/web lint`, `pnpm --filter @clinic/web type-check`, `pnpm --filter @clinic/web fmt`.

## Coding Style & Naming Conventions

- Indentation: 2 spaces (`.editorconfig`). Prettier uses single quotes + no semicolons (`.prettierrc`).
- Linting: ESLint extends `react-app` and enforces import ordering (`.eslintrc.js`). Keep `React` in scope in `.tsx` files.
- Pre-commit: `lint-staged` runs `eslint --fix` + `prettier --write` on staged files.
- Naming: React components `PascalCase.tsx` (e.g., `AutoRefreshButton.tsx`), hooks `useXxx.ts`, routes/pages under `packages/clinic-web/src/pages/`.

## Testing Guidelines

This repo doesn’t currently include a dedicated test runner; rely on `type-check`, `lint`, and manual UI verification for changes.

## Commit & Pull Request Guidelines

- Commit history commonly uses Conventional Commit prefixes (`feat:`, `fix:`, `refactor:`) and often includes a PR reference like `(#123)`.
- PRs should explain intent + impact, link relevant issues, include screenshots/GIFs for UI changes, and note any `gen:api` regeneration. Ensure `pnpm build` passes.

## Release And Hotfix Workflow

Branch model:

- `main` is the code trunk.
- `release` is the release trunk. It should contain the released code plus release-only files such as `docker/release-version` and `changelog/`.

Normal code merge and release flow:

1. Update `main`, branch from `main`, and make the code change.
2. Commit and push the branch, then open a PR targeting `main`.
3. After the PR merges, the code is on the main trunk.
4. When a release is needed, update both `main` and `release`, check out `release`, and create a `release-YYYYMMDD.XX` branch. The branch suffix must match the version written to `docker/release-version`.
5. Merge `main` into the release branch. If source-code conflicts occur, resolve them with the `main` implementation unless the conflict is in release-only metadata.
6. Update `docker/release-version`. Keep the first line as exactly one comment line, then put the version on the next line. The version format is `YYYYMMDD.XX`, for example `20260623.01`, where `XX` is the release sequence for that day.
7. Update `changelog/` for the release.
8. Commit and push the release branch, then open a PR targeting `release`.

Hotfix flow:

1. Check out `main`, update it, and branch from `main` for the hotfix.
2. Make the fix.
3. Commit and push the branch, then open a PR targeting `main`.
4. Prepare the release hotfix PR: check out `release`, update it, create a hotfix release branch, cherry-pick the just-merged hotfix PR changes, then update `docker/release-version` and `changelog/`.
5. Commit and push the hotfix release branch, then open a PR targeting `release`.

## Generated Assets

- `packages/slow-log-explorer` builds into `packages/clinic-web/public/slow-log-explorer-app/` through Vite.
- `pnpm build` and CI rebuild this directory, and the final Docker image uses the rebuilt `packages/clinic-web/dist`.
- Do not commit generated files under `packages/clinic-web/public/slow-log-explorer-app/`. If these files appear in a merge or release conflict, remove the tracked generated files and rely on the build output.

## Configuration & Security

- Runtime config lives in `packages/clinic-web/.env*` and is exposed via `REACT_APP_*` variables; centralize new vars in `packages/clinic-web/src/utils/env-config.ts`.
- The web builder loads `.env`, then `.env.${DEPLOY_ENV}`; in development `DEPLOY_ENV` defaults to `local_dev`, and `.env.local` can override values locally.
- Use local-only env overrides for developer settings, and don’t commit secrets.
- For release work, re-check the current release branch, `origin/main`, `docker/release-version`, and `changelog/` before executing release steps.