DTO Reference¶

A DTO (Data Transfer Object) is a versioned protobuf message that represents one piece of persistent system state — for example, a store record, an ESL assignment, a rendered image, or a set of rendering parameters. DTOs are the primary currency of the Pricer EVO platform.

Each DTO type has:

A single owning service that is the sole writer of that DTO type.
A defined ID pattern that encodes scope (tenant, store, and/or a local key) and is enforced by DTOflow.
Zero or more aliases — secondary key patterns used to look up the same DTO record by a different key (e.g., by item ID, by ESL barcode).
Zero or more subscribing services that receive change notifications via the Change Queue Service (CQS) and react to those changes.

When a DTO is written, the platform automatically notifies every subscriber. Services never call each other directly; all coordination flows through DTOs.

For a description of how DTOflow, CQS, and LFS work together, see platform/overview.md.

How to read these docs¶

Each DTO has (or will have) its own reference page. The pages share a standard structure:

Section	Content
Role	One-paragraph description of what this DTO represents and why it exists
Owning service	The service that writes it, with a link to the service page
Scope & ID	ID pattern, example ID, and the logic behind the scope level
Minor version	Current minor version, and what changed since v0
Schema summary	Table of top-level fields with types and short descriptions
Aliases	Named secondary lookup patterns (alias name, pattern, and expression)
Consumers	Services that subscribe to this DTO type and what they do with it
Related DTOs	DTOs that are logically adjacent (inputs, outputs, or dependencies)

DTO Catalog¶

Core & ESL¶

These DTOs form the foundation of the ESL registry: they track which ESLs exist, where they are assigned, and what operational state they are in.

DTO	Version	Scope	Owning service	Role	Page
store	v1 minor 1	per-tenant + store	link-registry	Store identity record: external ID and reference-store flag	store
storeesl	v1 minor 0	per-tenant + store	link-registry	Maps an ESL barcode to a store; carries ESL type and link department	storeesl
storeeslstatus	v1 minor 0	per-tenant + store	pricer-server	ESL device lifecycle state: ONBOARDING → OK → ROAMING → OFFBOARDED / LOST; includes battery, device properties, IR diagnostics	storeeslstatus
esltype	v1	global	studio-design-library	ESL device-type specification: display dimensions, supported features	esltype
esldriver	v1	global	(ECC infrastructure)	ESL driver / firmware configuration	esldriver

Design¶

Design DTOs describe the visual templates used to render labels, along with the fonts, palettes, and canvas types that support them.

DTO	Version	Scope	Owning service	Role	Page
design	v1	per-tenant	studio-design-library	Published, immutable design: display dimensions, color space, JSON definition and preview image stored in LFS	design
canvasdesign	v1	per-tenant	studio-design-library	Canvas-based design variant for multi-ESL floating canvases	canvasdesign
canvastype	v1	global	studio-design-library	Canvas display-type specification (size, layout constraints)	canvastype
designimage	v1	per-tenant	studio-design-library	Design preview image asset; binary stored in LFS, DTO carries the file path	designimage
font	v1	per-tenant	studio-design-library	Font definition; binary font file stored in LFS	font
eccfont	v1	global	ecc-image-render-service	ECC-specific font used by the ECC rendering pipeline	eccfont
palette	v1	per-tenant	studio-design-library	Named color palette referenced by designs	palette

Link¶

Link DTOs represent the binding between an item (or items) and one or more ESLs. They are the central DTO in the rendering pipeline — everything downstream of a link change is triggered by a change to one of these DTOs.

DTO	Version	Scope	Owning service	Role	Page
link	v2	per-tenant + store	link-registry	Links an item (or items) to an ESL; top-level `system` discriminator selects ECC (Single, MultiItem) or Studio (Single, FloatingCanvas) rendering path; aliases `by_storeesl`, `by_item`	link
studiolink	v1	per-tenant + store	studio-link-evaluator	Evaluated link for the Studio renderer: result of applying communicationpack scenarios and CEL conditions against item data; consumed by studio-renderer	studiolink
ecclink	v1	per-tenant + store	ecclink-projector	ECC-specific link projected from link.v2; consumed by ecc-image-render-service	ecclink

Image¶

Image DTOs carry rendered label images through the pipeline. The current production path produces a studioeslimage and an ecceslimage in parallel; the eslimage-merger combines them into the final eslimage that is pushed to hardware.

DTO	Version	Scope	Owning service	Role	Page
eslimage	v1	per-tenant + store	eslimage-merger	Final merged ESL image sent to hardware; merges studioeslimage + ecceslimage into a single deliverable	eslimage
studioeslimage	v1	per-tenant + store	studio-renderer	Studio-rendered ESL image; binary PNG stored in LFS	studioeslimage
ecceslimage	v1	per-tenant + store	ecc-image-render-service	ECC-rendered ESL image; produced from ecclink	ecceslimage
eccimage	v1	per-tenant + store	ecc-image-render-service	ECC image not tied to a specific ESL assignment	eccimage

ECC¶

ECC DTOs configure and describe the ECC (Pricer's proprietary display rendering engine) pipeline.

DTO	Version	Scope	Owning service	Role	Page
eccmodel	v1	global	ecc-image-render-service	ECC device model definition: layout slots, field mappings, rendering rules	eccmodel
eccparameters	v1 minor 1	per-tenant + store (singleton)	ecc-image-render-service	Global rendering parameters for ECC per store: key-value map (`#KEY#` substitution in scripts) and IPF entries (presentation format list, one default)	eccparameters

Item¶

Item DTOs carry product data and its configuration into the rendering pipeline.

DTO	Version	Scope	Owning service	Role	Page
itemproperties	v1 minor 0	per-tenant + store (singleton)	item-registry	Property schema for the store: catalog of all system-defined and custom properties, plus the dynamically generated protobuf `FileDescriptorProto` for the store's `StoreItem` message	itemproperties
storeitemvalues	v1	per-tenant + store	item-registry	Flattened key-value item data for a single item in a single store; alias `by_sic` enables lookup by SIC (Store Item Code)	storeitemvalues
itemprocessingparameters	v1	per-tenant + store (singleton)	item-registry	Item Registry behavior configuration: `unknown_item_behavior`, `sic_append`, `sic_allow_moving_sic`, `reject_update_on_unlinked`	itemprocessingparameters

Task / Workflow¶

These DTOs describe higher-level business logic: how items map to designs, and what flash/command sequences should run on ESLs.

DTO	Version	Scope	Owning service	Role	Page
communicationpack	v1	per-tenant	studio-scenario-library	Scenario container: a set of conditions and rules that map item data to Studio designs; evaluated by studio-link-evaluator to produce studiolink	communicationpack
taskdefinition	v1	per-tenant	actions-library	ESL task definition: flash commands with color, pattern, and duration; uses shared Conditions and Rule types	taskdefinition

Deprecated DTOs¶

These DTOs have been superseded. Their individual pages are kept for reference when encountering them in older code or data, but new services must not write or subscribe to them.

DTO	Replaced by	Status
`designerlink.v1`	studiolink.v1	Phase 2 complete — `studio-link-evaluator` now writes `studiolink` directly. No new designerlink records are written.
`renderedimage.v1`	eslimage.v1	Superseded by PLT-2487 image split. Bridge removal pending full pricer-server cutover to native `eslimage` consumption.
`link.v1`	link.v2	Read-only; no new records written. All new links are v2. Full migration tracked in ADR-003.

Scope reference¶

Every DTO has a scope that determines the structure of its ID. The four scope levels used in this system are:

Scope	Meaning	Example ID	Notes
global	One record exists across the entire platform; no tenant or store qualifier	`esltypes/Minew-154R2`	Used for device-type specs, ECC models, and platform-wide configuration that does not vary per customer
per-tenant	One record per tenant (customer); no store qualifier	`t/10001/designs/d-7f3a`	Used for designs, fonts, palettes, and communication packs that are authored at the tenant level and shared across all stores
per-tenant + store	One record per (tenant, store, local key) triple	`t/10001/s/S001/links/lnk-99b2`	The most common scope; used for links, images, item values, and ESL assignments where data differs per store
per-tenant + store (singleton)	Exactly one record per (tenant, store) pair; no further local key	`t/10001/s/S001/itemproperties`	Used for store-wide configuration blocks such as `itemproperties`, `eccparameters`, and `itemprocessingparameters`; the store ID is the full key

Scope and ID-pattern convention¶

IDs follow a resource-path convention with fixed segment names:

t/{tenantid}                          tenant root
t/{tenantid}/s/{storeid}              store root
t/{tenantid}/s/{storeid}/{type}/{id}  per-store record  (most DTOs)
t/{tenantid}/s/{storeid}/{type}       singleton         (itemproperties, eccparameters, …)
{type}/{id}                           global record     (esltypes, eccmodels, …)

The segment names between slashes (e.g., links, esls, designs) are the canonical plural names of the DTO types. They are fixed in the proto __idpattern__ annotation and must not be changed after the DTO type ships, because stored IDs are permanent.