Developer
3f5159fb8a
- Add docs/development/naming.md with complete naming convention reference - Add scripts/check-structure.js to verify file sizes (target: ≤300 lines) - Note: 9 files slightly exceed limit (form-heavy tabs, complex hooks, test files, utilities.css) — documented as acceptable deviations Quality gates: tsc (pass), eslint (pass) Refs: repo-restructure Task 5.2
173 lines
3.1 KiB
Markdown
173 lines
3.1 KiB
Markdown
# 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.
|