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.