Naming Convention

Introduction

This page defines the hierarchical taxonomy used to classify all functional behaviors in the Arda platform and the naming scheme used to assign stable, unique identifiers to each element. It is the canonical reference for all use case, user story, and functional scenario identifiers.

Four-Level Taxonomy

The taxonomy has four levels, from broadest to most specific:

Level	Name	Description
1	Domain	Top-level functional area of the platform (e.g., Procurement, Reference Data).
2	Area	A coherent module or capability group within a domain (e.g., Order Queue, Items).
3	Use Case	A distinct user-facing behavior within an area (e.g., Add Card to Order Queue, View Receiving List).
4	Scenario	A specific realization of a use case in the business domain (e.g., Add Card via QR Scan, Add Card via Item List).

Each Domain contains one or more Areas. Each Area contains one or more Use Cases, assigned chronologically within that area. Each Use Case contains one or more Scenarios, assigned chronologically within that use case. Each Scenario is the leaf element and corresponds to a single documentable behavior.

Identifier Format

Full Identifier

${domain}::${area}::${use_case}::${scenario}.${type}

Example: PRO::OQ::0001::0001.US — Procurement, Order Queue, first use case, first scenario, User Story.

Immutable Reference Format

The immutable, stable portion of the identifier excludes the type suffix:

${domain}::${area}::${use_case}::${scenario}

All cross-references, citations, and links must use this prefix form. The type suffix is metadata and may change as understanding of the element evolves. Example citation:

See PRO::OQ::0001::0002 for the QR scan entry point.

Case Sensitivity

Identifiers are case-insensitive. The canonical form uses uppercase for domain and area codes and for type codes. Comparisons, lookups, cross-references, and anchor-slug generation must treat PRO::OQ::0001 and pro::oq::0001 as equivalent. Documents must always render identifiers in the canonical uppercase form.

Element Rules

Element	Format	Scope of Uniqueness	Assignment Rule
`domain`	3—6 uppercase letters (case-insensitive)	Globally unique	Assigned when the domain is created
`area`	3—6 uppercase letters, may contain `-` (case-insensitive)	Unique within its domain	Assigned when the area is created
`use_case`	4-digit zero-padded number (`0001`—`9999`)	Unique within its area	Assigned chronologically within the area
`scenario`	4-digit zero-padded number (`0001`—`9999`)	Unique within its use case	Assigned chronologically within the use case
`type`	Short uppercase code (see Type Codes below, case-insensitive)	N/A — metadata, not part of the identity	Assigned based on the nature of the artifact

Separator Conventions

Separator	Usage
`::`	Between taxonomy levels (domain, area, use case, scenario)
`.`	Before the type suffix
`-`	Allowed within a single level as an intra-level separator (e.g., in area codes)

Type Codes

The type suffix classifies the nature of the documented artifact. The current set is:

Code	Meaning
`US`	User Story — written in the “As a… I want… so that…” form.
`UC`	Use Case — actor-goal behavioral specification with steps, pre/post-conditions, and alternative paths.
`FS`	Functional Scenario — a design rule, data rule, or system behavior constraint.

This set is intentionally open. Additional type codes may be introduced as new artifact types emerge. The type is not part of the immutable identifier and may change without affecting the identity of the element.

Numbering Rules

Numbering starts at 0001 for both use cases and scenarios.
0000 is reserved for potential future use (e.g., metadata or overview records) and must not be assigned to regular elements.
Numbers are never reused. If an element is retired, its number remains permanently consumed and is not reassigned to a different element.

Immutability Rules

Identifiers are immutable. Once assigned, the prefix ${domain}::${area}::${use_case}::${scenario} never changes.
Identifiers are never reused. A retired identifier remains permanently consumed.
Reclassification creates a new identifier. If an element is moved to a different domain or area, it receives a new identifier in the target location. The old identifier is retired with a link to its successor(s).
Type is mutable. The .${type} suffix may change without affecting the identity of the element.

Retirement and Graduation Example

When a story graduates from Unclassified to a proper domain:

UNC::PHY::0001::0001 -- RETIRED
  Successor: PRO::OQ::0005::0003
  Reason: Reclassified to Procurement after physical workflow was given a digital counterpart.

Domain Registry

All twelve domains and their codes:

Code	Name	Description
`FND`	Foundation	Shared utilities and libraries consumed as dependencies across all services.
`OAM`	Operation, Administration, and Maintenance	System management: tenants, users, roles, subscriptions, health. FCAPS model.
`REF`	Reference Data	Authoritative datasets: items, suppliers, organizations, contacts.
`RES`	Resources	Availability, allocation, and consumption tracking: facilities, kanban cards, loops.
`PRO`	Procurement	Commercial acquisition of materials: order queue, purchase orders, receiving.
`FUL`	Fulfillment	Commercial delivery to customers: demand queue, demand orders, shipping.
`OPS`	Operations	Internal manufacturing and business process orchestration.
`SAC`	Shop Access	Physical shop floor and device interfaces: scanners, printers, IoT feeds.
`WFI`	Workflows and Integrations	Cross-domain process coordination and external system connectors.
`APP`	Application	Application-level concerns: dashboard, navigation, layout, general UX.
`GEN`	General Behaviors	Cross-cutting interaction patterns: grid behaviors, error handling, diagnostics.
`UNC`	Unclassified	Stories and use cases not yet assigned to a domain. Graduation retires the UNC identifier and creates a successor in the target domain.

Area Registry

All thirty-four areas across the twelve domains:

FND — Foundation

Code	Area	Description
`CMN`	Common Module	Cross-cutting utilities, data types, and abstractions shared across backend services.

OAM — Operation, Administration, and Maintenance

Code	Area	Description
`FLT`	Fault	Detection, isolation, and correction of system faults.
`CFG`	Configuration	System configuration management across tenants and environments. Includes onboarding workflow, implementation guidance, and user/tenant presentation preferences.
`ACT`	Accounting and Cost	Usage tracking, metering, and cost attribution for tenant operations. Includes subscription and billing.
`PRF`	Performance	Observation and analysis of system performance metrics.
`SEC`	Security	Security policy enforcement, audit logging, and access control infrastructure.
`IAM`	Identity and Access Management	User accounts, tenants, invitations, sessions, and customer acquisition channels.

REF — Reference Data

Code	Area	Description
`ITM`	Items	Catalog of materials, finished goods, and WIP. Classification, supply info, locators, draft support, printing.
`SPL`	Item Supply	Links items to supply sources via `ItemSupply`. Supplier associations, designations, inline creation.
`BA`	Business Affiliates	Legal entities in business transactions. Roles (Vendor, Customer, Carrier, Operator), contacts, addresses.
`ORG`	Organization	Organizational structure and its relationship to business affiliates or department units.
`CON`	Contacts	Contact information as a shared, reusable entity across domains.

RES — Resources

Code	Area	Description
`FAC`	Facilities	Physical site model: Facility, Location, Node, Station, and specialized inbound/outbound node types.
`KC`	Kanban Cards	Full lifecycle of physical and digital Kanban cards. Operational states, print states, events, notes.
`LOOP`	Loop	Kanban route from origin to destination node within a facility.

PRO — Procurement

Code	Area	Description
`E2E`	End-to-End	Cross-cutting procurement lifecycle scenarios spanning multiple areas.
`OQ`	Order Queue	Queue of procurement demand signals (cards in REQUESTING state) awaiting conversion to purchase orders.
`PO`	Orders	Purchase order lifecycle: creation, line management, submission, acceptance, receiving, archiving.
`RCV`	Receiving	Physical inbound material flow: receiving orders, schedules, documents, induction into information system.

FUL — Fulfillment

Code	Area	Description
`DQ`	Demand Queue	External demand not yet entered into tenant business processes.
`DO`	Demand Orders	Demand order lifecycle until fulfillment.
`SHP`	Shipping	Physical outbound material flow: shipping orders, schedules, documents.

OPS — Operations

No areas defined. Content will emerge as specific manufacturing process types are modeled.

SAC — Shop Access

Code	Area	Description
`PDF`	PDF Rendering	PDF generation for labels, kanban cards, breadcrumbs, and other printable artifacts.

WFI — Workflows and Integrations

No areas defined. Content will emerge as cross-domain choreography and external connectors are designed.

APP — Application

Code	Area	Description
`DSH`	Dashboard	Dashboard overview, quick actions, recent activity, onboarding guide.
`NAV`	Navigation	Sidebar navigation, page layout, search, help, notifications.

GEN — General Behaviors

Code	Area	Description
`ENT-DA`	Entity Data Authority	Cross-cutting lifecycle contract for main entities: browse, create, edit, delete, duplicate, import/export, history.
`ENTSUB`	Entity Subordinate	Cross-cutting lifecycle contract for subordinate entities: view, add, edit, remove within parent context.
`MEDIA`	Entity Media	Cross-cutting contract for attaching, replacing, and removing media assets (images, files) on entities. Unified input surface with automatic detection of input method.
`LST`	List Views	Grid selection, inline editing, column management, state persistence.
`ERR`	Error Handling	Error pages, diagnostics, debug panels.
`INT`	Interactions	Cancel/undo flows and other cross-cutting interaction patterns.

UNC — Unclassified

Code	Area	Description
`PHY`	Physical Workflows	Physical-only workflows with no direct digital counterpart (e.g., card placement, bin organization).
`NFR`	Non-Functional	Non-functional requirements and cross-cutting quality attributes (e.g., instant persistence, optimistic UI).
`TBD`	To Be Determined	Catch-all for stories awaiting initial triage.

Classification Status Values

Each use case or scenario may carry a status value indicating the relationship between the documented behavior and the current implementation:

Status	Meaning
`Covered`	The behavior is fully documented and implemented.
`Partial`	The behavior is documented; implementation covers some but not all scenarios.
`New-extends`	A new behavior that extends an existing implemented capability.
`New-distinct`	A new behavior with no current implementation counterpart.

Identifier Format Examples

Full Identifier Examples

Identifier	Reading
`PRO::OQ::0001::0001.US`	Procurement, Order Queue, first use case, first scenario, User Story
`PRO::OQ::0001::0002.UC`	Procurement, Order Queue, first use case, second scenario, Use Case
`PRO::PO::0003::0001.FS`	Procurement, Orders, third use case, first scenario, Functional Scenario
`REF::ITM::0002::0001.US`	Reference Data, Items, second use case, first scenario, User Story
`OAM::IAM::0001::0003.UC`	OAM, Identity and Access Management, first use case, third scenario, Use Case
`UNC::TBD::0001::0001.US`	Unclassified, To Be Determined, first use case, first scenario, User Story

Future Variant Extension

A numeric variant suffix may be introduced in the future between the scenario number and the type code:

${domain}::${area}::${use_case}::${scenario}-V${variant}.${type}

Variants represent different system implementations of the same business scenario, such as different interaction channels (web, mobile, voice) or successive system improvements. A missing variant is equivalent to V0. This extension is reserved but not yet active.