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

File & Folder Naming

Standard React community conventions:

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

Layer, entity, and infrastructure folders are lowercase; component, form, and widget folders are PascalCase, matching the component they contain:

src/
  data/
    user/
      userAPI.ts
      hooks.ts              # or useUserQuery.ts, useCreateUserMutation.ts
      userDTO.ts
      userMapper.ts
  view/
    components/
      UserAvatar.tsx
    widgets/
      UserProfileWidget/
        index.ts
        UserProfileWidget.tsx
    forms/
      CreateUserForm/
        form.ts
        Component.tsx
        submit.ts
        index.ts
  shared/
    ui/
      Button.tsx
    hooks/
      useDebounce.ts
    utils/
      formatDate.ts

Case-Only Rename Problem (macOS + Git)

macOS file systems are case-insensitive by default while Git is case-sensitive internally, so a rename like api.ts → Api.ts may not be detected by Git, break CI on case-sensitive Linux, or leave the repo inconsistent.

Required: rename in two committed steps, for files and folders alike — never by case only in one step, never relying on IDE rename alone; verify with git status:

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

Optionally make Git case-sensitive for this repo with git config core.ignorecase false (verify with git config core.ignorecase). Even then, the file system stays case-insensitive and case-only renames can still misbehave — the two-step rename remains the safest approach.