Skip to content

Nomenclature Conventions

1. Introduction

This document defines the official nomenclature and naming conventions for all projects governed by this reference architecture.

It establishes a shared and mandatory baseline for naming:

  • Services and components
  • Cloud resources (IaaS, PaaS, SaaS)
  • Repositories and folders
  • Frameworks and runtimes
  • Infrastructure and operational artifacts

These conventions aim to ensure:

  • Consistency across teams and repositories
  • Clarity and traceability
  • Technical and organizational scalability
  • Alignment with Azure governance and the Azure Well-Architected Framework

All teams MUST follow these conventions unless an explicit exception is approved by Architecture.

Note: These conventions apply to microservices located in the same repository or in different repositories, regardless of shared library dependencies.

2. Governance & Mandatory Rules

2.1 Technology Lifecycle

  • Every component MUST declare its Technology Lifecycle in: docs-private/lifecycle/technology-lifecycle.md
  • New developments MUST NOT use technologies that are End-of-Life (EOL) or Near EOL.

2.2 Version Control Governance

  • All repositories MUST follow the Git strategy defined in: docs/governance/version-control/
  • Direct commits to protected branches (main / master) are forbidden.
  • Pull Requests are mandatory and must pass quality, security, and QA gates.

3. Environment Naming Conventions

Standard environment identifiers MUST be used consistently across code, pipelines, and infrastructure.

  • Development: dev
  • Quality Assurance: qa
  • Staging / Pre-Production: stg
  • Production: prod

Examples: - app-api-orders-dev - app-api-orders-prod - func-payments-qa

4. Folder and Service Naming Prefixes

The following prefixes define standard naming conventions for folders and services. They allow immediate identification of the component responsibility.

Prefix: Api
Type: Web API
Example: ApiOrderManagement
Description: RESTful backend service

Prefix: App
Type: Web Application
Example: AppCustomerPortal
Description: User-facing web application

Prefix: Azf
Type: Azure Function
Example: AzfDataProcessor
Description: Event-driven cloud functions

Prefix: Mcs
Type: Microservice
Example: McsUserProfile
Description: Independent domain service

Prefix: Wrk
Type: Worker
Example: WrkEmailDispatcher
Description: Background or async processor

Prefix: Ops
Type: Operations
Example: OpsDeployment
Description: CI/CD, Docker, scripts, tooling

Prefix: Dat
Type: Data
Example: DatCustomerDB
Description: Databases and data layers

Prefix: Sup
Type: Support / Infra
Example: SupStorageTools
Description: Infrastructure support utilities

Prefix: Doc
Type: Documentation
Example: Docs
Description: Project and architecture documentation

5. Cloud Component Nomenclature

5.1 Infrastructure Models

  • IaaS: Virtual Machines, custom networking
  • PaaS: App Service, Azure Functions, managed databases
  • SaaS: Azure DevOps, Entra ID, external platforms

5.2 Azure Resource Naming

Standard format:

--

Examples: - app-api-orders-prod - func-payments-dev - vm-batch-worker-qa

6. Framework & Runtime Naming

Frameworks and runtimes MUST be explicitly declared and versioned.

Examples: - python-3.11-fastapi - dotnet-8-webapi - dotnet-8-ocelot - node-20-angular

Rules: - LTS versions are mandatory for new developments - Runtime versions MUST align with the Technology Lifecycle Declaration

7. Repository & Documentation Structure

Mandatory files at repository root:

  • README.md (public entry point)
  • README-private.md (internal entry point)
  • CHANGELOG.md (version history)
  • .env.sample (environment variable template)

Documentation folders:

  • docs/ (public and reference documentation)
  • docs-private/ (internal and restricted documentation)

8. Configuration & Environment Variables

  • .env.sample MUST exist and be versioned
  • .env MUST NOT be committed
  • Secrets MUST NOT be hardcoded
  • Sensitive values MUST be stored in secure vaults

9. Operational Artifacts

Operational scripts and tooling MUST:

  • Live under the Ops/ folder
  • Be environment-agnostic when possible
  • Follow naming conventions

Example structure:

Ops/ - docker-compose.yml - backup.sh - restore.sh

10. Enforcement

  • These conventions are mandatory
  • Non-compliance may block:
  • Pull Requests
  • Releases
  • Deployments
  • Exceptions require explicit approval from Architecture

11. References

  • Azure Well-Architected Framework
  • Azure Naming and Tagging Best Practices
  • Internal Security and Compliance Policies