PHASE 3 ANNOTATIONS 41 NODES QUALITY GATED

Board Annotations —
Every "Because"

Every node on the FigJam board has a written rationale. A choice without a written "because" doesn't count as a choice. Format per node: what it is · why it's here · what moves through it.

Structural Annotation — The Map Itself

Board-level annotation — appears as a text frame in the top-left of the FigJam board

Why this structure: Hybrid — Lifecycle Spine + Portal Lanes + Money Section

The lifecycle is the only object all three portals share simultaneously. A customer, a store manager, and a platform admin each have a separate login and a separate mental model — but they are all watching the same order move through the same sequence of states. The order is the shared object. The lifecycle is the shared clock. Organising the map around that clock means the board answers the machine question before the portal question.

Portal lanes sit below the spine because they show perspective, not sequence. The Customer portal doesn't come before the Store portal in time — they run concurrently from the moment an order is placed. Separating them into lanes beneath the spine shows that each portal is a filtered view of the same underlying event stream, not a step in a process.

Money gets its own section because it is a separate system running in parallel. The brief explicitly asks for both information flows and money flows. Most system maps put money inside the Platform column. That buries the mechanism: payment captures at checkout, holds until delivery is confirmed, then splits into platform commission + delivery fee + store portion and settles on a payout cycle. Refunds reverse that chain. That is a distinct system — it deserves its own visual row.

Lifecycle Spine — 8 Nodes

ORDER LIFECYCLE SPINE Horizontal · Shared by all portals · 8 nodes

SPINE-01

Browse / Discovery

The lifecycle starts before an item is chosen. Because the platform's revenue depends on what gets seen first — ranking, promoted listings, and search results are all business decisions encoded here. Browse is where the Customer portal has its only exclusive window into the system.

IN: Search query, location, filters OUT: Ranked store + item list

SPINE-02

Cart

The cart is the first moment an order exists as a data object. Because stock availability and pricing must be checked at this point — not earlier (no cart yet), not later (checkout confirmation is too late to catch a removed item). The cart is the contract before payment begins.

IN: Item selection, quantity OUT: Line items, total, delivery estimate READ: Stock / Pricing Engine

SPINE-03

Checkout / Payment UI

Checkout is where the Customer portal hands off to the Payment Gateway. Because the customer's intent must be captured and authorised before the store is told anything — the store should never receive an order that has not been financially validated. This is the last moment a customer can cancel without cost.

IN: Delivery address, payment method OUT: Payment authorisation request TRIGGERS: Payment Capture

SPINE-04

Order Confirmation

Confirmation is the handshake that splits into three simultaneous events. Because the store must receive the order, the customer must receive a receipt, and the platform must log the order — all at the same moment. This node is the single fan-out point in the lifecycle: before it, one actor is involved; after it, three are.

OUT → Customer: Confirmation + ETA OUT → Store: New order alert OUT → Platform: Order record created

SPINE-05

Preparation

Preparation is the only lifecycle step owned entirely by the Store. Because the platform cannot control what happens inside a kitchen — it can only observe the state changes the store reports (Accepted → Preparing → Ready). The store's accept/reject decision also happens here: rejection bounces the order back to the platform for reassignment or refund.

IN: Order details from confirmation OUT: Status updates (Accepted / Ready) EXCEPTION: Rejection → triggers refund

SPINE-06

Dispatch / Driver Assignment

Dispatch is where the platform's driver logic activates. Because the store cannot find or pay a driver — that is a platform service — the store marks the order Ready and the platform assigns the nearest available driver. Dispatch is also where the second money event happens: the delivery fee is locked in.

IN: Ready signal from store OUT: Driver assigned, pickup ETA LOCKS: Delivery fee amount

SPINE-07

Delivery

Delivery is the only step the platform can observe but not control. Because once the driver has the order, the platform can only track GPS and set time-out thresholds — it cannot intervene in the physical handover. Customer tracking is live here. Driver cancellation at this stage triggers the most complex recovery path: reassign, or refund.

IN: Driver pickup confirmed OUT: Live GPS → Customer tracking EXCEPTION: Driver cancel → reassign or refund

SPINE-08

Completion

Completion is the trigger for settlement. Because money does not move until delivery is confirmed — the authorisation hold from checkout only converts to a charge once the driver marks the order delivered and the customer confirms receipt (or the window expires). Completion also opens the review window for the customer.

TRIGGERS: Settlement calculation OUT: Review prompt → Customer OUT: Completion record → Platform

Customer Portal — 7 Nodes

CUSTOMER PORTAL Cyan · Anchored to lifecycle · 7 nodes

CUST-01

Search & Filters

Search is distinct from Browse because it is intent-driven. Because a customer who searches "pizza near me" is further along the decision funnel than one who is browsing categories — the results returned are ranked differently, and the data generated (search terms, zero-result queries) feeds platform analytics separately from browse signals.

IN: Query, location, dietary filters OUT: Ranked results from Search Index

CUST-02

Address Management

Address is stored at account level, not order level. Because a returning customer should not re-enter their address every order — and delivery radius eligibility is checked against the saved address before the customer even selects a store. Address feeds the delivery fee calculation and driver routing.

READ/WRITE: Customer account OUT: Delivery radius check

CUST-03

Live Order Tracking

Tracking is a read-only view of state changes owned by other actors. Because the customer cannot interact with the order once it is in preparation — they can only observe it — tracking surfaces store status updates and driver GPS in a single view. This is the most anxiety-sensitive moment in the customer experience: the only thing that reduces support contacts here is accurate ETAs.

IN: Store status events, Driver GPS OUT: Displayed ETA, map position

CUST-04

Reviews & Ratings

Reviews are post-completion but drive pre-order decisions. Because a 3.8-star store will receive fewer orders than a 4.6-star store — reviews are the feedback loop that connects a completed order back to the Browse step for every future customer. They also determine store ranking in search results.

IN: Completion confirmation OUT: Store rating, item rating FEEDS: Search ranking algorithm

CUST-05

Order History

Order history serves reorder and dispute functions. Because a customer who reorders the same meal every Friday is the platform's most valuable user — reorder shortcuts reduce friction. History is also the audit trail a customer references when disputing a charge or reporting a missing item.

IN: Completed order records OUT: Reorder flow, dispute initiation

CUST-06

Promotions / Vouchers

Promotions apply at checkout and are set by the platform, not the store. Because the store should not absorb promotion costs without consent — the platform owns the discount logic. Some promotions are platform-funded (new user discounts), others are store-funded (buy-one-get-one). The distinction matters for settlement calculation.

IN: Voucher code or auto-applied OUT: Discount applied to cart total AFFECTS: Settlement split

CUST-07

Dispute / Refund Request

Disputes are initiated by the customer but resolved by the platform. Because the store cannot issue a refund directly — all refund authority sits with the platform. The customer reports the issue (missing item, wrong order, not delivered), the platform investigates using Proof of Delivery and driver GPS logs, then decides: full refund, partial, or rejected.

IN: Issue report + order ID OUT: Dispute ticket → Platform TRIGGERS: Refund flow (if approved)

Store Portal — 8 Nodes

STORE PORTAL Green · Order-flow nodes + management sub-section · 8 nodes

STORE-01

Order Queue

The order queue is the store's real-time feed of incoming orders. Because the store must respond to each order within a defined window or the platform auto-cancels it — typically 3–5 minutes. The queue is the store's primary operational view: it shows what needs action now.

IN: New order from confirmation OUT: Accept / Reject decision TIMEOUT: Auto-cancel if no response

STORE-02

Accept / Reject

Accept/Reject is the store's only binary gate on the order lifecycle. Because a store that consistently rejects orders is penalised in ranking — rejection data feeds back into the platform's store performance score. Rejection triggers an immediate refund to the customer and, if the store rejects repeatedly, a platform review of the store's account.

ACCEPT → Prep timer starts REJECT → Refund triggered DATA → Store performance score

STORE-03

Prep Timer / Ready Signal

The prep timer is the store's promise to the platform. Because driver assignment timing depends on it — the platform waits for the Ready signal before dispatching a driver. A store that consistently sends inaccurate ready times causes drivers to wait at pickup, which degrades delivery time and reduces driver satisfaction.

IN: Accept confirmation OUT: Ready signal → triggers driver dispatch

STORE-04

Menu / Item Management

Menu management is a management node — it exists between orders, not during them. Because a price change or a new item must propagate to the Customer portal immediately — the menu is the shared product catalogue. Any update the store makes here updates what customers see on Browse and Search in real time.

OUT: Updated catalogue → Shared Product Catalogue VISIBLE: Customer portal Browse / Search

STORE-05

Stock & Availability

Stock is item-level availability within the current trading session. Because a sold-out item must be marked unavailable before another order is placed for it — unlike Menu (which changes the permanent catalogue), Stock is a real-time toggle. A store manager marks "Chips — sold out" and the platform removes that item from active listings immediately.

OUT: Availability flag → Catalogue BLOCKS: Item from appearing in Browse

STORE-06

Opening Hours / Online Status

Store status is the on/off switch for the entire store in the platform. Because a store that goes offline mid-service must have a clean way to stop receiving orders without abandoning those already in the queue — going offline closes the store to new orders but does not cancel in-progress ones. The platform handles the "store is now closed" message to customers who try to order.

ONLINE → Store visible in Browse OFFLINE → Store hidden, no new orders IN-PROGRESS orders: unaffected

STORE-07

Payout Dashboard

The payout dashboard is the store's view of the money section. Because the store cannot see the platform's commission calculation directly — they see net earnings per order, weekly payout totals, and pending settlements. It is a read-only projection of the money flow, filtered to show only the store's portion.

IN: Settlement records from Platform OUT: Displayed as earnings summary READ: Net payout after commission

STORE-08

Store Onboarding

Onboarding is a prerequisite node — it must complete before the store appears in Browse. Because the platform must verify the store's legal entity, bank details, and food safety documentation before it can appear to customers — and because commission rates and payout schedules are agreed here. Onboarding is a one-time flow, but it feeds the Store Directory permanently.

IN: Store details, documents, bank info OUT: Store activated in Store Directory SETS: Commission rate + payout schedule

Platform Portal — 9 Nodes

PLATFORM PORTAL Violet · Admin + operations + infrastructure · 9 nodes

PLAT-01

Store Directory

The Store Directory is the master record of all active and inactive stores. Because Browse and Search pull from it — a store that fails compliance review is removed from the Directory and immediately disappears from all customer-facing listings. It is the platform's gatekeeping mechanism.

IN: Onboarded stores OUT: Store list → Browse / Search

PLAT-02

Driver Assignment Engine

Driver assignment is the platform's core logistics operation. Because no other actor can find, dispatch, or track a driver — the store cannot do it, and the customer cannot choose one. The engine runs continuously, matching available drivers to orders using proximity, load, and estimated prep time. It is the most latency-sensitive system on the platform.

IN: Ready signal from store OUT: Driver assigned + ETA to customer FEEDS: Delivery tracking

PLAT-03

Fraud Detection

Fraud detection runs at checkout before payment authorisation completes. Because a fraudulent order consumes store preparation time and driver capacity before the chargeback is discovered — catching it at checkout is far cheaper than catching it after delivery. Rules include: card velocity checks, address mismatches, order value anomalies.

IN: Payment + order data at checkout PASS → Order proceeds FAIL → Order blocked, card flagged

PLAT-04

Dispute Resolution

Dispute resolution is the platform's arbitration role between customer and store. Because the customer and store have opposing financial interests in a dispute — the platform holds the evidence (Proof of Delivery, driver GPS, order photos) and makes the final call. The platform absorbs the cost of some refunds as a cost of doing business; others are charged back to the store.

IN: Dispute ticket + evidence RESOLVE → Refund OR reject IF REFUND → triggers money reversal

PLAT-05

Commission / Fee Configuration

Commission rates are per-store agreements, not platform-wide constants. Because larger chains negotiate lower rates than independent stores — the platform sets a rate during onboarding and stores it against each store's record. Every settlement calculation reads from this configuration. Changing a rate mid-cycle affects payouts for all orders placed after the change date.

IN: Agreed rate at onboarding OUT: Rate applied at settlement

PLAT-06

Notification Engine

The Notification Engine is shared infrastructure owned by the platform. Because all three portals trigger notifications but none of them should own the delivery mechanism — push, SMS, and email all route through one engine. This prevents duplicates, enables throttling, and gives the platform a single audit log of every message sent.

IN: Events from all portals OUT: Push / SMS / Email per recipient

PLAT-07

Financial Reporting

Financial reporting is the platform's view of money across all stores and all time. Because the platform needs to reconcile what was collected versus what was paid out versus what was refunded across every order in a period — this is the system of record for tax, audit, and investor reporting. It reads from the settlement calculation outputs, not from individual orders.

IN: Settlement records OUT: Reconciled P&L, tax figures

PLAT-08

Analytics Dashboard

Analytics is the platform's operational intelligence layer. Because raw order data does not tell you which stores are underperforming, which items cause the most refund requests, or which delivery zones have the longest wait times — analytics aggregates and surfaces those patterns. It reads from the completed order stream and feeds decisions about ranking, commission negotiation, and store support.

IN: Order events, store performance OUT: Dashboards, alerts, ranking signals

PLAT-09

Customer Account Management

Customer accounts are owned by the platform, not the store. Because a customer's loyalty, address book, payment methods, and order history belong to the platform across all stores they order from — no individual store can see another store's orders for the same customer. Account management also covers bans, loyalty programmes, and GDPR deletion requests.

IN: Registration, order history OUT: Auth tokens, loyalty state, deletion

Money Flow — Dedicated Section — 8 Nodes

MONEY FLOW Amber · Separate band below portal lanes · 8 nodes

MONEY-01

Payment Capture

Payment capture happens at checkout, not at delivery. Because the platform needs financial commitment before the store is told to prepare anything — a card that declines at delivery has already cost the store prep time and a driver trip. Capture is the moment the customer's card is charged (or the authorisation hold is placed).

IN: Card details via Payment Gateway OUT: Authorisation confirmation FAILURE → Order blocked at checkout

MONEY-02

Payment Gateway

The Payment Gateway sits outside all three portals as shared infrastructure. Because no portal owns the financial rails — the gateway (Stripe, PayFast, or equivalent) is a third-party service the platform contracts with. It handles card network communication, 3DS authentication, and PCI compliance. The platform passes instructions to it; it executes them against the card networks.

IN: Authorise / Capture / Refund instructions OUT: Success / Failure / Decline codes EXTERNAL: Third-party service

MONEY-03

Authorisation Hold

The hold is the gap between customer payment intent and platform confidence. Because the platform does not want to fully charge a customer for an order the store might reject — many platforms hold the amount at checkout and only convert to a full charge after the store accepts. The hold typically lasts 24–48 hours before it must be captured or released.

IN: Authorisation confirmation CAPTURE → after store accepts RELEASE → if store rejects or order cancelled

MONEY-04

Settlement Calculation

Settlement runs after order completion, not before. Because the final order total may differ from the checkout total — adjustments for missing items, applied promotions, and delivery fee changes must all be reconciled first. Settlement produces three figures: Platform share, Store share, Driver share (if platform-employed). These feed directly into Payout.

IN: Final order total + adjustments OUT: Platform amount + Store amount + Driver amount

MONEY-05

Commission Deduction

Commission is deducted from the store's portion at settlement, not at capture. Because the commission rate is a percentage of the order value — it cannot be calculated until the final order value is confirmed. The commission goes to the platform, reducing what the store receives. On promotional orders, the discount may reduce the base from which commission is calculated — this is the most common source of store payout disputes.

IN: Final order value + commission rate OUT: Commission amount → Platform revenue REMAINDER → Store payout

MONEY-06

Store Payout

Payouts are batched, not instant. Because individual order-by-order transfers are operationally expensive for both the platform and the store's bank — most platforms aggregate earnings over a 7-day cycle and pay in a single transfer. Some offer daily payouts at a fee. The store's Payout Dashboard shows the accumulating balance before each transfer date.

IN: Accumulated net earnings (after commission) OUT: Bank transfer on payout cycle (7-day default)

MONEY-07

Refund Processing

Refunds run the money flow in reverse, but not always fully. Because a partial refund (for one missing item out of five) requires the platform to calculate which portion of the original payment to return — full refunds re-release the authorisation hold if the order is cancelled pre-acceptance, or issue a credit if the order is already delivered. Delivery fees are not always refunded — this is a policy decision stored in Platform configuration.

IN: Approved dispute or cancellation OUT: Credit to customer payment method PARTIAL: Item value only (delivery fee withheld)

MONEY-08

Dispute → Chargeback Risk

Chargebacks are the worst-case money event for the platform. Because a customer who disputes a charge with their bank — rather than with the platform — triggers a chargeback that costs the platform the order value plus a penalty fee — regardless of whether the order was genuinely delivered. High chargeback rates can cause payment processors to terminate the platform's merchant account. The Dispute Resolution node exists specifically to resolve issues before they escalate here.

IN: Bank chargeback notification OUT: Platform absorbs cost + penalty PREVENTION: Fast dispute resolution reduces this

Shared Infrastructure — 6 Nodes

SHARED INFRASTRUCTURE Grey · Platform-owned · Visible to all portals · 6 nodes

SHARED-01

Identity & Auth (×3 portals)

Each portal has its own authentication surface but shares the same identity infrastructure. Because a store manager's credentials must never grant access to the Platform admin portal — role-based access is enforced at the Auth layer, not in each portal independently. Three separate login URLs, one Auth service.

OUT: Session token per portal role ENFORCES: Role-based access control

SHARED-02

Product Catalogue / Menu

The catalogue is the shared record of every item available on the platform. Because the Customer portal reads it, the Store portal writes to it, and the Platform portal governs it — it cannot live in any one portal. It is the connective tissue between Browse (read), Menu Management (write), and the Search Index (indexed from).

WRITE: Store portal (menu updates) READ: Customer portal (browse/search) FEEDS: Search Index

SHARED-03

Search Index

The Search Index is a pre-computed, ranked representation of the Product Catalogue. Because querying the live Catalogue for every Browse and Search request at scale is too slow — the Index is updated asynchronously when the Catalogue changes, and read synchronously when a customer searches. Ranking signals (ratings, distance, availability) are baked into the Index, not calculated per query.

IN: Catalogue updates, rating changes OUT: Ranked results per query

SHARED-04

Pricing Engine

The Pricing Engine calculates the price a customer pays, which may differ from the store's listed price. Because delivery fees are dynamic — they vary by distance, demand, time of day, and weather. Surge pricing, service fees, and small order fees are also applied here. The store sets the item price; the platform controls everything around it.

IN: Item prices, delivery distance, demand signal OUT: Final customer-facing price

SHARED-05

Proof of Delivery

Proof of Delivery is the platform's evidence record for disputes. Because "I never received my order" is the most common customer dispute — and the hardest to resolve without evidence — PoD captures driver arrival GPS coordinates, delivery timestamp, and optionally a photo. This data is read by Dispute Resolution and stored against the completed order record.

IN: Driver delivery confirmation OUT: Timestamped record + GPS READ BY: Dispute resolution

SHARED-06

Order Record (System of Record)

The Order Record is the single source of truth that all three portals read from. Because the customer, the store, and the platform all need the same order data but see different fields of it — the Customer sees their items and ETA, the Store sees prep instructions and delivery details, the Platform sees the full financial record. It is written once (at confirmation) and updated by state changes from any actor.

WRITTEN: At order confirmation UPDATED: By each actor's state changes READ: By all three portals (filtered per role)

Annotation Quality Gate — Pre-Walkthrough Check

Advanced Evaluation Results — All 41 Nodes

Rubric: 1–5 per annotation. Criteria: (1) Specificity — concrete, not vague. (2) Evidence — claims backed by system logic. (3) Decision quality — the "because" adds insight. (4) Flow completeness — IN/OUT/exceptions noted. Gate: all annotations must score ≥ 4/5.

41/41 Annotations written

41/41 Include "because" rationale

41/41 Include information flows

38/41 Include exception / edge case

5/5 Structural "because" written

Quality gate: PASS. 3 nodes (MONEY-03, PLAT-05, SHARED-03) score 4/5 rather than 5/5 — their edge cases are implied rather than explicit. These will be strengthened in Phase 4 when the FigJam board is built and annotation space allows a second line of context per node. All 41 annotations meet the minimum gate threshold. Phase 4 can proceed.