Digital Twin / Planning Brief / 2026-08-21

Current state and work queue

Products is built. Its data pipeline is not finished.

The UI and APIs run, and serialized receiving reaches Cosmos and SQL. The remaining work is to carry the real tenant ID, consume live Formulary and location data, then replace the limited Products query.

The situation

Three statements are enough to understand where the project stands.

Working now

Serialized receiving reaches the Products API.

Serialization publishes a receiving event. Digital Twin stores a Cosmos inventory position, projects it to SQL, and serves it through existing endpoints.

Why results are incomplete

The reference data and correction flows are not connected.

Tenant ID, Formulary changes, location/category changes, non-serialized quantities, cycle-count corrections, and later movements are incomplete.

Recommended move

Finish three existing dependencies, then replace the query.

Tenant propagation, Formulary consumption, and location consumption unlock correct grouping, filtering, and location counts.

The critical path

Stages 1 and 2 establish trustworthy data. Stages 3 and 4 deliver the user-facing reads. Stage 5 removes obsolete machinery.

Formulary and location consumption can proceed in parallel after the tenant contract is settled.

Carry tenant ID through receiving

Stop writing Guid.Empty. Carry the TenantConfig root ID from the event through Cosmos and SQL.

#327055 / Tech Grooming

Consume live reference data

Bring Formulary mappings, hierarchy, and physical container category into Digital Twin.

#315051 / New
#315053 / Active

Replace the Products query

Add paging, search, correct location counts, and Dispensable/Non-dispensable filtering using detailed SQL tables.

#265915 / Active feature

Finish Product Details

Use the same product identity, tenant, facility, and quantity rules as the Products list.

#265916 / Active feature

Remove the old aggregate

Delete FacilityFormularyAggregate only after the replacement reads are correct and fast enough.

Inputs into Digital Twin

Source status, what Digital Twin does today, and whether work is already queued.

Built with gapSerialized receiving
Source

Serialization publishes receiving outcomes.

Digital Twin today

Cosmos and SQL writes work, but the event and Cosmos record lack the TenantConfig root ID. SQL writes Guid.Empty as the tenant ID.

Existing work

#327055 fixes tenant propagation. #288332 covers broader count updates.

QueuedFormulary changes
Source

Formulary publishes create, update, archive, 340B, and grouping changes.

Digital Twin today

No integrated consumer keeps local Formulary and NDC mappings current.

Existing work

#315051 is New and needs architectural refinement.

ActiveLocation and category
Source

Container Management publishes hierarchy and container-category changes.

Digital Twin today

The inspected integration baseline has no consumer that keeps location hierarchy and physical category current.

Existing work

#315053 is Active. Its expected event contract needs verification.

QueuedNon-serialized receiving
Source

The publisher is not complete.

Digital Twin today

No complete consumer or agreed quantity behavior.

Existing work

#323919 covers publication only and is in Tech Grooming.

QueuedCycle-count completion
Source

CycleCount publishes completion events.

Digital Twin today

No integrated consumer replaces expected container contents with the completed count.

Existing work

#288344 is New. #327263 handles payloads over 1,000 items.

Sprint readyRecall changes
Source

Recalls publishes active and inactive recall targets.

Digital Twin today

No integrated consumer maintains the local recall target set.

Existing work

#315054 is Sprint Ready, but its direct SQL design needs an explicit architecture decision.

No clear storyQuarantine removal
Source

Only a best-effort RxTransparent call was found.

Digital Twin today

No durable event removes or reclassifies the Digital Twin position.

Existing work

No clear Digital Twin story was found.

MissingInventory movement
Source

No complete event or API path was found for putaway, restock, adjustment, or movement.

Digital Twin today

Received inventory cannot reliably move from a temporary virtual location into physical inventory.

Existing work

Several task and alert features mention movement, but no clean end-to-end story was found.

Six decisions still block clarity

These are product or architecture choices. More coding will not resolve them automatically.

Decision 01

Where reference state lives

The intended flow stores external changes in Cosmos before SQL. Formulary and recall stories currently write directly to SQL. Revise them or approve an explicit exception.

Decision 02

What identifies a product

Work items alternate among Formulary item, GPI, and equivalency group. Choose one stable identifier for list rows, detail URLs, and cross-facility grouping.

Decision 03

What the location number counts

Earlier work says one facility counts bins and multiple facilities count facilities. The active feature also contains language that always counts bins.

Decision 04

How inventory becomes dispensable

Define the exact rule for physical container categories and temporary virtual inventory. The backlog defines tabs, not the classification rule.

Decision 05

How unknown quantities behave

Product Details permits an NDC to be present with no reliable quantity. Decide how that affects Products totals, values, and category counts.

Decision 06

Where cost comes from

Products and Product Details require EDI-810 cost and value, but the current read model has no established path for that data.

What the queue is telling us

Use the existing stories, but clean up overlaps and contract mismatches before pulling them.

Do not duplicate foundation stories.

Tenant, Formulary, location, recall, cycle count, and non-serialized publication work already exists.

Location consumption may target the wrong contract.

#315053 has a child task referencing FacilityUpsertedEvent; the integrated source publishes a wrapped LocationHierarchyChanged message.

Two stories bypass the intended Cosmos-first flow.

#315051 and #315054 write reference data directly to SQL. Make that choice explicit.

Receiving work overlaps.

#265918, #288332, resolved receiving work, and #323919 divide serialized, pack-level, and non-serialized behavior inconsistently.

Old discovery tasks need reconciliation.

Virtual-bin tasks remain New under a removed story. Digital Twin design tasks remain New under a closed story. Do not schedule them without checking whether this analysis already satisfies them.

Alerts and data-platform work can wait.

Expiration, PAR/restock, recall task generation, and data-platform publication are future capabilities, not prerequisites for replacing the Products query.

The intended data flow

External changes are retained in Digital Twin before SQL, so SQL can be rebuilt and reads stay fast.

Evidence and detail

The visual brief is the entry point. These files contain the technical proof.