Naming Conventions

Naming Conventions¶

Identifier forms¶

This documents defines:

lower-kebab-case as a sequence of words in lower case joined with a dash -
lowerCamelCase as a sequence of capitalized words joined without any separator,
with the first letter of the first word in lower case.
lower_snake_case as a sequence of names in lower case joined with an underscore _

Primary Naming Conventions¶

Canonical identifier¶

The primary naming conventions defines conventions that engineer have to follow while designing
and writing software; those are the names that engineers actively creates.

Given a Component C and its constituting Modules M1, M2, M3, …

The canonical form of their name is lower-case-kebab
The canonical name does not have any trailing suffix -component, -module, -data-authority, …
The name aims to be short, one or two nouns.

Example:

qr-lookup: Yes
qrLookup: No, it is not lower-kebab-case
item-data-authority: No, no generic trailing suffix.

Repository¶

There is a repository, having the canonical name of the Component

The repository contains all the source code of the Component; an exception can be made for its documentation.
The repository does not contain any other Components.

In the case of a kotlin Component, the repository contains one gradle project having the canonical Component name.

Kotlin¶

Note

Multi-project gradle conventions will be defined later

All kotlin classes and objects are grouped in package by the Module they belong to, and all the Module packages are
«under» a package for the Component.

The simple name of the packages is the lowerCamelCase form of the Component, resp. Module canonical name.

The qualified name of a Module packages

starts with cards.arda,
immediately followed by the lowerCamelCase Component name,
eventually followed by the lowerCamelCase Module name.

Example:

cards.arda.pdfRender.PdfRenderModule: No, class is in the Component, but not in the Module
cards.arda.pdfRender.shopAccess.PdfRenderModule: Yes, class is in the Module shopAccess
which is itself directly in the Component pdfRender
cards.arda.pdfRender.shopaccess.PdfRenderModule: No, Module name is not lowerCamelCase
cards.arda.pdfrender.shopAccess.PdfRenderModule: No, Component name is not lowerCamelCase
cards.arda.accounts.system.tenant.TenantModule: Yes, class is in the Module tenant which is
itself indirectly in the Component accounts

API: Ingress¶

The Ingress is directly exposed by the Service only to other Services in the kubernetes cluster.

The ingress path is the combination of the Module api version, a ‘/’ and the lower-kebab-case form of Module name.

API: Route¶

The Route is exposed by the API Gateway to other systems.
It is the published API of the Component and must only evolve intentionally.

It is recommended, but not mandatory, for the Route to be the ingress path.
During transitions, it is possible to have multiple routes map to the same ingress.

Database¶

The database has the lower_snake_case of the Module name.

Secondary Naming Conventions¶

Those names will be derived from primary names by an appropriate combination of the Component and Module names
and will adhere to the naming conventions of the ecosystems in which they are beng used.

Docker¶

The docker image name is the combination of the Component name, a ‘/’, and the Module name.

Helm¶

The main Chart name is the Component name.

The release name is the Component name.

Kubernetes¶

Every object has its .metadata.namespace set to the combination of the purpose, a - and the Component name.

As a default, objects have .metadata.name set to the Component name.
Should there be multiple objects of the same kind, secondary objects have appropriate names,
conventions to be established.

Example:
Namespaces have at least two secrets, one to configure the deployment, named after the Component,
while the other provides credentials required to download the docker images; this secondary has the name ghcr-secret.

Should the Component deploy multiple Modules, and should these Modules meed different secrets, they would be named after
their Module.

Naming Conventions