headquarter/docs/development/naming.md

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.

// 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.