## Project Overview

- Name: **TiDB Cloud Management Portal UI** (`tidbcloud/management-portal-ui`).
- Frontend app built with **React 18** + **TypeScript**.
- Build tool: **Rsbuild**.
- Main responsibility: Internal management portal UI for TiDB Cloud operations, tenant/project/cluster management, DevOps workflows, IAM/RBAC, incidents, billing, and Traffic Mirror features.

---

## Tech Stack

- **Core**: React 18, TypeScript
- **Build**: Rsbuild (`@rsbuild/core` + `@rsbuild/plugin-react` + `@rsbuild/plugin-type-check`)
- **Routing**: `react-router-dom` v5
- **State / Data**:
  - Server state: `react-query` v3
  - Local/page state: React hooks (`useState`, `useMemo`, `useEffect`, etc.)
- **UI**: `antd` v4 + `@tidbcloud/uikit`
  - If unsure about uikit usage, check: `node_modules/@tidbcloud/uikit/llms.txt`
- **Forms**: Mostly Ant Design Form, with `react-hook-form` available in project
- **API Client**: OpenAPI clients generated by **orval**
- **Testing**: Jest + Testing Library
- **Formatting/Linting**: Prettier + ESLint (React App config)

---

## Important Commands

- Install dependencies:
  - `yarn`
- Start dev server:
  - `yarn start`
- Generate API clients:
  - `yarn gen:api`
- Build:
  - `yarn build`
- Unit tests:
  - `yarn test`
- Bundle analyze:
  - `yarn analyze`

Preferred package manager: **yarn (classic)** (`packageManager: yarn@1.22.22`).

---

## Project Structure

- `src/pages/`: Route-level pages (major business domains live here).
- `src/components/`: Reusable shared components (tables, forms, loaders, popovers, etc.).
- `src/apiClient/`: API-related code.
  - `src/apiClient/api/` and `src/apiClient/services/**`: generated OpenAPI clients/schemas.
  - `src/apiClient/custom-instance.ts`: shared orval mutator.
  - `src/apiClient/axios.tsx`: axios interceptors and error handling.
- `src/routes.tsx`: Central route registry.
- `src/utils/`: Shared utils/hooks and unit tests (`src/utils/__tests__`).
- `src/uikit/`: Local uikit wrappers and theme integration.
- `swagger/` + `swagger.json`: OpenAPI source files.
- `orval.config.ts`: API generation config.
- `scripts/`: release/hotfix/changelog scripts.

---

## API Generation Rules (orval)

Where to look:

- Orval config: `orval.config.ts`
- Swagger files: `./swagger.json`, `./swagger/*.swagger.json`
- Generated outputs:
  - `src/apiClient/api/**`
  - `src/apiClient/services/**`

Rules:

- Do **not** manually edit generated API files under `src/apiClient/api/**` or `src/apiClient/services/**`.
- If API signatures/behavior need updates, modify `orval.config.ts` and/or swagger source, then re-run `yarn gen:api`.
- Keep `customInstance` (`src/apiClient/custom-instance.ts`) as the shared request mutator entry for generated clients.

---

## Import & Code Style

- TypeScript `baseUrl` is `src`; prefer absolute imports from project roots like:
  - `apiClient/...`
  - `components/...`
  - `pages/...`
  - `utils/...`
- Follow ESLint import ordering (`.eslintrc.js`): builtin/external/internal groups with blank lines between groups and alphabetical sorting.
- Formatting is controlled by Prettier:
  - `singleQuote: true`
  - `semi: false`
  - `printWidth: 80`
  - `trailingComma: none`
- Keep file edits minimal and consistent with existing style in the touched module.

---

## UI & Interaction Conventions

- Prefer existing shared components/hooks before creating new abstractions (`src/components`, `src/utils/hooks`).
- Keep Ant Design + uikit usage consistent with neighboring pages.
- Existing codebase already uses `data-mp-event` for key click tracking in several flows; preserve tracking attributes when modifying related UI behavior.
- Use/keep `data-testid` only where tests rely on it; avoid noisy or unstable selectors.

---

## Testing & Verification

When making code changes, choose the smallest valid verification set:

- For logic-only changes: run targeted unit tests and/or `yarn test`.
- For UI/route/API integration changes: at least run `yarn build` to catch type and compile issues.
- For API model changes: run `yarn gen:api` and confirm generated code compiles with `yarn build`.

If full verification is too expensive, run the closest scoped checks and report what was not executed.

---

## Git & PR Conventions

- Commit messages should follow **Conventional Commits** (from project README conventions).
- Keep PR descriptions aligned with `.github/pull_request_template.md`:
  - problem statement
  - what changed
  - checklist/docs/CI notes
  - UI screenshots when applicable

---

## Common Pitfalls

- `react-router-dom` is v5; do not apply v6 APIs (`Routes`, `useNavigate`, etc.) in this repo.
- Generated API directories are easy to accidentally edit; always confirm whether a file is generated before manual changes.
- This repository contains both `moment` and `dayjs`; follow existing local module conventions instead of forcing broad date-library migrations in feature PRs.

---

## Useful Files

- `package.json` — scripts and dependency versions
- `rsbuild.config.ts` — bundling + env injection + type-check plugin
- `tsconfig.json` — strict TS options + path baseUrl
- `.eslintrc.js` / `.prettierrc` — style and lint rules
- `src/routes.tsx` — all route definitions
- `src/apiClient/custom-instance.ts` — orval mutator
- `src/apiClient/axios.tsx` — request/response interceptor behavior
- `orval.config.ts` — generated API wiring
- `.github/pull_request_template.md` — PR expectations