URL Naming

Public URLs in Arda’s Platform encode both the capability type and the deployment location (Infrastructure + Purpose). This document defines the URL structure, naming rules, and versioning conventions.

URL Structure

https://<Purpose>.<Infrastructure>.<capability>.arda.cards/<major-version>/<endpoint-name>/<specific-route>

Segment	Description
`<Purpose>`	The Purpose (Partition) hosting this instance: `dev`, `stage`, `demo`, `prod`, `live`
`<Infrastructure>`	The Infrastructure name (e.g., `alpha002`, `prod-amm-001`)
`<capability>`	Type of capability: `app`, `io`, `api`, or `auth`
`<major-version>`	SemVer major version of the API Endpoint (not the module or component version)
`<endpoint-name>`	Lowercase kebab-case endpoint name (e.g., `items`, `purchase-orders`, `pdf-render`)
`<specific-route>`	OpenAPI route path relative to the endpoint

Examples

https://dev.alpha002.api.arda.cards/v1/items/
https://prod.prod-amm-001.io.arda.cards/v1/purchase-orders/{id}
https://live.app.arda.cards/  (canonical production app)
https://live.auth.arda.cards/oauth2/token

Capability Classifiers

Capability	Domain	Use Case
`app`	`app.arda.cards`	End-user browser applications
`api`	`api.arda.cards`	REST APIs (future primary domain)
`io`	`io.arda.cards`	REST APIs (current primary; migration from `io` to `api` pending)
`auth`	`auth.arda.cards`	OAuth2 authorization and token endpoints

Infrastructure Naming Rules

Infrastructure names have three dot-separated parts: <kind>.<qualifier>.<revision>

Kind

Kind	Description
`Prod`	High-availability, customer-facing production infrastructure
`NonProd`	Development and production-like testing
`Sandbox`	Transient, one-off environments for experimentation; owned by an individual or small team

Qualifier

Short name identifying the product, project, or owner:

amm — Arda Money Making product (Arda Cloud); applies to NonProd and Prod
oam — OAM product
kyle — personal sandbox (individual owner)
infra — infrastructure testing

Revision

Three-digit number (001, 002, …) distinguishing sequential environments of the same kind+qualifier when major infrastructure changes require a new environment.

Full example: NonProd.amm.001, Prod.amm.002, Sandbox.kyle.001

Legacy Names

Current environments use legacy names (created before this convention was established):

Sandbox0001 → would be Prod.amm.001
Alpha001 → would be Prod.amm.002
Alpha002 → would be NonProd.amm.001

Purpose Naming Rules

Standard purposes and their usage:

Purpose	Description
`dev`	Active feature development
`stage`	Pre-production testing and validation
`demo`	Showcase to prospective customers
`prod`	Live, customer-facing operations
`live`	Canonical alias for `prod` (used in stable canonical names)

Infrastructure/Purpose Hierarchy

Platform
  Sandbox.<qualifier>.###
    (ad-hoc purposes)
  NonProd.<qualifier>.###
    dev
    stage
    (others as needed)
  Prod.<qualifier>.###
    demo
    prod

API Endpoint Naming Rules

Endpoint names must:

Be lowercase kebab-case: ^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$
Use plural form for resource collections: items, purchase-orders, business-affiliates
Use mnemonic names for special-purpose endpoints: pdf-render, qr-lookup

API Endpoint versions are managed independently from module versions and component versions. The URL uses only the major version of the API Endpoint.

Canonical Reference-Data Route Shape

The going-forward standard for in-process Kotlin/Ktor routing of reference-data endpoints is a path of five explicit, all-singular segments:

{version}/{domain}/{module}/{service}/{endpoint}

For reference-data endpoints, {domain} is reference-data. Worked examples:

Resource	Path
Item	`/v1/reference-data/item/item/item/{id}/…`
ItemSupply (own endpoint)	`/v1/reference-data/item/item-supply/supply/{item-eId}/…`
BusinessAffiliate	`/v1/reference-data/business-affiliate/business-affiliate/business-affiliate/{id}/…`

Conventions:

Segments stay explicit even when the literals repeat. The item/item/item and business-affiliate/business-affiliate/business-affiliate repetition is intentional — {module}, {service}, and {endpoint} are each spelled out regardless of whether they coincide. ItemSupply is exposed on its own item-supply/supply endpoint rather than nested under the item endpoint.
Scope: Kotlin/Ktor routing layer only, for now. This shape is introduced at the application routing layer. It involves no Helm chart route/ingress changes and no CloudFormation/CDK changes. Rolling the canonical routes out to the ingress / Helm / Cfn layer (and the legacy-alias deprecation timeline) is tracked as PDEV-863.
Legacy routes remain active as aliases during migration. The pre-existing /v1/<resource>/... routes continue to resolve to the same handlers while callers migrate (DQ-009).

Relationship to the host/endpoint scheme

This is a forward standard for the path structure after the version, not a replacement of the host scheme defined above. The host-plus-version portion — <Purpose>.<Infrastructure>.<capability>.arda.cards/<major-version> — is unchanged. The five-segment shape defines what follows the major version: {domain}/{module}/{service}/{endpoint} in place of the single <endpoint-name> segment for reference-data endpoints.