Naming Conventions

This document defines the formal naming conventions for all system artifacts in Arda’s platform.

Identifier Forms

Three standard identifier forms are used throughout the system:

• lower-kebab-case: a sequence of words in lower case joined with a dash - (e.g., item-data-authority)
• lowerCamelCase: a sequence of capitalized words joined without a separator, with the first word’s first letter in lower case (e.g., itemDataAuthority)
• lower_snake_case: a sequence of names in lower case joined with an underscore _ (e.g., item_data_authority)

Primary Naming Conventions

These conventions are actively created by engineers during design and implementation.

Canonical Identifier

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

1. The canonical form is lower-kebab-case
2. The canonical name does not have generic trailing suffixes like -component, -module, or -data-authority
3. The name aims to be short — one or two nouns

Examples:

• qr-lookup — correct
• qrLookup — incorrect (not lower-kebab-case)
• item-data-authority — incorrect (has generic trailing suffix)

Repository

Each Component has exactly one repository with the canonical component name:

1. The repository contains all source code of the Component (documentation may be separate)
2. The repository does not contain other Components
3. In a Kotlin Component, the repository contains one Gradle project with the canonical component name

Kotlin Packages

All Kotlin classes are grouped into packages by the Module they belong to. All Module packages are “under” a package for the Component.

Package naming rules:

1. Starts with cards.arda
2. Immediately followed by the lowerCamelCase Component name
3. Optionally followed by the lowerCamelCase Module name

Examples:

• cards.arda.pdfRender.shopAccess.PdfRenderModule — correct (class in Module shopAccess within Component pdfRender)
• cards.arda.accounts.system.tenant.TenantModule — correct (Module tenant under Component accounts)
• cards.arda.pdfRender.PdfRenderModule — incorrect (class is in Component, not in a Module)
• cards.arda.pdfRender.shopaccess.PdfRenderModule — incorrect (Module name not lowerCamelCase)

API: Ingress

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

The ingress path is the combination of:

• The Module API version
• A /
• The lower-kebab-case form of the 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 equal the Ingress path. During transitions, multiple Routes may map to the same Ingress.

See also API Design: URL Naming for the full hostname and path convention.

Database

The database name is the lower_snake_case form of the Module name.

Secondary Naming Conventions

These names are derived from primary names by combining Component and Module names according to ecosystem conventions.

Docker

The Docker image name is: <component-name>/<module-name>

Helm

• The main Chart name is the Component name
• The release name is the Component name

Kubernetes

Every object has .metadata.namespace set to: <purpose>-<component-name>

As a default, .metadata.name is set to the Component name. Secondary objects of the same kind have appropriate names (conventions to be established).

Example: A namespace has at least two Secrets — one named after the Component (deployment configuration), and one named ghcr-secret (Docker image pull credentials). If a Component deploys multiple Modules requiring different secrets, they are named after their Module.