Structural Topology & Register Modeling

The structure of the POS domain is built around three integrated models: the retail store topology, the payment and receipt structure, and the offline-first edge architecture. Together they define how terminals, sessions, drawers, transactions, and tenders are organized and reconciled.

---

1. Retail Topology: Store → Register → Drawer → Shift → Transactions

The retail topology models the physical and operational hierarchy of a point-of-sale environment.

Store / Branch
└── Register / Terminal Station
    ├── Active Drawer
    │   ├── Shift Session
    │   │   ├── Opening Float
    │   │   ├── Transactions (Sales, Refunds, Voids)
    │   │   ├── Cash Drops
    │   │   ├── Petty Expenses
    │   │   └── Closing Count
    │   └── Cash Movements
    └── Hardware Peripherals
        ├── Barcode Scanner
        ├── Receipt Printer
        ├── Payment Terminal
        ├── Customer Display
        └── Cash Drawer Lock

Topology Levels

Level	Description	Key Attributes
Store / Branch	The physical retail location where registers operate.	Store code, address, timezone, business hours, tax jurisdiction.
Register / Terminal	The physical POS device assigned to a station.	Terminal ID, hardware profile, status (online/offline), store assignment.
Terminal Station	The logical configuration of a register for a specific counter or department.	Station code, default drawer, allowed tender types, receipt template.
Active Drawer	The cash container currently assigned to a session.	Drawer ID, opening float, current expected balance.
Shift Session	The cashier’s work cycle on a drawer.	Session ID, cashier, open time, close time, state.
Transaction	A single sale, refund, or cancellation event.	Receipt number, sequence, timestamp, line items, tenders.

One Terminal, One Active Session Rule

A terminal may have only one active shift session at a time. A new session cannot be opened until the previous session is properly closed and reconciled, except under supervised exception protocols.

---

2. Receipt & Payment Structure

A POS receipt is the central document of a checkout transaction. It captures line items, modifiers, discounts, taxes, and one or more tender payments.

Master POS Receipt
├── Store / Terminal / Session References
├── Line Item Snapshots
│   ├── Product Code / Barcode
│   ├── Description
│   ├── Quantity
│   ├── Unit Price
│   ├── Modifiers
│   ├── Discounts
│   └── Tax Category
├── Tax Breakdown
│   ├── Tax Category A: 5.00
│   └── Tax Category B: 8.00
├── Total Amount
└── Tender Payments
    ├── Cash: 50.00
    ├── Card: 30.00
    └── Store Credit: 10.00
        └── Change Due: 5.00 (Cash)

Receipt Components

Component	Purpose
Receipt Number	Unique identifier for the transaction, typically store-terminal-sequence formatted.
Sequence Number	Monotonic terminal-level counter used for ordering and replay.
Line Item Snapshots	Frozen product description, price, tax, and quantity at time of sale.
Tax Breakdown	Summary of taxes collected by category or jurisdiction.
Tender Payments	Detailed record of each payment method and amount.
Change Due	Amount returned to customer, always non-negative.
Timestamp	Local and UTC timestamps of transaction completion.
Cashier / Operator	Identity of the session operator who executed the transaction.

Multi-Tender Rules

Rule	Invariant
Total Coverage	Sum of tender amounts must equal or exceed the receipt total before completion.
Change Limitation	Change is issued only against cash or cash-equivalent tenders (e.g., not against card overpayment).
Store Credit Restrictions	Store credit may not be refunded as cash unless local regulation requires.
Gift Card Partial Use	Gift card tender cannot exceed the available stored value; remainder must use other tenders.
Foreign Currency	If supported, foreign cash tender is converted at the store’s current exchange rate.

Split Tender Example

Tender Type	Amount
Cash	50.00
Credit Card	30.00
Store Credit	10.00
Total Tendered	90.00
Receipt Total	85.00
Change Due (Cash)	5.00

---

3. Drawer Cash Movement Model

The drawer is a cash container whose expected balance is computed from all cash movements during the shift.

$$ \text{Expected Cash} = \text{Opening Float} + \text{Cash Sales} - \text{Cash Refunds} - \text{Cash Drops} - \text{Petty Expenses} $$

Drawer Movement Types

Movement Type	Direction	Description
Opening Float	In	Initial cash placed in drawer at shift start.
Cash Sale	In	Cash received from customer sales.
Cash Refund	Out	Cash returned to customer for returns.
Cash Drop / Skim	Out	Cash removed to safe mid-shift.
Petty Expense / Paid Out	Out	Cash disbursed for operational expenses.
Closing Count	—	Physical cash counted at shift end.

Discrepancy Calculation

$$ \text{Discrepancy} = \text{Actual Closing Cash} - \text{Expected Cash} $$

Discrepancy Value	Classification
Positive	Overage
Zero	Balanced
Negative	Shortage

---

4. Edge & Offline Architecture Model

POS terminals operate as edge nodes with local state and eventual consistency with central systems.

┌─────────────────────────────────────┐
│  POS Terminal (Edge Node)           │
│  ├── Local Product Cache            │
│  ├── Local Price / Tax Cache        │
│  ├── Local Stock Indicator          │
│  ├── Local Transaction Queue        │
│  ├── Monotonic Sequence Counter     │
│  └── Local Drawer State             │
└──────────────┬──────────────────────┘
               │ Sync when online
               ▼
┌─────────────────────────────────────┐
│  Central Obelaw System                 │
│  ├── PIM / Catalog                  │
│  ├── Inventory / WMS                │
│  ├── Sales / OMS                    │
│  ├── Accounting / FMS               │
│  └── CRM / Loyalty                  │
└─────────────────────────────────────┘

Offline-First Principles

Principle	Description
Local Cache Authority	While offline, the terminal uses locally cached product, price, and tax data.
Local Queue	Transactions are stored locally with monotonic sequence numbers until synchronization.
No Central Blocking	Checkout speed is not dependent on central system availability.
Eventual Consistency	On reconnection, queued events are replayed to central systems in sequence order.
Conflict Detection	Central systems detect sequence gaps or duplicates and reject invalid replays.

Monotonic Sequence Rules

Rule	Invariant
Per-Terminal Uniqueness	Every transaction receives the next ascending integer from the terminal’s sequence counter.
No Gaps Allowed	A missing sequence number indicates a lost or un-replayed transaction.
No Duplicate Sequences	The same sequence number cannot be accepted twice from the same terminal.
Immutable After Assignment	Sequence numbers are assigned at transaction time and never changed.

Sequence Validation Formula

For a terminal with last accepted sequence $S_{last}$ and a new transaction with sequence $S_{new}$:

$$ \text{Accept if } S_{new} = S_{last} + 1 $$

Gaps require investigation; duplicates are rejected as replays.

---

5. Local State Synchronization Topics

The terminal synchronizes the following data categories with central systems:

Data Category	Direction	Purpose
Product Master	Downlink	Cache product names, barcodes, tax categories.
Price Lists	Downlink	Cache current selling prices and discount rules.
Tax Rules	Downlink	Cache tax rates and jurisdictional rules.
Stock Availability	Downlink	Display available-to-sell indicators.
Customer Aliases	Downlink	Support loyalty lookup and store credit queries.
Transactions	Uplink	Replay completed sales, refunds, and cash movements.
Session Closures	Uplink	Send aggregated settlement data to FMS.
Configuration	Downlink	Update terminal profiles, tender types, and receipt templates.

This topology ensures that POS terminals can deliver fast, reliable checkout service while maintaining accurate, auditable, and eventually consistent integration with the central ERP ecosystem.