E2E Flows¶

This section documents how the DTOflow platform and functional services cooperate end-to-end to get the correct rendered image onto every Electronic Shelf Label (ESL) in a store. Each flow describes one coherent slice of the pipeline: who triggers it, which services participate, which DTOs are produced and consumed, and how the system behaves at the boundaries between services.

The underlying transport for all inter-service communication is the DTOflow platform, which consists of:

dtoflow-spanner — primary DTO storage
dtoflow-changequeue (CQS) — change-event fan-out that drives reactive services
dtoflow-lfs — large-file storage for rendered PNG images

Services are reactive and stateless: each subscribes to CQS notifications for the DTOs it cares about, fetches the latest state, computes its output, and writes a new DTO. No service holds authoritative in-memory state beyond its own output DTOs.

Flows¶

Flow	Trigger	Key services	Summary
Design Publication	Designer publishes a design in Studio UI	studio-design-library, studio-renderer, studio-link-evaluator	A label design moves from draft to published and becomes immutable. All ESLs using that design are queued for re-render.
Item–ESL Linking	Store worker scans ESL barcode and links it to an item	link-registry, studio-link-evaluator, studio-renderer, eslimage-merger, pricer-server	A physical ESL is associated with a retail item for the first time (or re-linked). The full render and transmission pipeline runs end-to-end.
Item Update	ERP/PIM pushes updated item data to item-registry-api	item-registry, studio-link-evaluator, studio-renderer, eslimage-merger, pricer-server	Item attributes change (price, name, promotional flag, etc.). If the change affects the winning design evaluation result the ESL image is re-rendered and re-transmitted; if not, the pipeline stops early.
ECC Rendering Pipeline	A `link.v2` ECC variant (EccSingle / MultiItem) is created or updated	ecclink-projector, ecc-image-render-service, eslimage-merger, pricer-server	The parallel ECC rendering path: `link.v2` → `ecclink` → `ecceslimage` → merged `eslimage` → hardware.
ESL Hardware Lifecycle	Link created, physical ESL communicates (or stops communicating)	link-registry, pricer-server	Tracks an ESL from initial onboarding through normal operation, roaming, intentional offboarding, and final deletion from the platform.

Authoritative source notes¶

These flow pages are syntheses of the running system. For the original migration context and design rationale (PLT-2484, PLT-2487) that informed several of these flows, the in-repo handover notes are authoritative:

PLT-2484-full-flow.md — full flow analysis for the link.v1 → link.v2 migration
PLT-2487-overview.md — image DTO split (renderedimage → studioeslimage / ecceslimage / eslimage)
esl-status.md — the canonical storeeslstatus state machine and rationale (ADR-006 source material)
itemproperties-PLT2690.md — itemproperties structure and the property-schema flow
itemprocessingparameters-handover.md — itemprocessingparameters semantics

When a flow page diverges from these notes, the running system (and updated proto/code) is authoritative; flag the drift.