admin/docs/apps-architecture/react-frontend/naming.md

# File & Folder Naming

## Table of Contents

- [Naming Convention](#naming-convention)
  - [Folders](#folders)
  - [Component Files](#component-files)
  - [Hook Files](#hook-files)
  - [Utility & Helper Files](#utility--helper-files)
  - [Other TypeScript Files](#other-typescript-files)
  - [Examples by Layer](#examples-by-layer)
- [Case-Only Rename Problem (macOS + Git)](#case-only-rename-problem-macos--git)
  - [Required: Correct Rename Procedure](#required-correct-rename-procedure)
  - [Making Git Case-Sensitive on macOS](#making-git-case-sensitive-on-macos)
  - [Important Reality Check](#important-reality-check)

## Naming Convention

We follow **standard React community naming conventions**:

These conventions apply to frontend apps and to module folders inside those apps. For example, `apps/admin/src/core/FileManager` may use PascalCase because it is a product module folder, while its layer folders such as `data`, `entities`, `providers`, `pages`, `view`, and `shared` stay lowercase.

| Type                   | Convention                                   | Example                               |
| ---------------------- | -------------------------------------------- | ------------------------------------- |
| Folders                | lowercase (PascalCase for component folders) | `user/`, `shared/`, `CreateUserForm/` |
| React component files  | PascalCase                                   | `UserProfile.tsx`, `Button.tsx`       |
| Hook files             | camelCase (`use` prefix)                     | `useDebounce.ts`, `useToggle.ts`      |
| Utility / helper files | camelCase                                    | `formatDate.ts`, `generateId.ts`      |
| API / service files    | camelCase (acronyms uppercase)               | `userAPI.ts`, `productAPI.ts`         |
| DTO / mapper files     | camelCase (acronyms uppercase)               | `userDTO.ts`, `userMapper.ts`         |
| Type / interface files | camelCase                                    | `types.ts`, `dto.ts`, `interfaces.ts` |
| Constants files        | camelCase                                    | `constants.ts`, `formConstants.ts`    |
| Config / entry files   | camelCase                                    | `index.ts`, `queryClient.ts`          |

### Folders

Layer and infrastructure folders use **lowercase**.
Component, form, and widget folders use **PascalCase** — matching the component they contain.

```
src/
  data/           # lowercase — layer folder
    user/         # lowercase — entity folder
    product/
  view/           # lowercase — layer folder
    components/
    forms/
      CreateUserForm/   # PascalCase — component folder
    widgets/
      UserProfileWidget/
  shared/
    ui/
    hooks/
    lib/
```

### Component Files

React component files use **PascalCase** — matching the name of the exported component.

```
UserProfile.tsx
ProductCard.tsx
LoginButton.tsx
UserProfileWidget.tsx
CreateProductForm.tsx
```

### Hook Files

Hook files use **camelCase** and always start with `use`.

```
useDebounce.ts
useToggle.ts
useLocalStorage.ts
useUserQuery.ts
useCreateProductMutation.ts
```

### Utility & Helper Files

Utility and helper files use **camelCase**.

```
formatDate.ts
formatCurrency.ts
generateId.ts
sleep.ts
```

### Other TypeScript Files

All other `.ts` files (APIs, DTOs, mappers, types, config) use **camelCase**, with acronyms kept uppercase.

```
userAPI.ts
userDTO.ts
userMapper.ts
types.ts
constants.ts
queryClient.ts
axiosInstance.ts
```

### Examples by Layer

#### `shared/`

```plaintext
shared/
├── ui/
│   ├── Button.tsx
│   ├── Modal.tsx
│   └── Card.tsx
│
├── hooks/
│   ├── useDebounce.ts
│   ├── useToggle.ts
│   └── useLocalStorage.ts
│
├── lib/
│   ├── axios/
│   │   └── axiosInstance.ts
│   └── query/
│       └── queryClient.ts
│
└── utils/
    ├── formatDate.ts
    └── formatCurrency.ts
```

#### `data/`

```plaintext
data/
├── user/
│   ├── userAPI.ts
│   ├── hooks.ts          # or useUserQuery.ts, useCreateUserMutation.ts
│   ├── userDTO.ts
│   └── userMapper.ts
│
└── product/
    ├── productAPI.ts
    ├── hooks.ts
    ├── productDTO.ts
    └── productMapper.ts
```

#### `providers/`

```plaintext
providers/
├── AppProviders.tsx
├── QueryProvider.tsx
├── RouterProvider.tsx
├── ThemeProvider.tsx
├── AuthProvider.tsx
├── I18nProvider.tsx
└── index.ts
```

#### `view/`

```plaintext
view/
├── components/
│   ├── UserAvatar.tsx
│   └── ProductCard.tsx
│
├── widgets/
│   └── UserProfileWidget/
│       ├── index.ts
│       └── UserProfileWidget.tsx
│
└── forms/
    └── CreateUserForm/
        ├── form.ts
        ├── Component.tsx
        ├── submit.ts
        └── index.ts
```

## Case-Only Rename Problem (macOS + Git)

macOS file systems are **case-insensitive by default**, while Git is **case-sensitive internally**.

Renaming a file like `api.ts` → `Api.ts` may:

- Not be detected by Git
- Break CI (Linux environments are case-sensitive)
- Cause inconsistent repository state

### REQUIRED: Correct Rename Procedure

If you **must rename a file or folder by case only**, you are required to perform a two-step rename.

#### Step 1 — Rename to Temporary Name

```bash
git mv userApi.ts userApi-temp.ts
git commit -m "chore: temporary rename userApi.ts to userApi-temp.ts"
```

#### Step 2 — Rename to Final Name

```bash
git mv userApi-temp.ts UserApi.ts
git commit -m "chore: rename userApi-temp.ts to UserApi.ts (case change)"
```

### Rules

- Never rename by case only in one step
- Always use an intermediate name
- Always commit both steps
- Applies to files and folders
- Do not rely only on IDE rename
- Always verify with `git status`

### Making Git Case-Sensitive on macOS

By default, Git on macOS usually has:

`core.ignorecase=true`

This makes Git ignore case-only changes.

#### Set Case Sensitivity for This Repository

```bash
git config core.ignorecase false
```

#### Verify:

```bash
git config core.ignorecase
```

It should return: `false`

### Important Reality Check

Even if `core.ignorecase=false`:

- macOS file system is still case-insensitive
- Case-only renames can still behave unexpectedly
- The two-step rename process is still the safest approach