fetch_ml/docs/src/file-naming-conventions.md

File Naming Conventions

This document defines the naming conventions for the FetchML codebase to maintain consistency and clarity.

Package Structure

fetch_ml/
├── cmd/                    # Entry points (wiring only)
│   ├── api-server/        # API server entry point
│   ├── worker/            # Worker entry point
│   ├── tui/               # Terminal UI entry point
│   └── ...
├── internal/              # Internal packages (business logic)
│   ├── domain/            # Core domain types (zero internal deps)
│   ├── api/               # HTTP/WebSocket handlers
│   ├── worker/            # Worker business logic
│   ├── queue/             # Queue implementations
│   ├── storage/           # Storage abstractions
│   ├── network/           # Network utilities
│   └── ...
└── tests/                 # Test suites
    ├── unit/
    ├── integration/
    └── e2e/

Naming Rules

1. General File Naming

• Use snake_case for file names: job_runner.go, task_queue.go
• Match file name to primary content: The file name should reflect the main type or function defined within
• One concern per file: Each file should have a single, clear purpose

2. Package-Level Files

Pattern	Purpose	Example
doc.go	Package documentation	internal/domain/doc.go
types.go	Shared type definitions	internal/api/types.go
errors.go	Error definitions	internal/queue/errors.go
const.go	Constants	internal/config/const.go

3. Handler/Service Files

Pattern	Purpose	Example
<noun>.go	Main type definition	worker.go, server.go
<noun>_test.go	Unit tests	worker_test.go
<verb>_<noun>.go	Action-focused	run_job.go, cancel_task.go
<noun>_<action>.go	Noun-focused action	job_runner.go, task_scheduler.go

4. Internal Package Organization

internal/worker/
├── worker.go           # Main Worker type (always present)
├── config.go           # Configuration parsing
├── factory.go          # Constructor functions (NewWorker)
├── lifecycle.go        # Start/Stop/Shutdown
├── runloop.go          # Main processing loop
├── metrics.go          # Metrics setup
├── gpu.go              # GPU utilities
└── execution/          # Sub-package for execution logic
    ├── runner.go       # JobRunner type
    ├── setup.go        # Job directory setup
    └── container.go    # Container helpers

5. TUI Model Package (Post-Phase 7)

cmd/tui/internal/model/
├── state.go        # State struct, InitialState()
├── jobs.go         # Job type, JobStatus
├── messages.go     # tea.Msg types
├── styles.go       # Lipgloss styles
├── keys.go         # KeyMap, DefaultKeys()
└── doc.go          # Package docs

6. API Package (Post-Phase 5)

internal/api/
├── server.go           # Server type
├── factory.go          # NewServer()
├── routes.go           # Route registration
├── middleware.go       # Auth, logging middleware
├── errors.go           # API error responses
├── health.go           # Health check handlers
├── jobs/               # Job handlers sub-package
│   ├── handlers.go
│   ├── manifest.go
│   └── paths.go
├── jupyter/            # Jupyter handlers
│   └── handlers.go
├── validate/           # Validation handlers
│   └── handlers.go
└── ws/                 # WebSocket infrastructure
    ├── handler.go
    └── protocol.go

Anti-Patterns to Avoid

❌ Don't: utils.go, helpers.go, misc.go - too vague
✅ Do: path_utils.go, response_helpers.go, string_utils.go - specific purpose

❌ Don't: handler_v2.go, new_worker.go - version numbers in names
✅ Do: Update the existing file or create purpose-specific files

❌ Don't: worker/interface.go - stutter (package name in file name)
✅ Do: worker/interfaces.go or just define in worker.go

❌ Don't: 1000+ line files
✅ Do: Split into focused files (<400 lines each)

Layer Enforcement

The scripts/ci-checks.sh script enforces these architectural rules:

1. No internal/ → cmd/ imports: Business logic cannot depend on entry points
2. domain/ has zero internal imports: Core types only use stdlib
3. File size limits: Warning if files exceed 400 lines
4. No circular imports: Verified via go list

Run checks with:

make ci-checks

Success Metrics

• All files <400 lines (warning at 400, error at 600)
• File name matches primary content
• Package imports follow layer direction (cmd → internal → domain)
• CI checks pass: make ci-checks