> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Frontend Overview

The frontend in `web/` is a React 19 and TypeScript single-page application. Vite 8 handles development and builds, Ant Design 6 provides the primary UI components, and Zustand manages global state.

## Development commands

```bash
cd web
pnpm install
pnpm dev       # Start the development server
pnpm build     # TypeScript checks and production build
pnpm lint      # Run Oxlint
pnpm preview   # Preview the production build
```

## Source layers

| Directory              | Responsibility                                                     |
| ---------------------- | ------------------------------------------------------------------ |
| `src/pages/`           | Business pages and file-based route inputs                         |
| `src/api/`             | Endpoints grouped into `system`, `common`, `ai`, and other domains |
| `src/components/`      | Shared tables, forms, uploads, permission buttons, and more        |
| `src/domain/`          | Business data types                                                |
| `src/stores/`          | Zustand stores for users, global settings, and dictionaries        |
| `src/layout/`          | Admin shell, navigation, and content area                          |
| `src/locales/`         | `zh_CN` and `en_US` translations                                   |
| `src/utils/request.ts` | Axios setup, deduplication, authentication, and error handling     |

## API base URL

The development URL is configured in `web/.env.development`:

```dotenv
VITE_BASE_URL=http://localhost:8000
```

Production values belong in `web/.env.production`. Restart Vite after changing environment variables.

## Request convention

Define endpoint functions in `src/api/` instead of creating Axios instances inside components:

```ts
import createAxios from '@/utils/request';

export function queryDept() {
  return createAxios({
    url: '/system/dept',
    method: 'get',
  });
}
```

The wrapper adds `Authorization: Bearer <token>` and `User-Language`, and centrally handles 401 responses, duplicate requests, and business errors. See [API Response Conventions](/en/backend/api-conventions.md) for the response schema.