Skip to content

Naming conventions – Balyze

Purpose

These naming conventions aim to ensure:

  • immediate understanding of a file’s role without opening it
  • a consistent and maintainable codebase
  • evolution without technical debt from v0 (ALPHA) to BETA and beyond

The guiding principle is simple:

Reading a name should be enough to understand the responsibility of the associated code.

Global conventions

Language

  • English is used everywhere in the codebase
  • French is allowed only in:
  • documentation
  • the README
  • tickets and the Kanban board

Directory structure

  • Strict adherence to Laravel’s directory structure
  • No generic or ambiguous directories (Helpers, Utils, Common, etc.)
  • One directory corresponds to one clear responsibility

Models (Eloquent)

Location

app/Models

Naming rules

  • Singular names
  • PascalCase
  • No suffixes or prefixes

Examples:

Application
Position
Document
User

Eloquent relationships

  • Explicit method names
  • Singular or plural depending on the relationship

Examples:

user()
applications()
documents()

Enums

Location

app/Enums

Naming rules

  • PascalCase
  • Explicit suffix depending on the role

Examples:

ApplicationStatus
DocumentType

Enum values

  • Explicit values
  • No magic values elsewhere in the codebase

Policies

Location

app/Policies

Naming rules

  • One policy per model
  • Policy suffix

Examples:

ApplicationPolicy
PositionPolicy
DocumentPolicy

Responsibility

  • Authorization only
  • No business logic
  • Global rules (super-admin) are centralized via Gate::before()

Domain services

Location

app/Services

Naming rules

  • Verb + DomainName + Service
  • One business action per service

Examples:

CreateApplicationService
UpdateApplicationStatusService
AttachDocumentToApplicationService

Rules

  • No generic classes (Manager, Helper, Utils)
  • Business logic lives exclusively in services

Controllers

Location

app/Http/Controllers

Naming rules

  • Controller suffix
  • One controller per domain resource

Examples:

ApplicationController
PositionController
DocumentController

Responsibility

  • Request validation
  • Calling domain services
  • Returning the HTTP response
  • No business logic

Form Requests

Location

app/Http/Requests

Naming rules

  • Verb + Name + Request

Examples:

StoreApplicationRequest
UpdateApplicationRequest
AttachDocumentRequest

Tests

Location

tests/Feature
tests/Unit

Naming rules

  • Test suffix
  • Aligned with the tested class or behavior

Examples:

ApplicationPolicyTest
CreateApplicationServiceTest

Organization

  • Feature tests: global behavior (auth, policies, routes)
  • Unit tests: isolated business logic (services)

Migrations and database

Tables

  • snake_case
  • plural

Examples:

applications
positions
documents
application_document

Columns

  • snake_case
  • explicit suffixes

Examples:

user_id
created_at
deleted_at
document_type

Permissions (Spatie)

Format

resource.action

Examples

applications.create
applications.view
applications.update
applications.delete

documents.create
documents.view
documents.update
documents.delete

Rules

  • Permissions are coarse-grained
  • Fine-grained restrictions are handled by Policies
  • The admin role is handled globally via Gate::before()

Conclusion

These conventions form the foundation of the Balyze development process.

They apply from v0 (ALPHA) onward and are designed to evolve toward BETA and future versions without structural refactoring.