Skip to content

ADR-013 — Reference Architecture as Vertical Composition

Status

Accepted

Context

UC-BoK models retail knowledge at the horizontal level (capabilities, processes, objects — valid across all verticals). However, different retail verticals (fashion, grocery, specialty) require different capability priorities, process priorities, and application topologies. A mechanism is needed to express these vertical-specific configurations without duplicating the horizontal model.

Decision

A UC-BoK Reference Architecture (RA) is a vertical composition of the horizontal model: it declares which capabilities are critical, important, or standard for a given retail vertical, and which processes are priority. RAs are defined in catalogs/reference-architectures/.

Rules:

  1. An RA does not define new capabilities or processes — it prioritises existing ones.
  2. An RA uses three capability priority tiers: critical (MVP ≥ 3), important (MVP ≥ 2), standard (MVP ≥ 1).
  3. An RA is bound to a retail vertical. Three canonical verticals are defined: Fashion Retail (RA-001), Grocery Retail (RA-002), Specialty Retail (RA-003).
  4. An RA can be used as the baseline for a UCMI Assessment (ADR-014): capability gaps are measured against the RA's priority thresholds.
  5. New verticals require a new RA and an editorial board decision — they are not created ad hoc.

Consequences

  • catalogs/reference-architectures/*.yaml are the RA source files.
  • The Knowledge Graph requires_critical/important/standard edges connect RAs to Capabilities.
  • The UCMI Assessment Engine uses RA baselines for gap analysis.
  • The Vertical Comparison page (docs/10-reference-architecture/1042-vertical-comparison.md) is generated from RA data.