# Naming Conventions

This document defines the file and identifier naming conventions for the Headquarter codebase.

## Frontend (`apps/web/src/`)

### React Components

**File naming:** PascalCase, matching the exported component name exactly.

```
✅ Good:
  components/features/git/FileBrowser.tsx
  components/features/dashboard/DashboardSummary.tsx
  pages/DashboardPage.tsx

❌ Bad:
  components/file-browser.tsx
  pages/dashboard.tsx
```

**Component naming:** PascalCase. Page components end with `Page`.

```typescript
// Component
export const FileBrowser = () => { ... }

// Page
export const DashboardPage = () => { ... }
```

### Hooks

**File naming:** camelCase with `use` prefix.

```
✅ Good:
  hooks/use-theme.ts
  hooks/use-dashboard-actions.ts
```

### API Modules

**File naming:** kebab-case.

```
✅ Good:
  api/tool-types.ts
  api/git-repositories.ts
  api/config-folders.ts
```

### Type Modules

**File naming:** kebab-case.

```
✅ Good:
  types/tool-type.ts
  types/git-repository.ts
```

### Utilities

**File naming:** kebab-case.

```
✅ Good:
  utils/terminal-protocol.ts
  utils/language.ts
```

### CSS Modules

**File naming:** kebab-case, matching the component file name with `.module.css` suffix.

```
✅ Good:
  FileBrowser.tsx + FileBrowser.module.css
```

## Backend (`apps/api/src/`)

### Routers

**File naming:** snake_case.

```
✅ Good:
  api/tool_instances.py
  api/git_repositories.py
```

### Services

**File naming:** snake_case.

```
✅ Good:
  services/docker/compose.py
  services/profile_resolver.py
```

### Models

**File naming:** snake_case. Class names use PascalCase.

```
✅ Good:
  models/tool_instance.py
  class ToolInstance(Base):
```

### Schemas

**File naming:** snake_case.

```
✅ Good:
  schemas/tool_instance.py
```

## Tests

### Frontend Tests

**File naming:** Same as source file with `.test.tsx` suffix.

```
✅ Good:
  FileBrowser.tsx + FileBrowser.test.tsx
```

### Backend Tests

**File naming:** `test_` prefix + snake_case.

```
✅ Good:
  test_tool_instances.py
```

## Directory Structure Summary

```
apps/web/src/
├── api/              # kebab-case files
├── components/
│   ├── ui/           # PascalCase files
│   ├── layout/       # PascalCase files
│   └── features/     # PascalCase files, grouped by domain
│       ├── git/
│       ├── project/
│       ├── session/
│       └── ...
├── hooks/            # camelCase files
├── pages/            # PascalCase files ending with Page
├── styles/           # kebab-case CSS files
├── types/            # kebab-case files
└── utils/            # kebab-case files

apps/api/src/
├── api/              # snake_case files
├── models/           # snake_case files
├── schemas/          # snake_case files
├── services/         # snake_case files
└── auth/             # snake_case files
```

## Migration Notes

Some legacy files may not yet follow these conventions. When touching a file for other work, rename it to match the convention in the same PR.