Implementation Plan - Multi-location Inventory Transfers

Milestones

Execution plan by track

Use the filter to isolate the track you are actively implementing. Default view shows the full dependency order.

Platform

M1. Transfer domain model and status machine

Create server-side transfer aggregate with states draft, requested, approved, dispatched, received, reconciled, cancelled.

Week 1 Dependency for all UI Auth + audit included

Owner Platform squad Exit State transitions covered by tests

Data

M2. Inventory reservation and ledger posting

Add source-location reservation on approval and destination receipt posting on receive. Prevent negative stock and duplicate dispatch posting.

Week 2 Idempotency required Backfill script needed

Owner Data platform Exit Ledger parity verified in staging

Platform

M3. Request, approval, dispatch, and receive APIs

Expose create, list, approve, dispatch, and receive endpoints with line-level variance notes and actor attribution.

Week 2 to 3 Supports mobile receiving flow Rate-limited writes

Owner Platform squad Exit Contract tests passing

Ops

M4. Store UI, approval queue, and receiving checklist

Ship request composer for managers, dispatch checklist for source site, and receipt confirmation for destination site with barcode fallback.

Week 3 to 4 Keyboard-safe controls Printable transfer slip

Owner Ops frontend Exit Pilot flows complete in staging

Ops

M5. Pilot rollout with 3 live locations

Enable for central kitchen, Midtown, and Riverside. Measure transfer cycle time, variance rate, and manual stock adjustments avoided.

Week 5 Shadow mode for first 3 days Daily ops review

Owner Ops program manager Exit Less than 3% unresolved variance

Ops

M6. General availability and legacy workflow removal

Cut over from spreadsheet-based transfers, freeze ad hoc adjustment shortcut, and document exception handling for damaged or partial receipts.

Week 6 Training required Support runbook published

Owner Ops + support Exit All sites migrated

Working model

Transfer lifecycle

Keep business logic aligned to this order. Reservation happens before physical dispatch.

1. Request

Manager selects source, destination, line items, need-by date, and justification.

2. Approve

Source approver validates available stock; system reserves requested quantity.

3. Dispatch

Picker confirms packed quantity, prints slip, and posts dispatch event once.

4. Receive

Destination records received quantity, flags variance, and posts receipt into local stock.

Reservation only on approval Dispatch is idempotent Receipt can be partial

Target dates

Six-week rollout calendar

Wk 1

Domain + permissions

State machine, actor roles, audit trail schema, feature flag scaffolding.

Wk 2

Ledger + reservation

Reservation writer, negative stock guardrails, migration rehearsal on staging copy.

Wk 3

API + list views

Create, approve, dispatch, receive endpoints plus transfer list and detail surfaces.

Wk 4

Store workflows

Approval queue, dispatch checklist, receipt variance screen, printable transfer slip.

Wk 5

Pilot

Three-site pilot with shadow reconciliation and daily review of variance events.

Wk 6

General availability

Enable all stores, retire spreadsheet flow, and publish support runbook and training.

Schema

Database changes

Table	Key columns	Purpose
`inventory_transfers`	`id`, `source_location_id`, `dest_location_id`, `status`, `requested_by`, `approved_by`	Header record for lifecycle, actors, timing, and feature-flag rollout metadata.
`inventory_transfer_lines`	`transfer_id`, `ingredient_id`, `uom`, `requested_qty`, `packed_qty`, `received_qty`	Line-level quantities, variance notes, and receiving outcomes.
`inventory_reservations`	`reservation_id`, `transfer_id`, `location_id`, `ingredient_id`, `qty_reserved`	Separates reserved stock from on-hand stock after approval, before dispatch.
`inventory_transfer_events`	`event_id`, `transfer_id`, `event_type`, `actor_id`, `idempotency_key`, `payload_json`	Immutable audit history for approval, dispatch, receipt, reconciliation, and cancellation.

API contract

Backend surface area

Keep writes explicit and idempotent. The client must never patch stock directly.

POST /api/transfers GET /api/transfers POST /api/transfers/:id/approve POST /api/transfers/:id/dispatch POST /api/transfers/:id/receive

Create request payload

Required: sourceLocationId, destinationLocationId, needByDate, lines[], reasonCode. Reject if source and destination match.

Approve dispatch rules

Approval reserves stock. Dispatch accepts packedQty per line and requires an Idempotency-Key header to prevent duplicate stock postings.

Receive rules

Receiving may post less than packed quantity. Any variance over 5% requires a reason code and creates a follow-up reconciliation task.

Rollout stages

Operational release plan

Stage	Audience	Guardrails	Success metric
Stage 0: Internal staging	Engineering + ops QA	Seeded stock data, synthetic transfers, migration rollback ready	All contract tests green, no ledger drift after replay
Stage 1: Pilot shadow mode	3 locations, no accounting cutover	Spreadsheet remains source of truth for 3 days	Variance between system and manual log below 2%
Stage 2: Pilot authoritative	Same 3 locations	Ops manager approves all transfers, daily exception review	Median cycle time under 45 minutes
Stage 3: Regional rollout	All city stores	Feature flag by location, support runbook live	Manual stock adjustments reduced by 60%

Duplicate dispatch posting

High

Retrying dispatch after a flaky network response could double-deduct source inventory.

Mitigation: Require idempotency keys and store dispatch event hash before ledger mutation.

Reservation drift

High

Manual stock adjustments at source location may conflict with reserved quantities.

Mitigation: Show reserved vs available in adjustment tooling and block negative available stock.

Receiving friction on mobile

Medium

Destination managers often receive from phones in back-of-house areas with weak connectivity.

Mitigation: Large step-by-step receipt UI, offline draft capture, and printable dispatch slip.

Partial receipt ambiguity

Medium

Teams may not know whether missing quantity should be re-shipped, adjusted, or discarded.

Mitigation: Force a variance reason and create reconciliation task automatically.

Ops adoption lag

Low

Store leads are used to spreadsheet transfers and may bypass the new flow during rush periods.

Mitigation: Limit legacy shortcut after GA and publish a one-page training guide.

Reporting mismatch

Low

Existing stock movement reports may omit transfer reservations and show confusing deltas.

Mitigation: Add transfer event dimensions before pilot review starts.

Acceptance criteria

Minimum ship bar

Approved transfer reserves stock and reduces available quantity without changing on-hand quantity.
Dispatch endpoint is idempotent and safe to retry after a 500 or network timeout.
Receiving flow supports partial quantities and captures variance reasons per line.
Transfer detail page shows actor history, timestamps, and immutable event log.
Feature flag can enable or disable by location without requiring deploy.
Pilot dashboard reports cycle time, variance rate, and unresolved transfer count daily.

Open questions

Resolve before Week 2 ends

Approval policy

Can any destination manager request from any source site, or do transfers need a regional approval matrix?

Unit normalization

Some ingredients move in cases while stores count eaches. Should conversion happen at request time or receipt time?

Carrier evidence

Do we need a photo attachment or signature capture on dispatch for third-party runners?

Accounting treatment

Should cross-location transfers create accounting entries immediately, or continue as operational-only movements?