ADR-008: GitHub Repository Naming Patterns

Status: Accepted
Date: 2025-09-11
Authors: Development Team
Reviewers: Architecture Team

The Entirius project adopts standardized GitHub repository naming patterns using the format <type>-<specifier>-<name> to ensure consistent organization, easy identification, and clear categorization of repositories across the ecosystem.

Naming Rules:

• Use lowercase and kebab-case (separate words with hyphens -)
• Keep names descriptive but concise
• Include platform/language specifier when relevant
• Always prefix with entirius-

This list explains the role of each component type within the Entirius ecosystem to help developers understand their purpose and correctly apply the naming conventions.

• Frontend Services (PWA) Client-side applications built with a Progressive Web App architecture, based on Node.js/React. They are responsible for the entire user interface, user interaction, and communication with backend services.

• Backend Services (API) The main server-side services that implement business logic and expose an API. They include both monolithic applications based on Django (Python) and specialized microservices (e.g., for AI).

• External Services Instances or forks of external software (e.g., Magento, Redmine) that have been integrated into the Entirius ecosystem. These are standalone applications customized to our needs.

• Modules Packages of code designed to extend the functionality of existing services or platforms (e.g., Django, Magento). These are reusable components that do not run on their own and must be installed within a larger application.

• Libraries Collections of reusable functions, classes, or tools specific to a programming language. These libraries are imported into various projects to speed up development and avoid code duplication.

• Documentation Repositories containing only technical, project, or user documentation. They can be generated using tools like Hugo or Sphinx, or simply consist of a collection of Markdown files.

• Scripts Collections of automated scripts for operational and administrative tasks. They are used for server provisioning (KVM), deployment automation, or CI/CD tasks.

• Tools Independent utility applications that support development, testing, or analytical processes. Examples include custom log analyzers, data importers, or debugging tools that do not fit into any other category.

As the Entirius ecosystem grows with multiple services, modules, libraries, and tools, there is a need for a consistent repository naming convention that:

• Provides clear identification of repository purpose and type
• Enables easy filtering and searching within GitHub
• Maintains consistency across all project components
• Supports the modular monolith architecture pattern
• Facilitates automated tooling and CI/CD processes
• Helps new contributors understand the project structure quickly

Without standardized naming patterns, repositories become difficult to organize, search, and manage at scale.

• Description: Use simple descriptive names like customer-dashboard, ai-gateway
• Pros:
  • Shorter names
  • Less typing required
• Cons:
  • No clear ownership or project association
  • Difficult to filter Entirius repositories
  • Name conflicts with other projects
  • No type categorization
• Impact on system: Minimal structure, harder to manage at scale

• Description: Use patterns like service-ai-gateway, module-django-auth
• Pros:
  • Clear type identification
  • Good categorization
• Cons:
  • No project branding
  • Potential conflicts with other organizations
  • Missing technology/platform context
• Impact on system: Better organization but lacks project identity

• Description: Use entirius-<type>-<specifier>-<name> pattern with clear categorization
• Pros:
  • Clear project branding and ownership
  • Type-based organization
  • Technology/platform identification
  • Consistent structure across all repositories
  • Easy filtering and searching
  • Supports automated tooling
• Cons:
  • Longer repository names
  • Requires adherence to naming conventions
• Impact on system: Excellent organization, clear structure, supports growth

Chosen option: Structured naming with project prefix and type categorization

Key decision factors:

• Brand consistency: All repositories clearly belong to the Entirius project
• Type clarity: Immediate identification of repository purpose (service, module, tool, etc.)
• Platform identification: Technology stack is clear from the name
• Scalability: Pattern supports growth to hundreds of repositories
• Developer experience: Easy to find and understand repository purpose
• Automation support: Consistent patterns enable better CI/CD and tooling
• GitHub organization: Repositories are naturally grouped and searchable
• Compatibility with existing architecture: Aligns with modular monolith approach

• ADR-001: Modular Monolith Architecture - Naming supports architectural boundaries
• ADR-005: GitHub as Code Repository - Naming convention for GitHub platform

• GitHub Repository Naming Best Practices
• Semantic Naming Conventions