Pre-Book · Phase 1
End-to-End Flow & System Behavior
What happens between a user clicking Save and an order existing in Shopify — the five places pre-book data lives, the two payload paths, and the seven things the backend still has to confirm.
System map
Pre-book is a storefront experience with a backend handoff, not an application with a database. That distinction shapes everything in this document. There is no single system of record; there are five places data lives, each with a different lifetime and a different owner, and the program — the object the entire tool exists to manage — lives in the one that was never designed to hold it.
Two payload paths leave the storefront: save, which happens many times per program, and submit, which happens once and is final.
Where the data lives
Metafields have practical size limits, no transactional guarantees, and last-write-wins semantics. A large program, or a rep and a dealer touching the same program in the same window, is exactly the shape of problem metafields handle worst. This does not need solving in Phase 2, but Phase 3 cannot be scoped honestly without a decision on it — see CONF-08.
Save vs. submit
The two paths share a shape but not a consequence. Save is repeatable and reversible. Submit creates real orders, sends real email, and cannot be undone from the tool.
The payload
What leaves the storefront when a user saves or submits.
| Element | Purpose | Save | Submit |
|---|---|---|---|
| Request type | Tells the backend whether this is a pre-book request or a regular rep order | Yes | Yes |
| Dealer identity | Who the order belongs to | Yes | Yes |
| Rep identity | Who placed it, when a rep is acting | Yes | Yes |
| Line items | SKUs and quantities | Yes | Yes |
| Ship date | The chosen date inside the allowed window | Yes | Yes |
| PO number | Dealer's own reference | Yes | Yes |
| Note | Free text from the rep or dealer | Yes | Yes |
| Program state | The customer-linked program the storefront has been maintaining | Yes | Yes — complete set |
The exact field or flag that distinguishes a pre-book request from a regular rep order is known to the code but not written down anywhere. It is the single most important undocumented item in the system, because every branch on the backend hangs off it. See CONF-05.
Backend responsibilities
In the current implementation the backend service owns six jobs.
| Responsibility | Detail |
|---|---|
| Order creation | Creates Shopify orders when a program is submitted. |
| Dealer notification | Lets Shopify send its normal dealer confirmation off the created order. |
| Rep notification | Sends a separate custom rep-facing confirmation when one is needed. |
| Program state | Reads and updates saved program data in customer metafields, but only for requests it treats as pre-book. |
| State alignment | Keeps storefront and backend agreeing on the current saved-order state. |
| SKU resolution | Resolves uploaded CSV SKUs into valid, draft, unavailable, or missing. |
Pre-book vs. rep order
The backend does not treat every rep request the same way, and the distinction is consequential: a pre-book request is permitted to read and write saved program data, while a regular rep order should not touch that path at all.
| Request | Program data | Expected behavior |
|---|---|---|
| Pre-book submission | Read and write | Full program lifecycle: saved orders, totals, completion |
| Regular rep order | Must not use the saved-state path | Behaves like a standard order flow |
If a regular rep order is misclassified as pre-book, it can read or overwrite a dealer's live program state. If a pre-book submission is misclassified as a regular order, the program is never marked complete. Neither failure is loud. Documenting and hardening this discriminator is a prerequisite for Phase 3, not a detail of it.
Email split
Submission produces two confirmations from two independent systems.
| Recipient | Sent by | Consequence |
|---|---|---|
| Dealer / customer | Shopify, off the created order | Looks like a normal Shopify order confirmation — not like a pre-book program acknowledgment. The dealer receives a transactional receipt for a seasonal buying commitment. |
| Rep | Backend, custom | Separate template, separate delivery path, separate failure mode. It can fail silently while the dealer's email succeeds, or vice versa. |
The dealer confirmation is the last thing a dealer sees in the workflow and the only artifact they keep. Making it a genuine program acknowledgment — the whole program, its orders, ship windows, PO references, and totals, in St. Croix's voice — is one of the highest-leverage, lowest-cost improvements available. See PB-SUB-04.
Change events
Five events reshape the system's state mid-session. Each has a defined technical behavior and, in most cases, no defined user-facing behavior.
| Event | System behavior | User-facing behavior |
|---|---|---|
| Dealer changed | Working context resets so nothing attaches to the wrong dealer | Undefined — no warning documented |
| Pre-book turned off | Session state cleared; cart returns to standard checkout | Undefined — no warning documented |
| Program total changed | Threshold status recalculated; available ship dates may narrow | Status message updates; the ship-date consequence is not explained |
| Saved order edited | Order re-hydrated into cart; remains part of the program until re-saved or deleted | Loading screen, then a populated cart |
| Program submitted | Program marked complete; final payload sent; orders created | Undefined post-submit state — no confirmation surface |
Needs confirmation
Eight items the storefront cannot answer. Each is listed with what it blocks, so they can be triaged rather than treated as one undifferentiated list. Items marked P0 block Phase 3 estimation.
| ID | Question | What it blocks | Owner | Pri |
|---|---|---|---|---|
| CONF-01 | Where does the final submission land after it leaves the storefront? | Integration design for the future B2B platform | Backend | P0 |
| CONF-02 | Does the backend notify in every case, or only some? | Notification design; failure handling | Backend | P1 |
| CONF-03 | Orders, draft orders, or program data only — and in which scenarios? | Whether an amend path is even possible | Backend | P0 |
| CONF-04 | Does the backend update ERP or any other system? | Phase 3 scope and integration cost | St. Croix IT | P0 |
| CONF-05 | Which flag tells the backend pre-book from regular order? | Every backend branch; hardening work | Backend | P0 |
| CONF-06 | How are rep and dealer identifiers used downstream? | Rep attribution, reporting, commission | Backend | P1 |
| CONF-07 | What happens on submission with missing or empty rep information? | Error design; data integrity | Backend | P1 |
| CONF-08 | Do metafields remain the system of record for program data? | Phase 3 architecture and its cost band | Joint decision | P0 |
CONF-01, 03, 04, 05 and 08 should be closed in a single working session with St. Croix IT and whoever owns the Lambda before Phase 3 is priced. They are five questions, not five weeks of work — but until they are answered, any Phase 3 number is a guess with a wide band.