Version: 7.0.0
Last Updated: March 2, 2026
BRD Version: 20.0 (19,900+ lines, 7 modules, 113 decisions)
Total Screens: 118
This appendix provides a complete catalog of every user-facing screen in the POS Platform, derived from the Business Requirements Document (BRD v20.0, Chapter 05). Each screen is mapped back to its source BRD section, database tables, Appendix F services, and state machines — creating full traceability from business requirement to UI surface.
| Audience | Use Case |
|---|
| Frontend Developers | Find the complete specification for any screen they need to build |
| UI/UX Designers | Understand screen inventory, element requirements, and navigation flows |
| QA Engineers | Trace test scenarios back to specific screens and their business rules |
| Product Owners | Review screen coverage to ensure all BRD requirements have a UI surface |
| Architects | Verify that screen boundaries align with module boundaries and ADR decisions |
Each screen entry includes:
| Field | Description |
|---|
| Screen ID | Unique identifier: SCR-MXX-YY (M=module 01-06), SCR-RXX (Raptag), SCR-XXX (cross-cutting) |
| Product(s) | Role-based access within Nexus POS (React web app) or Raptag (React Native mobile). Values: All Roles, CASHIER+, MANAGER+, OWNER, BUYER+, Raptag |
| BRD Section(s) | Chapter 05 section number(s) this screen implements |
| Database Tables | Tables from Ch 07/08 this screen reads (R) or writes (W) |
| State Machine(s) | BRD Module 7 state machines that govern this screen’s behavior |
| Appendix F Services | Code services from Appendix F that power this screen |
| User Roles | Which roles can access: OWNER, MANAGER, CASHIER, BUYER, AUDITOR |
| Offline Capable | Whether the screen functions in DEGRADED/OFFLINE mode (ADR-048). SQLite WASM (sql.js/wa-sqlite + OPFS) provides 2-table fallback in the browser. |
| Route | Suggested URL route path |
| To Find… | Look At… |
|---|
| Business rules for a screen | Ch 05, section listed in BRD Section(s) |
| Database schema for a table | Ch 08, entity specification for the table |
| Service implementation details | Appendix F, service listed in Appendix F Services |
| State transitions | Ch 05, Module 7 (sections 7.1-7.16) |
| Architecture decisions | Ch 02, ADR listed in screen notes |
| Offline behavior patterns | Ch 04, Section L.10A.1 (ADR-048, ADR-052) |
The POS Platform delivers two product experiences from two codebases, governed by ADR-052 (Unified Web App) and ADR-047 (Raptag React Native):
┌─────────────────────────────────────────────────────────────────────────┐
│ NEXUS PLATFORM — 2 PRODUCTS │
│ │
│ ┌──────────────────────────────────────────────┐ ┌────────────────┐ │
│ │ NEXUS POS — UNIFIED WEB APP │ │ SEPARATE APP │ │
│ │ (ADR-052, ADR-048) │ │ (ADR-047) │ │
│ │ │ │ │ │
│ │ React / TypeScript / Vite │ │ ┌────────────┐│ │
│ │ Single SPA in the browser │ │ │NEXUS ││ │
│ │ │ │ │RAPTAG ││ │
│ │ Role-based access: │ │ │(React ││ │
│ │ CASHIER — sales terminal screens │ │ │ Native) ││ │
│ │ MANAGER — reports, inventory, setup │ │ │ ││ │
│ │ OWNER — full config, integrations │ │ │ RFID ││ │
│ │ BUYER — catalog, purchasing │ │ │ counting ││ │
│ │ AUDITOR — counts, audit log │ │ │ ~8 screens ││ │
│ │ │ │ │ + SQLite ││ │
│ │ 107 screens + SQLite WASM fallback │ │ │ offline ││ │
│ │ │ │ └────────────┘│ │
│ └──────────────────────────────────────────────┘ └────────────────┘ │
│ │
│ SHARED: PostgreSQL 16 + Redis 7.x + Socket.io (ADR-049) │
│ STATE: React Query (server) + Zustand (client) (ADR-051) │
│ OFFLINE: 3-state monitor, 2-table SQLite WASM fallback (ADR-048) │
└─────────────────────────────────────────────────────────────────────────┘
| Product | Tech | Deployment | Primary Users | Screens | Offline |
|---|
| Nexus POS | React/TS + Vite | Web browser (any device) | All roles (CASHIER through OWNER) | 107 + 3 cross-cutting | Yes (ADR-048, SQLite WASM) |
| Nexus Raptag | React Native + Expo | Mobile (iOS/Android) | Auditor, Manager | 8 | Yes (ADR-047) |
Key Insight (ADR-052): Nexus POS is a single React web application. All roles access the same app — the difference is what screens are visible based on permissions. A cashier at a register sees transaction screens; a manager sees reports and configuration. Role-based routing controls screen access (CASHIER+, MANAGER+, OWNER, BUYER+, AUDITOR).
| Module | All Roles | CASHIER+ | MANAGER+ | OWNER | BUYER+ | Raptag | Total |
|---|
| 1. Sales | — | 19 | 3 | — | — | — | 22 |
| 2. Customers | 4 | — | 6 | — | — | — | 10 |
| 3. Catalog | 3 | — | 10 | 1 | 4 | — | 18 |
| 4. Inventory | 5 | 1 | 14 | 1 | 2 | — | 23 |
| 5. Setup & Config | 1 | 1 | 2 | 18 | — | — | 22 |
| 6. Integrations | — | — | — | 12 | — | — | 12 |
| Raptag Mobile | — | — | — | — | — | 8 | 8 |
| Cross-Cutting | 3 | — | — | — | — | — | 3 |
| Total | 16 | 21 | 35 | 32 | 6 | 8 | 118 |
Complete master table of all 118 screens. See sections G.4-G.12 for full specifications.
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M01-01 | Sales Terminal / Item Entry | 1.1 | CASHIER+ | CASHIER, MANAGER | Yes |
| SCR-M01-02 | Cart Panel & Line Items | 1.1 | CASHIER+ | CASHIER, MANAGER | Yes |
| SCR-M01-03 | Discount Modal | 1.2 | CASHIER+ | MANAGER, OWNER | Yes |
| SCR-M01-04 | Payment / Checkout | 1.3 | CASHIER+ | CASHIER, MANAGER | Degraded |
| SCR-M01-05 | Layaway Payment | 1.3 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-06 | Affirm Financing Flow | 1.3 | CASHIER+ | CASHIER | No |
| SCR-M01-07 | Parked Sales List | 1.1.1 | CASHIER+ | CASHIER, MANAGER | Yes |
| SCR-M01-08 | Gift Card Operations | 1.5 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-09 | Receipt Print / Reprint | 1.4 | CASHIER+ | CASHIER, MANAGER | Yes |
| SCR-M01-10 | Cash Drawer Management | 1.12 | CASHIER+ | CASHIER, MANAGER | Yes |
| SCR-M01-11 | Price Check Mode | 1.13 | CASHIER+ | CASHIER | Yes |
| SCR-M01-12 | Coupon Entry | 1.14 | CASHIER+ | CASHIER | No |
| SCR-M01-13 | Loyalty Display | 1.15 | CASHIER+ | CASHIER | No |
| SCR-M01-14 | Return Processing | 1.4 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-15 | Exchange Processing | 1.4 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-16 | Special Order Create | 1.6 | CASHIER+ | MANAGER | No |
| SCR-M01-17 | Multi-Store Inventory Lookup | 1.7 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-18 | Hold for Pickup (BOPIS) | 1.11 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M01-19 | Ship-to-Customer | 1.7 | CASHIER+ | MANAGER | No |
| SCR-M01-20 | Sales Reports Dashboard | 1.8, 1.19 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M01-21 | Commission Management | 1.8 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M01-22 | Manager Discrepancy Review | 1.16 | MANAGER+ | MANAGER, OWNER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M02-01 | Customer List / Directory | 2.1 | All Roles | CASHIER, MANAGER | No |
| SCR-M02-02 | Customer Profile / Detail | 2.1 | All Roles | CASHIER, MANAGER | No |
| SCR-M02-03 | Customer Create / Edit | 2.1 | All Roles | CASHIER, MANAGER | No |
| SCR-M02-04 | Customer Group / Tier Mgmt | 2.2 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M02-05 | Customer Notes & Preferences | 2.3 | All Roles | CASHIER, MANAGER | No |
| SCR-M02-06 | Communication Preferences | 2.4 | MANAGER+ | MANAGER | No |
| SCR-M02-07 | Customer Merge / Dedup | 2.5 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M02-08 | Customer Deletion / Anonymize | 2.5 | MANAGER+ | OWNER | No |
| SCR-M02-09 | Loyalty Admin Dashboard | 2.6, 5.17 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M02-10 | Communication Log | 2.4 | MANAGER+ | MANAGER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M03-01 | Product List / Search | 3.1 | All Roles | ALL | Yes |
| SCR-M03-02 | Product Detail / Edit | 3.1 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-03 | Variant Matrix Editor | 3.1 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-04 | Pricing Engine / Price Books | 3.3 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M03-05 | Promotions Setup | 3.3 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M03-06 | Markdown Workflow | 3.3 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M03-07 | Coupon Management | 3.3 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M03-08 | Category Hierarchy | 3.5 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-09 | Tags & Collections | 3.5 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-10 | Seasons / Buying Calendar | 3.5 | BUYER+ | BUYER | No |
| SCR-M03-11 | Barcode Management | 3.4 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-12 | Multi-Channel Allocation | 3.6 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M03-13 | Vendor Management | 3.8 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M03-14 | Label Printing | 3.10 | All Roles | CASHIER, MANAGER | No |
| SCR-M03-15 | Product Media Manager | 3.11 | BUYER+ | BUYER | No |
| SCR-M03-16 | Custom Fields Config | 3.12, 5.12 | OWNER | OWNER | No |
| SCR-M03-17 | Product Search & Discovery | 3.9 | All Roles | ALL | Yes |
| SCR-M03-18 | Product Analytics | 3.14 | MANAGER+ | MANAGER, OWNER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M04-01 | Inventory Dashboard | 4.17 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M04-02 | Inventory List (per location) | 4.1 | All Roles | ALL | No |
| SCR-M04-03 | Low Stock Alerts | 4.16 | MANAGER+ | MANAGER, BUYER | No |
| SCR-M04-04 | PO Create / Edit | 4.3 | BUYER+ | BUYER, MANAGER | No |
| SCR-M04-05 | PO Approval / Track | 4.3 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M04-06 | PO Templates | 4.3 | BUYER+ | BUYER | No |
| SCR-M04-07 | Receiving & Inspection | 4.4 | All Roles | CASHIER, MANAGER | No |
| SCR-M04-08 | Receiving Variance | 4.4 | All Roles | MANAGER | No |
| SCR-M04-09 | Stock Count Session | 4.6 | All Roles | AUDITOR, MANAGER | No |
| SCR-M04-10 | Count Freeze Manager | 4.6 | MANAGER+ | MANAGER | No |
| SCR-M04-11 | Scanner Count Entry | 4.6 | CASHIER+ | AUDITOR, CASHIER | No |
| SCR-M04-12 | RFID Count Manager | 4.6.8 | MANAGER+ | MANAGER | No |
| SCR-M04-13 | Count Results Review | 4.6 | MANAGER+ | MANAGER, AUDITOR | No |
| SCR-M04-14 | Count Approval | 4.6 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M04-15 | Adjustment Request | 4.7 | All Roles | CASHIER, MANAGER | No |
| SCR-M04-16 | Adjustment Approval | 4.7 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M04-17 | Transfer Create / Track | 4.8 | MANAGER+ | MANAGER | No |
| SCR-M04-18 | Reorder Configuration | 4.5 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M04-19 | Reason Codes Management | 4.7 | OWNER | OWNER | No |
| SCR-M04-20 | Serial Number Tracking | 4.10 | All Roles | MANAGER | No |
| SCR-M04-21 | Vendor RMA | 4.9 | MANAGER+ | BUYER, MANAGER | No |
| SCR-M04-22 | Inventory Reports | 4.17 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M04-23 | Reservation Management | 4.13 | MANAGER+ | MANAGER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M05-01 | Onboarding Wizard (13 steps) | 5.20 | OWNER | OWNER | No |
| SCR-M05-02 | System Settings / Branding | 5.2 | OWNER | OWNER | No |
| SCR-M05-03 | Location Management | 5.4 | OWNER | OWNER | No |
| SCR-M05-04 | User Management | 5.5 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M05-05 | Role & Permission Config | 5.5 | OWNER | OWNER | No |
| SCR-M05-06 | Login / Authentication | 5.5 | All Roles | ALL | Yes |
| SCR-M05-07 | Clock-In / Clock-Out | 5.6 | CASHIER+ | CASHIER, MANAGER | No |
| SCR-M05-08 | Register Management | 5.7 | OWNER | MANAGER, OWNER | No |
| SCR-M05-09 | Register Profiles | 5.7 | OWNER | MANAGER, OWNER | No |
| SCR-M05-10 | Register Retirement | 5.7 | OWNER | OWNER | No |
| SCR-M05-11 | Payment Terminal Config | 5.11 | OWNER | OWNER | No |
| SCR-M05-12 | Payment Methods Setup | 5.11 | OWNER | OWNER | No |
| SCR-M05-13 | Tax Jurisdiction Config | 5.9 | OWNER | OWNER | No |
| SCR-M05-14 | Tax Exemption Management | 5.9 | MANAGER+ | MANAGER, OWNER | No |
| SCR-M05-15 | UOM Setup | 5.10 | OWNER | OWNER | No |
| SCR-M05-16 | Approval Workflows | 5.13 | OWNER | OWNER | No |
| SCR-M05-17 | Printer Configuration | 5.8 | OWNER | MANAGER, OWNER | No |
| SCR-M05-18 | Receipt Builder | 5.14 | OWNER | OWNER | No |
| SCR-M05-19 | Email Config & Templates | 5.15 | OWNER | OWNER | No |
| SCR-M05-20 | RFID Configuration | 5.16 | OWNER | OWNER | No |
| SCR-M05-21 | Audit Log Viewer | 5.18 | OWNER | OWNER | No |
| SCR-M05-22 | Business Rules (YAML Editor) | 5.19 | OWNER | OWNER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-M06-01 | Integration Hub Dashboard | 6.11 | OWNER | MANAGER, OWNER | No |
| SCR-M06-02 | Shopify Setup & Connection | 6.3 | OWNER | OWNER | No |
| SCR-M06-03 | Shopify Inventory Sync Config | 6.3, 6.7 | OWNER | MANAGER, OWNER | No |
| SCR-M06-04 | Shopify Order Fulfillment | 6.3 | OWNER | MANAGER | No |
| SCR-M06-05 | Amazon Setup & Connection | 6.4 | OWNER | OWNER | No |
| SCR-M06-06 | Amazon Catalog / Listings | 6.4 | OWNER | MANAGER | No |
| SCR-M06-07 | Google Merchant Setup | 6.5 | OWNER | OWNER | No |
| SCR-M06-08 | Google Validation Dashboard | 6.5 | OWNER | MANAGER | No |
| SCR-M06-09 | Cross-Platform Validation | 6.6 | OWNER | MANAGER, OWNER | No |
| SCR-M06-10 | Inventory Sync Dashboard | 6.7 | OWNER | MANAGER | No |
| SCR-M06-11 | Integration Health Monitor | 6.11 | OWNER | MANAGER, OWNER | No |
| SCR-M06-12 | Error DLQ Management | 6.2 | OWNER | MANAGER, OWNER | No |
| ID | Screen | BRD | Product | Roles | Offline |
|---|
| SCR-R01 | Login | 5.5 | Raptag | ALL | Yes |
| SCR-R02 | Home Dashboard | 4.6.8 | Raptag | AUDITOR, MANAGER | Yes |
| SCR-R03 | Join / Start Session | 4.6.8 | Raptag | AUDITOR, MANAGER | No |
| SCR-R04 | Scanning Interface | 4.6.8 | Raptag | AUDITOR | Yes |
| SCR-R05 | Section Assignment & Progress | 4.6.8 | Raptag | AUDITOR | Yes |
| SCR-R06 | Session Summary | 4.6.8 | Raptag | AUDITOR, MANAGER | Yes |
| SCR-R07 | Chunked Upload / Sync | 4.6.8 | Raptag | AUDITOR | Degraded |
| SCR-R08 | Device Pairing | 5.16 | Raptag | MANAGER | No |
| ID | Screen | Ref | Product | Roles | Offline |
|---|
| SCR-X01 | Login / Authentication | 5.5, ADR-004 | All Roles | ALL | Yes |
| SCR-X02 | Error Pages (403/404/500) | — | All Roles | ALL | Yes |
| SCR-X03 | Offline Mode Indicator | 1.16, ADR-048 | All Roles | ALL | Yes |
BRD Sections: 1.1-1.20 | Appendix F: §F.4 (37 services) | Pattern: Full CQRS + Event Sourcing
Cross-Reference: See Ch 05, Sections 1.1-1.20 for business rules. See Ch 08, Domain 4 (Sales & Payments) for table schemas. See Appendix F, §F.4 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M01-01 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.1 |
| Database Tables | orders (R/W), order_items (R/W), products (R), variants (R), inventory_levels (R), customers (R) |
| State Machine(s) | 7.1 Order States, 7.2 Parked Sale States |
| Appendix F Services | sale.cart.command.service, sale.cart.query.service, sale.park.command.service, sale.park.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (degraded – cached products from product_cache only, no real-time price updates, stale pricing warning displayed) |
| Route | /pos/sales/terminal |
The Sales Terminal is the primary point-of-sale screen where staff ring up customer purchases. It supports barcode scanning, manual SKU entry, and bulk RFID tag lookup (max 50 tags per request). Staff can toggle between Sale, Return, and Exchange modes, attach customers for loyalty/pricing, and park sales for later retrieval (max 5 per terminal, 4-hour TTL).
| Element | Type | Description | Business Rule |
|---|
| Barcode/SKU Input | Input | Scan barcode or type SKU to add items; auto-focuses after each entry | BRD 1.1: GET /product/{sku} or POST /products/bulk-lookup (max 50 tags) |
| Mode Toggle | Button Group | Switch between Sale / Return / Exchange modes | BRD 1.1: Mode determines stock validation behavior |
| Cart Panel | Panel | Displays current line items with qty, price, discount, line total | BRD 1.1: Real-time subtotal calculation |
| Customer Attach | Button + Search | Search/attach customer by name, phone, email, or loyalty number | BRD 1.1: Recalculates prices if Price Tier applies; recalculates tax if exempt |
| Running Totals | Panel | Subtotal, discounts, tax breakdown (State/County/City), grand total | BRD 1.2.1: Strict discount calculation order (7 steps) |
| Stock Warning | Badge/Alert | Warns when stock is low or zero for sale items | BRD 1.1: Check Stock > 0 before adding to cart |
| Park Sale | Button | Serialize cart state and release locks; max 5 per terminal | BRD 1.1.1: 4-hour TTL, soft-reserve inventory |
| Retrieve Sale | Button | List and restore parked sales for this terminal | BRD 1.1.1: Parked items visible to other terminals with warning |
| Upsell Alert | Toast/Banner | Triggered by promo engine when cart meets criteria | BRD 1.1: “Buy 1 more for 10% off” style suggestions |
| Proceed to Payment | Button | Transition order from DRAFT to PENDING state | BRD 1.3: Navigates to Payment/Checkout |
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEXUS POS [Sale ▼] [Price Check] [Park Sale] [Retrieve] [User] [?] │
├────────────────────┬────────────────────────────────┬───────────────────────┤
│ ITEM ENTRY │ CART │ CUSTOMER & TOTALS │
│ │ │ │
│ ┌──────────────┐ │ # SKU Name Qty $ │ ┌─────────────────┐ │
│ │ Scan / SKU │ │ 1 NXJ-1001 Jacket 1 89 │ │ [Attach Cust.] │ │
│ └──────────────┘ │ 2 NXJ-2045 Tee 2 50 │ │ │ │
│ │ 3 NXJ-3012 Pants 1 65 │ │ Jane Doe │ │
│ ┌──────────────┐ │ │ │ Gold Tier │ │
│ │ Search Prod │ │ │ │ 450 pts │ │
│ │ ─────────── │ │ │ │ Tax Exempt: No │ │
│ │ Recent Items │ │ │ └─────────────────┘ │
│ │ NXJ-1001 │ │ │ │
│ │ NXJ-2045 │ │ │ Subtotal: $254.00 │
│ │ NXJ-3012 │ │ │ Discount: - $25.40 │
│ └──────────────┘ │ │ State Tax: + $9.83 │
│ │ │ Local Tax: + $2.29 │
│ ⚠ Low Stock: │ ├────────────────────────────┤ ───────────────────── │
│ NXJ-3012 (2 left) │ │ [Remove] [Discount] [Qty] │ TOTAL: $240.72 │
│ │ │ │
│ [Upsell: Buy 1 │ │ ┌─────────────────┐ │
│ more Tee, 10% │ │ │ PAY ($240.72)│ │
│ off all Tees] │ │ └─────────────────┘ │
└────────────────────┴────────────────────────────────┴───────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Pay” | SCR-M01-04 Payment / Checkout | CASHIER+ |
| Click “Park Sale” | Stays on terminal (cart cleared, sale serialized) | CASHIER+ |
| Click “Retrieve” | SCR-M01-07 Parked Sales List | CASHIER+ |
| Click “Price Check” | SCR-M01-11 Price Check Mode | CASHIER+ |
| Click line item discount | SCR-M01-03 Discount Modal | CASHIER+ (Manager PIN for override) |
| Click “Attach Customer” | SCR-M02-01 Customer List (search overlay) | CASHIER+ |
| Toggle to Return mode | SCR-M01-14 Return Processing | CASHIER+ |
| Toggle to Exchange mode | SCR-M01-15 Exchange Processing | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-02 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.1 |
| Database Tables | orders (R/W), order_items (R/W), variants (R), products (R), pricing_rules (R) |
| State Machine(s) | 7.1 Order States |
| Appendix F Services | sale.cart.command.service, sale.cart.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (degraded – uses product_cache prices, stale pricing warning) |
| Route | /pos/sales/terminal (embedded panel within SCR-M01-01) |
The Cart Panel is the central line-item display embedded within the Sales Terminal. It shows all items in the current transaction with quantity controls, per-line discount indicators, tax amounts, and line totals. Staff can modify quantities, remove items, apply line discounts, and see real-time running totals as the cart changes.
| Element | Type | Description | Business Rule |
|---|
| Line Item Row | Table Row | SKU, product name, quantity, unit price, discount, tax, line total | BRD 1.1: Snapshot product data at time of add |
| Quantity Stepper | Input | Increment/decrement quantity; validates against stock | BRD 1.1: Stock > 0 validation for sale mode |
| Remove Item | Button | Remove line item from cart | BRD 1.1: Releases any soft-reserve |
| Line Discount Indicator | Badge | Shows applied discount type and percentage | BRD 1.2.1: Discount calculation order applies |
| Non-Discountable Flag | Icon | Indicates items excluded from global discounts | BRD 1.2.1: Gift cards, deposits, is_discountable=false |
| Running Subtotal | Text | Live-calculated subtotal across all lines | BRD 1.1: Updated on every cart change |
| Serial Number Badge | Badge | Shows serial number for tracked items | BRD 1.10: Serial required flag on product |
| Action | Navigates To | Requires Role |
|---|
| Click line item discount button | SCR-M01-03 Discount Modal | CASHIER+ |
| Click remove item | Stays on cart (item removed) | CASHIER+ |
| Adjust quantity to 0 | Stays on cart (item removed) | CASHIER+ |
| Click serial number prompt | Serial entry modal (inline) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-03 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.2 |
| Database Tables | orders (R/W), order_items (R/W), pricing_rules (R) |
| State Machine(s) | – |
| Appendix F Services | sale.discount.command.service, sale.promotion.engine.service, sale.price-override.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (degraded – promotions may be stale from product_cache) |
| Route | /pos/sales/terminal (modal overlay) |
The Discount Modal allows staff to apply line-item discounts, global order discounts, or manual price overrides. It enforces the strict 7-step discount calculation order: Price Tier, Line Discounts, Auto Promos, Global %, Coupons, Tax, Loyalty Redemption. Manual price overrides require a manager PIN and a mandatory reason code.
| Element | Type | Description | Business Rule |
|---|
| Discount Type Selector | Radio Group | Choose: percentage off, fixed amount off, or price override | BRD 1.2: Three discount application types |
| Percentage Input | Input | Enter discount percentage (1-100%) | BRD 1.2: Applied to line item or entire order |
| Fixed Amount Input | Input | Enter dollar amount to deduct | BRD 1.2: Cannot exceed line/order total |
| Reason Code Dropdown | Select | Required for all discounts: Damaged, Employee, Price Match, Manager Discretion | BRD 1.2: Reason code mandatory for audit |
| Manager PIN Prompt | Input | PIN entry for price overrides and discounts exceeding threshold | BRD 1.2: Manager Auth required for overrides |
| Discount Preview | Panel | Shows before/after price comparison and savings amount | BRD 1.2.1: Calculation order preview |
| Non-Discountable Warning | Alert | Blocks discount on gift cards, deposits, flagged items | BRD 1.2.1: is_discountable = false exclusion |
| Apply / Cancel | Button Pair | Confirm or cancel the discount | BRD 1.2: Discount added to order |
| Action | Navigates To | Requires Role |
|---|
| Apply discount | Returns to SCR-M01-01 Sales Terminal (discount applied) | CASHIER+ |
| Apply price override | Returns to SCR-M01-01 (requires MANAGER PIN) | MANAGER+ |
| Cancel | Returns to SCR-M01-01 (no change) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-04 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.3, 1.18 |
| Database Tables | orders (R/W), order_items (R), payments (W), payment_attempts (W), gift_cards (R/W), gift_card_transactions (W), store_credits (R/W), customers (R/W), loyalty_accounts (R/W), cash_movements (W) |
| State Machine(s) | 7.1 Order States (PENDING -> PAID -> COMPLETED) |
| Appendix F Services | sale.payment.command.service, sale.payment.card.service, sale.payment.cash.service, sale.payment.giftcard.service, sale.payment.storecredit.service, sale.payment.affirm.service, sale.finalize.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Partial (cash only – card payments, gift cards, store credit, and Affirm blocked offline per BRD 1.16.2) |
| Route | /pos/sales/checkout |
The Payment/Checkout screen processes split-tender payments across multiple methods: cash, credit/debit card (SAQ-A semi-integrated), gift card, store credit (on-account), layaway deposit, and Affirm third-party financing. It calculates change due for cash, manages remaining balance across multiple tenders, and finalizes the order once fully paid.
| Element | Type | Description | Business Rule |
|---|
| Amount Due | Panel | Displays remaining balance to be paid | BRD 1.3: Decrements with each tender applied |
| Cash Tender | Button + Input | Enter amount received; auto-calculates change due | BRD 1.3: Change = Tendered - Remaining |
| Card Payment | Button | Initiates SAQ-A terminal flow; displays “Insert/Tap Card” | BRD 1.18: Card data never touches system; token + auth code stored |
| Gift Card | Button + Input | Scan/enter gift card number; shows balance; apply partial or full | BRD 1.5: Validates balance & expiry; partial allowed |
| Store Credit (On-Account) | Button | Check credit limit: Credit Limit - (Debt + Pending Layaways + Cart) | BRD 1.3.3: Block if exceeds available credit |
| Layaway | Button | Select layaway mode; validate minimum deposit percentage | BRD 1.3.2: Status -> LAYAWAY |
| Affirm Financing | Button | Create Affirm checkout session; display QR code for customer | BRD 1.3: Webhook: loan approved + charge_id |
| Tender List | Table | Shows all applied payment methods with amounts | BRD 1.3: Multiple tenders allowed |
| Change Due Display | Panel | Shows change to return for cash overpayment | BRD 1.3: “Collect: $X.XX” or “Change: $X.XX” |
| Finalize Order | Button | Write order record, decrement inventory, award loyalty, record commission | BRD 1.3: POST /orders/finalize |
| Receipt Options | Button Group | Select receipt format: Thermal, A4 Invoice, Gift Receipt, Email | BRD 1.4: Template selection |
┌─────────────────────────────────────────────────────────────────────────────┐
│ PAYMENT [Back] [Cancel] │
├─────────────────────────────────┬───────────────────────────────────────────┤
│ ORDER SUMMARY │ PAYMENT METHODS │
│ │ │
│ Items: 3 │ ┌──────────┐ ┌──────────┐ │
│ Subtotal: $254.00 │ │ CASH │ │ CARD │ │
│ Discount: - $25.40 │ └──────────┘ └──────────┘ │
│ Tax: + $12.12 │ ┌──────────┐ ┌──────────┐ │
│ ───────────────────── │ │ GIFT CARD│ │ STORE CR │ │
│ TOTAL: $240.72 │ └──────────┘ └──────────┘ │
│ │ ┌──────────┐ ┌──────────┐ │
│ TENDERS APPLIED: │ │ LAYAWAY │ │ AFFIRM │ │
│ ┌────────────────────────┐ │ └──────────┘ └──────────┘ │
│ │ Visa ****4521 $200.00 │ │ │
│ │ [Remove] │ │ CASH ENTRY: │
│ └────────────────────────┘ │ ┌────────────────────────────┐ │
│ │ │ Amount Received: $50.00 │ │
│ REMAINING: $40.72 │ └────────────────────────────┘ │
│ │ │
│ │ Change Due: $9.28 │
│ │ │
│ │ ┌────────────────────────────────────┐ │
│ │ │ FINALIZE & PRINT │ │
│ │ └────────────────────────────────────┘ │
│ │ [Thermal] [A4 Invoice] [Gift] [Email] │
└─────────────────────────────────┴───────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Finalize order | SCR-M01-09 Receipt Print / Reprint | CASHIER+ |
| Select Layaway | SCR-M01-05 Layaway Payment | CASHIER+ |
| Select Affirm | SCR-M01-06 Affirm Financing Flow | CASHIER+ |
| Click Back | SCR-M01-01 Sales Terminal (cart preserved) | CASHIER+ |
| Cancel transaction | SCR-M01-01 Sales Terminal (cart cleared) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-05 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.3, 1.3.2 |
| Database Tables | orders (R/W), payments (W), customers (R), inventory_levels (R/W) |
| State Machine(s) | 7.4 Layaway States (DEPOSIT_PAID -> RESERVED -> PAID_IN_FULL -> COMPLETED) |
| Appendix F Services | sale.layaway.command.service, sale.payment.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires real-time balance verification and inventory reservation) |
| Route | /pos/sales/layaway |
The Layaway Payment screen handles creating new layaways (with minimum deposit validation) and processing subsequent payments on existing layaways. When the final payment is received, inventory is released from reserved to sold status. Cancelled layaways trigger deposit refunds according to the configured policy.
| Element | Type | Description | Business Rule |
|---|
| Customer Display | Panel | Shows attached customer (required for layaway) | BRD 1.3.2: Customer attachment mandatory |
| Minimum Deposit Calculator | Panel | Shows minimum deposit percentage and dollar amount | BRD 1.3.2: Min deposit % configurable; default 50% |
| Deposit Amount Input | Input | Enter deposit amount; validates against minimum | BRD 1.3.2: Must meet or exceed minimum deposit |
| Payment History | Table | Shows all prior payments on this layaway with dates | BRD 1.3.2: RESERVED state allows additional payments |
| Remaining Balance | Panel | Calculated: Total - Sum(all payments) | BRD 1.3.2: Final payment transitions to PAID_IN_FULL |
| Payment Deadline | Date Display | Shows configured payment deadline | BRD 1.3.2: FORFEITED if deadline missed |
| Cancel Layaway | Button | Cancel with refund processing | BRD 1.3.2: CANCELLED_REFUND state; refund deposit |
| Complete Layaway | Button | Process final payment and release inventory | BRD 1.3.2: COMPLETED state; items released |
| Action | Navigates To | Requires Role |
|---|
| Process deposit | SCR-M01-04 Payment / Checkout (deposit payment) | CASHIER+ |
| Complete layaway (final payment) | SCR-M01-09 Receipt Print / Reprint | CASHIER+ |
| Cancel layaway | Confirmation modal -> SCR-M01-04 (refund) | MANAGER+ |
| Back to terminal | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-06 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.3 |
| Database Tables | orders (R/W), payment_attempts (W) |
| State Machine(s) | 7.1 Order States |
| Appendix F Services | sale.payment.affirm.service, sale.finalize.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires active network connection for Affirm API and webhook) |
| Route | /pos/sales/checkout/affirm |
The Affirm Financing Flow presents a QR code or redirect URL for customers to complete a third-party financing application on their personal device. The screen waits for an Affirm webhook confirming loan approval, then stores the charge_id and loan_id. The full purchase amount is received from Affirm; the customer pays Affirm directly over time.
| Element | Type | Description | Business Rule |
|---|
| Order Summary | Panel | Shows items, total, and financing amount | BRD 1.3: Full amount financed through Affirm |
| QR Code Display | Image | Generated QR code for customer to scan and complete Affirm application | BRD 1.3: POST /payments/affirm/initiate |
| Status Indicator | Badge | Shows: Waiting for Customer / Application Submitted / Approved / Declined | BRD 1.3: Webhook-driven status updates |
| Timer | Display | Shows elapsed waiting time; timeout at configurable threshold | BRD 1.3: Staff can cancel if customer abandons |
| Approval Confirmation | Alert | Shows Affirm charge_id and approval status | BRD 1.3: charge_id, loan_id, status stored |
| Cancel Affirm | Button | Cancel financing attempt and return to payment selection | BRD 1.3: Tender list updated |
| Action | Navigates To | Requires Role |
|---|
| Affirm approved | SCR-M01-04 Payment / Checkout (Affirm tender applied) | CASHIER+ |
| Affirm declined | SCR-M01-04 Payment / Checkout (try another method) | CASHIER+ |
| Cancel | SCR-M01-04 Payment / Checkout | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-07 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.1, 1.1.1 |
| Database Tables | orders (R/W), order_items (R) |
| State Machine(s) | 7.2 Parked Sale States (ACTIVE -> PARKED -> ACTIVE or EXPIRED) |
| Appendix F Services | sale.park.command.service, sale.park.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (parked sales stored locally; retrieve from local state) |
| Route | /pos/sales/parked |
The Parked Sales List displays all currently parked (held) sales for the active terminal or location. Each entry shows the customer name (if attached), item count, total, and time remaining before the 4-hour TTL expires. Staff can retrieve any parked sale to resume checkout or let expired sales auto-release their soft-reserved inventory.
| Element | Type | Description | Business Rule |
|---|
| Parked Sales Table | Table | Lists all parked sales: customer, item count, subtotal, parked time | BRD 1.1.1: Max 5 parked sales per terminal |
| Time Remaining | Badge | Countdown showing TTL remaining per parked sale | BRD 1.1.1: 4-hour TTL; expired sales auto-release inventory |
| Expired Indicator | Badge | Red badge for sales that have exceeded TTL | BRD 1.1.1: EXPIRED state; inventory released |
| Retrieve Button | Button | Restore parked sale to active cart | BRD 1.1.1: PARKED -> ACTIVE transition |
| Delete Expired | Button | Remove expired parked sales from list | BRD 1.1.1: Clean up expired entries |
| Soft-Reserve Warning | Alert | Shows if parked items are being viewed/held by another terminal | BRD 1.1: Soft-reserved while parked; visible with warning |
| Action | Navigates To | Requires Role |
|---|
| Retrieve parked sale | SCR-M01-01 Sales Terminal (cart restored) | CASHIER+ |
| Delete expired sale | Stays on list (sale removed) | CASHIER+ |
| Back | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-08 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.5 |
| Database Tables | gift_cards (R/W), gift_card_transactions (R/W), orders (R/W), order_items (W) |
| State Machine(s) | 7.3 Gift Card States (INACTIVE -> ACTIVE -> DEPLETED/EXPIRED/CASHED_OUT) |
| Appendix F Services | sale.giftcard.command.service, sale.giftcard.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (gift card activation, reload, balance check, and cash-out all blocked offline per BRD 1.16.2) |
| Route | /pos/sales/gift-cards |
The Gift Card Operations screen handles all gift card lifecycle actions: selling/activating new cards, checking balances, reloading existing cards, and processing cash-outs where jurisdiction rules permit (e.g., California law requires cash-out for balances under $10). The screen enforces jurisdiction-specific compliance rules based on the store location.
| Element | Type | Description | Business Rule |
|---|
| Card Number Input | Input | Scan or manually enter gift card number | BRD 1.5: Unique card number lookup |
| Action Selector | Tab Group | Sell New / Check Balance / Reload / Cash Out | BRD 1.5: Four distinct operations |
| Load Amount Input | Input | Dollar amount for new card or reload | BRD 1.5: POST /giftcards/activate |
| Balance Display | Panel | Current balance, expiry date, last activity | BRD 1.5: GET /giftcards/{number}/balance |
| Cash-Out Eligibility | Alert | Shows whether balance qualifies for cash-out under jurisdiction rules | BRD 1.5.2: California $10 threshold; Virginia no cash-out |
| Jurisdiction Rules | Info Panel | Displays applicable expiry, fee, and cash-out rules for store location | BRD 1.5.2: Strictest-rule-wins default |
| Transaction History | Table | Shows activation, reloads, redemptions, and cash-outs | BRD 1.5: Full audit trail |
| Add to Cart | Button | Adds gift card sale or reload as a cart line item | BRD 1.5: Non-discountable item |
| Action | Navigates To | Requires Role |
|---|
| Sell new gift card (add to cart) | SCR-M01-01 Sales Terminal (gift card in cart) | CASHIER+ |
| Reload existing card (add to cart) | SCR-M01-01 Sales Terminal (reload in cart) | CASHIER+ |
| Process cash-out | Cash dispensed from drawer | CASHIER+ |
| Back | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-09 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.4 |
| Database Tables | orders (R), order_items (R), payments (R), customers (R) |
| State Machine(s) | – |
| Appendix F Services | sale.receipt.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Partial (can reprint from local cache for recently completed sales; email requires network) |
| Route | /pos/sales/receipt |
The Receipt Print/Reprint screen generates and delivers receipts in multiple formats. After completing a sale, it auto-shows with template selection. Staff can also access this screen from Sales History to reprint or email receipts for past transactions. Receipts include a scannable barcode for return/exchange validation.
| Element | Type | Description | Business Rule |
|---|
| Receipt Preview | Panel | Full receipt preview with line items, taxes, payments, barcode | BRD 1.4: Receipt data for verification |
| Template Selector | Button Group | Thermal (standard), A4 Invoice (detailed), Gift Receipt (no prices) | BRD 1.4: Three template formats |
| Email Input | Input | Override email address for sending digital receipt | BRD 1.4: POST /orders/{id}/email-receipt |
| Print Button | Button | Send to configured receipt printer | BRD 1.4: Thermal printer integration |
| Receipt Barcode | Image | Scannable barcode encoding order ID for return validation | BRD 1.4: POST /receipts/validate for returns |
| Offline Watermark | Badge | Shows “OFFLINE” watermark on receipts printed during offline mode | BRD 1.16: Offline receipt indicator |
| Action | Navigates To | Requires Role |
|---|
| Print receipt | Stays (prints to thermal/A4 printer) | CASHIER+ |
| Email receipt | Stays (sends email) | CASHIER+ |
| Done / New Sale | SCR-M01-01 Sales Terminal (fresh cart) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-10 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.12 |
| Database Tables | cash_drawers (R/W), cash_movements (R/W), cash_counts (R/W), cash_drops (R/W), cash_pickups (R), shifts (R/W) |
| State Machine(s) | 7.9 Cash Drawer States (CLOSED -> OPENING -> OPEN -> COUNTING -> BALANCED -> CLOSED) |
| Appendix F Services | sale.cashdrawer.command.service, sale.cashdrawer.count.service, sale.cashdrawer.pickup.service, sale.shift.command.service |
| User Roles | CASHIER (X-Report), MANAGER (Open/Close/Variance approval) |
| Offline Capable | Yes (cash operations are local; Z-Report synced on reconnection) |
| Route | /pos/cash-drawer |
The Cash Drawer Management screen handles the full cash accountability lifecycle: opening with a float, mid-shift X-Reports, cash drops to safe, and end-of-shift Z-Report closure with blind denomination counting. It calculates expected cash based on all cash transactions and flags variances for manager review when outside tolerance.
| Element | Type | Description | Business Rule |
|---|
| Drawer Status | Badge | Shows: Closed / Open / Counting / Variance Detected | BRD 1.12.1: Cash Drawer State Machine |
| Opening Float Input | Input | Enter starting cash amount when opening drawer | BRD 1.12: POST /cash-drawer/open |
| Denomination Grid | Input Grid | Count each denomination: pennies through hundreds, rolled coins | BRD 1.12: Blind count (expected not shown) |
| X-Report Button | Button | Generate mid-shift cash snapshot without closing drawer | BRD 1.12.2: Unlimited per shift; does not close drawer |
| Z-Report Button | Button | Generate end-of-shift report; closes drawer and resets counters | BRD 1.12.2: Once per shift; closes drawer |
| Variance Display | Panel | Shows: Expected, Counted, Variance (+/-) | BRD 1.12: Variance = Counted - Expected |
| Manager Approval | Input | Manager PIN + reason code for out-of-tolerance variance | BRD 1.12: MANAGER_REVIEW state |
| Cash Drop | Button | Record cash drop to safe with amount | BRD 1.12: Cash drops reduce drawer balance |
| Paid In / Paid Out | Button Pair | Record non-sale cash movements (petty cash, vendor payments) | BRD 1.12: Logged in cash_movements |
| Cash Movement Log | Table | Chronological list of all cash in/out events for current shift | BRD 1.12.3: Immutable audit trail |
┌─────────────────────────────────────────────────────────────────────────────┐
│ CASH DRAWER MANAGEMENT Drawer: OPEN [X-Report] [?] │
├─────────────────────────────────────┬───────────────────────────────────────┤
│ DENOMINATION COUNT (BLIND) │ SHIFT SUMMARY │
│ │ │
│ COINS Qty Amount │ Opening Float: $200.00 │
│ Pennies ($0.01) [ ] $0.00 │ Cash Sales: $1,245.00 │
│ Nickels ($0.05) [ ] $0.00 │ Cash Refunds: - $85.00 │
│ Dimes ($0.10) [ ] $0.00 │ Paid Out: - $50.00 │
│ Quarters($0.25) [ ] $0.00 │ Cash Drops: - $500.00 │
│ Half $ ($0.50) [ ] $0.00 │ ────────────────────────────── │
│ Dollar ($1.00) [ ] $0.00 │ Expected Cash: $810.00 │
│ │ Counted Cash: $805.00 │
│ BILLS Qty Amount │ ────────────────────────────── │
│ $1 [ ] $0.00 │ VARIANCE: -$5.00 ⚠ │
│ $5 [ ] $0.00 │ │
│ $10 [ ] $0.00 │ ┌──────────────────────────────┐ │
│ $20 [ ] $0.00 │ │ Manager PIN: [____] │ │
│ $50 [ ] $0.00 │ │ Reason: [Counting error ▼] │ │
│ $100 [ ] $0.00 │ └──────────────────────────────┘ │
│ Rolled Coins [____] $0.00 │ │
│ │ Transactions: 47 │
│ COUNTED TOTAL: $805.00 │ Shift Duration: 8h 15m │
│ │ │
│ [Paid In] [Paid Out] [Cash Drop] │ [Close Drawer & Print Z-Report] │
└─────────────────────────────────────┴───────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Open drawer (enter float) | Stays (drawer status -> OPEN) | MANAGER+ |
| Print X-Report | Stays (report generated, drawer stays open) | CASHIER+ |
| Close drawer (Z-Report) | Prints Z-Report; drawer status -> CLOSED | CASHIER+ (MANAGER for variance approval) |
| Cash drop | Stays (cash_drops record created) | CASHIER+ |
| Paid In / Paid Out | Stays (cash_movements record created) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-11 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.13 |
| Database Tables | products (R), variants (R), pricing_rules (R), inventory_levels (R) |
| State Machine(s) | – |
| Appendix F Services | sale.price-check.query.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (degraded – uses product_cache; stale pricing warning shown) |
| Route | /pos/sales/price-check |
Price Check Mode allows staff to quickly scan an item and display its current selling price, stock level, and any active promotions without adding the item to the cart. This is used for customer inquiries (“How much is this?”). The display auto-returns to the normal sale mode after a configurable timeout or keypress.
| Element | Type | Description | Business Rule |
|---|
| Barcode Input | Input | Scan or enter item barcode/SKU | BRD 1.13: GET /products/{sku} |
| Large Price Display | Panel | Product name, SKU, and price displayed in large font | BRD 1.13: Customer-visible price display |
| Stock Level | Badge | Current stock count at this location | BRD 1.13: Show stock level |
| Promotion Alert | Banner | Shows active sale/promotion: “Was $50, Now $39.99” | BRD 1.13: Active promotion display |
| Auto-Timeout | Timer | Returns to sale mode after configurable timeout | BRD 1.13: Press any key or timeout |
| Stale Price Warning | Alert | Warning when operating from cached prices (offline) | BRD 1.16: product_cache may be stale |
| Action | Navigates To | Requires Role |
|---|
| Press any key / Timeout | SCR-M01-01 Sales Terminal | CASHIER+ |
| Scan another item | Stays (new product displayed) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-12 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.14 |
| Database Tables | orders (R/W), order_items (R/W), pricing_rules (R) |
| State Machine(s) | 7.10 Coupon States (AVAILABLE -> APPLIED -> REDEEMED) |
| Appendix F Services | sale.promotion.engine.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Yes (degraded – coupon validation from cached rules; may accept expired coupons) |
| Route | /pos/sales/terminal (modal overlay) |
The Coupon Entry modal allows staff to scan or manually enter coupon codes. The system validates single-use coupons (checking if already redeemed) and multi-use coupons (checking usage limits and expiry). Valid coupons are applied to the cart according to the discount calculation order (step 5 of 7). Coupons are marked REDEEMED upon order finalization.
| Element | Type | Description | Business Rule |
|---|
| Coupon Code Input | Input | Scan barcode or type coupon code | BRD 1.14: POST /coupons/validate |
| Validation Status | Alert | Shows: Valid, Already Redeemed, Expired, Limit Reached | BRD 1.14: Single-use vs multi-use validation |
| Discount Preview | Panel | Shows discount amount and type (% off, $ off, BOGO) | BRD 1.14.1: APPLIED state preview |
| Stacking Warning | Alert | Warns if coupon cannot stack with other active discounts | BRD 1.2.1: Calculation order step 5 |
| Savings Display | Panel | Shows total savings from applied coupon | BRD 1.14: Display savings |
| Apply / Cancel | Button Pair | Confirm coupon application or cancel | BRD 1.14: Coupon linked to order at finalize |
| Action | Navigates To | Requires Role |
|---|
| Apply coupon | Returns to SCR-M01-01 Sales Terminal (coupon applied) | CASHIER+ |
| Cancel | Returns to SCR-M01-01 (no change) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-13 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.15 |
| Database Tables | customers (R), loyalty_accounts (R/W), loyalty_transactions (R/W) |
| State Machine(s) | 7.11 Customer Tier States (BRONZE -> SILVER -> GOLD) |
| Appendix F Services | sale.loyalty.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (loyalty point balance requires real-time server data for accuracy) |
| Route | /pos/sales/terminal (embedded panel or overlay) |
The Loyalty Display shows the attached customer’s current loyalty status during a sale: tier (Bronze/Silver/Gold), points balance, points to be earned from this transaction, and available redemption options. It supports three program types: points-per-dollar, punch cards, and spend thresholds. Points are awarded upon order finalization; redemptions are applied after tax calculation (step 7 of discount order).
| Element | Type | Description | Business Rule |
|---|
| Tier Badge | Badge | Current tier: Bronze (1x), Silver (1.5x + 5%), Gold (2x + 10%) | BRD 1.15.1: Tier state machine |
| Points Balance | Panel | Current redeemable points and dollar equivalent | BRD 1.15: 500 points = $5 off |
| Points to Earn | Panel | Points that will be awarded from this transaction | BRD 1.15: 1 point per $1 (modified by tier multiplier) |
| Redeem Points | Button | Apply points redemption to current sale | BRD 1.2.1: Step 7 – after tax calculation |
| Punch Card Progress | Progress Bar | Shows punch count for qualifying items (e.g., “3 of 10”) | BRD 1.15: Buy 10 Get 1 Free |
| Spend Threshold | Progress Bar | Shows progress toward next reward threshold | BRD 1.15: Spend $100, Get $10 Off |
| Tier Upgrade Alert | Toast | Notification when sale triggers tier upgrade | BRD 1.15.1: Automatic tier upgrades |
| Action | Navigates To | Requires Role |
|---|
| Redeem points | Stays (redemption applied to cart totals) | CASHIER+ |
| View loyalty history | SCR-M02-02 Customer Profile (loyalty tab) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-14 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.4, 1.9 |
| Database Tables | orders (R), order_items (R), returns (R/W), return_items (R/W), store_credits (W), customers (R/W), loyalty_accounts (R/W), cash_movements (W), inventory_levels (R/W) |
| State Machine(s) | 7.1 Order States (COMPLETED -> PARTIALLY_RETURNED / FULLY_RETURNED) |
| Appendix F Services | sale.return.command.service, sale.return-policy.engine.service, sale.receipt.validate.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | Partial (return with receipt allowed offline; queued for sync; no-receipt returns blocked offline) |
| Route | /pos/sales/return |
Return Processing is a two-phase flow: first, locate the original sale via receipt barcode scan or order number lookup; second, select items to return and choose the refund method. The return policy engine evaluates eligibility based on receipt presence, time window (0-30 days: full refund; 31-90 days: store credit; 90+ days: manager override), and item-specific rules (final sale blocked, restocking fees for electronics).
| Element | Type | Description | Business Rule |
|---|
| Receipt Barcode Scanner | Input | Scan receipt barcode to validate and load original sale | BRD 1.4: POST /receipts/validate {barcode_data} |
| Order Number Search | Input | Manual order number entry as fallback | BRD 1.4: GET /orders/{id} |
| Original Sale Display | Panel | Shows all items from original order with quantities and prices | BRD 1.4: Original sale data loaded |
| Item Selection Checkboxes | Checkbox Group | Select which items to return with quantity controls | BRD 1.4: Partial returns supported |
| Policy Evaluation Result | Alert | Shows: Full Refund / Store Credit Only / Manager Override Required / Blocked | BRD 1.9: Time-based policy tiers |
| Refund Method Selector | Radio Group | Original Payment (Manual on terminal or Auto via token) / Cash / Store Credit | BRD 1.4.1: Card refund method selection |
| Restocking Fee | Panel | Shows applicable restocking fee (e.g., 15% for electronics) | BRD 1.9: Item-specific rules |
| Final Sale Block | Alert | Blocks return for items flagged as final sale | BRD 1.9: No returns on final sale |
| Manager PIN | Input | Required for policy exceptions and no-receipt returns | BRD 1.9: Manager override with reason code |
| Commission Reversal Preview | Panel | Shows proportional commission reversal calculation | BRD 1.8.1: Proportional reversal on return |
| Return Reason | Select | Required reason code for the return | BRD 1.4: Reason code for audit |
┌─────────────────────────────────────────────────────────────────────────────┐
│ RETURN PROCESSING [Cancel] [Help] │
├─────────────────────────────────────────────────────────────────────────────┤
│ PHASE 1: LOCATE ORIGINAL SALE │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ Scan Receipt Barcode: [________________________] [Search by Order#] │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
│ ✓ Receipt Valid — Order #LOC-20260215-0042 — Feb 15, 2026 (14 days ago) │
│ Policy: WITHIN 30 DAYS — Full Refund Eligible │
├─────────────────────────────────────────────────────────────────────────────┤
│ PHASE 2: SELECT ITEMS TO RETURN │
│ │
│ [✓] NXJ-1001 Blue Jacket 1 of 1 $89.00 Reason: [Wrong Size ▼] │
│ [ ] NXJ-2045 Cotton Tee 0 of 2 $25.00 │
│ [✓] NXJ-3012 Slim Pants 1 of 1 $65.00 Reason: [Defective ▼] │
│ │
│ Refund Method: (●) Original Payment ( ) Cash ( ) Store Credit │
│ [●] Auto via token [ ] Manual on terminal │
│ │
│ Subtotal: $154.00 Commission Reversal: $5.13 │
│ Tax Refund: + $8.16 (66.7% of original $7.70) │
│ Restocking Fee: $0.00 │
│ ────────────────────────── │
│ REFUND TOTAL: $162.16 │
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ PROCESS RETURN │ │
│ └──────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Process return | SCR-M01-09 Receipt Print / Reprint (return receipt) | CASHIER+ |
| Manager override (no receipt / expired) | Manager PIN modal -> continues return flow | MANAGER+ |
| Cancel return | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-15 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.4 |
| Database Tables | orders (R/W), order_items (R/W), returns (R/W), return_items (R/W), products (R), variants (R), inventory_levels (R/W) |
| State Machine(s) | 7.1 Order States |
| Appendix F Services | sale.exchange.command.service, sale.return-policy.engine.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires real-time inventory and pricing for new items) |
| Route | /pos/sales/exchange |
Exchange Processing is a dedicated flow for swapping items (e.g., different size or color). Staff load the original sale, select items to exchange OUT, scan/add new items IN, and the system calculates the price difference. If the customer owes money, payment is collected; if the store owes a refund, it is processed. Even exchanges require no payment.
| Element | Type | Description | Business Rule |
|---|
| Original Sale Loader | Panel | Load original order to select items for exchange out | BRD 1.4: GET /orders/{id} |
| Items Out Selection | Checkbox Group | Select items being returned in the exchange | BRD 1.4: Items being exchanged out |
| Items In Scanner | Input | Scan or search for new replacement items | BRD 1.4: Items being exchanged in |
| Price Difference Calculator | Panel | Shows: Items Out value vs Items In value, net difference | BRD 1.4: Calculate price difference |
| Collect Payment | Button | Process additional payment if customer owes money | BRD 1.4: “Collect: $15.00 difference” |
| Issue Refund | Button | Process refund if store owes customer | BRD 1.4: “Refund: $10.00 to customer” |
| Even Exchange | Badge | Indicates no payment required | BRD 1.4: No payment required |
| Commission Adjustment | Panel | Shows commission adjustment based on price difference | BRD 1.8.1: Adjust commission if price difference |
| Action | Navigates To | Requires Role |
|---|
| Process exchange (collect payment) | SCR-M01-04 Payment / Checkout | CASHIER+ |
| Process exchange (issue refund) | Refund processed -> SCR-M01-09 Receipt | CASHIER+ |
| Process even exchange | SCR-M01-09 Receipt Print / Reprint | CASHIER+ |
| Cancel | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-16 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.6 |
| Database Tables | orders (R/W), order_items (R/W), products (R), variants (R), customers (R/W), payments (W) |
| State Machine(s) | 7.5 Special Order States (CREATED -> DEPOSIT_PAID -> ORDERED -> RECEIVED -> READY_FOR_PICKUP -> COMPLETED) |
| Appendix F Services | sale.specialorder.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires real-time product lookup and customer verification) |
| Route | /pos/sales/special-order |
The Special Order screen allows staff to create orders for out-of-stock items with customer deposits. A customer must be attached, and a minimum deposit (50% or full) is collected. The order progresses through vendor ordering, receiving, staging, and customer pickup. Notifications are sent when items arrive. Abandoned orders (30+ days without pickup) are flagged.
| Element | Type | Description | Business Rule |
|---|
| Product Search | Input | Search for out-of-stock products to special order | BRD 1.6: “Available for Special Order” |
| Customer Attachment | Panel | Required customer profile for special orders | BRD 1.6: Attach Customer (Required) |
| Quantity Input | Input | Enter quantity needed | BRD 1.6: Quantity for vendor ordering |
| Deposit Calculator | Panel | Shows minimum deposit (50% or full) and amount due | BRD 1.6: Min 50% or Full deposit required |
| Deposit Payment | Button | Process deposit payment through standard payment flow | BRD 1.6: POST /special-orders/create |
| Order Status Display | Badge | Shows current state in special order lifecycle | BRD 1.6.1: 8-state machine |
| Expected Delivery Date | Date Display | Estimated arrival date from vendor | BRD 1.6: Purchasing team notification |
| Special Order Receipt | Button | Print receipt with order number (SO-XXXXX) | BRD 1.6: Print Special Order Receipt |
| Action | Navigates To | Requires Role |
|---|
| Process deposit | SCR-M01-04 Payment / Checkout (deposit amount) | CASHIER+ |
| Cancel special order | Stays (order cancelled, no deposit) | MANAGER+ |
| Print receipt | SCR-M01-09 Receipt Print / Reprint | CASHIER+ |
| Back | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-17 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.7 |
| Database Tables | inventory_levels (R), products (R), variants (R), locations (R), transfer_orders (R/W), transfer_order_items (R/W) |
| State Machine(s) | 7.6 Transfer States, 7.7 Reservation States |
| Appendix F Services | sale.cart.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires network for cross-store inventory query, max 5 min stale) |
| Route | /pos/sales/multi-store |
Multi-Store Inventory Lookup displays real-time (eventually consistent, max 5-minute stale) stock levels across all store locations for a given product. When the current store is out of stock, staff can initiate a transfer request (ship to this store), a reservation (customer picks up at other store), or a ship-to-customer order. All options require full payment before processing.
| Element | Type | Description | Business Rule |
|---|
| Product Display | Panel | Shows product name, SKU, image for the searched item | BRD 1.7: GET /inventory/multi-store/{sku} |
| Stock Level Grid | Table | Stock count at each location: Store A: 5, Store B: 2, etc. | BRD 1.7: Eventually consistent (max 5 min stale) |
| Request Transfer | Button | Create transfer from source store to current store | BRD 1.7: Full payment required; POST /transfers/request |
| Reserve at Store | Button | Reserve item for customer pickup at source store | BRD 1.7: Full payment required; POST /reservations/create |
| Ship to Customer | Button | Ship directly from source store to customer address | BRD 1.7.3: Carrier shipping cost calculation |
| Staleness Indicator | Badge | Shows time since last inventory sync per location | BRD 1.7: Max 5 min stale data |
| Transfer Receipt | Button | Print transfer receipt or pickup voucher for customer | BRD 1.7: Transfer #TRF-789 receipt |
| Action | Navigates To | Requires Role |
|---|
| Request transfer | SCR-M01-04 Payment / Checkout (full payment required) | CASHIER+ |
| Reserve at store | SCR-M01-04 Payment / Checkout (full payment required) | CASHIER+ |
| Ship to customer | SCR-M01-19 Ship-to-Customer | CASHIER+ |
| Back | SCR-M01-01 Sales Terminal | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-18 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.11 |
| Database Tables | orders (R/W), order_items (R), customers (R), inventory_levels (R/W) |
| State Machine(s) | 7.1 Order States (HOLD_FOR_PICKUP -> READY_FOR_PICKUP -> COMPLETED / HOLD_EXPIRED) |
| Appendix F Services | sale.hold-for-pickup.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires real-time inventory reservation and customer verification) |
| Route | /pos/sales/hold-pickup |
Hold for Pickup manages fully paid items held for later customer pickup at the current store. This includes both in-store holds (customer pays now, picks up later) and BOPIS orders (buy online, pick up in store). The screen shows pickup deadline (default 7 days), handles staging items as “ready,” and manages expired holds with customer contact workflows.
| Element | Type | Description | Business Rule |
|---|
| Held Orders List | Table | All active hold-for-pickup orders with status and deadline | BRD 1.11: HOLD_FOR_PICKUP and READY_FOR_PICKUP states |
| Pickup Deadline | Date Display | Configurable deadline (default 7 days) per order | BRD 1.11: Set Pickup Deadline |
| Stage Items | Button | Mark items as staged and ready for customer pickup | BRD 1.11.1: HOLD_FOR_PICKUP -> READY_FOR_PICKUP |
| Release to Customer | Button | Verify customer ID and release items | BRD 1.11: PATCH /orders/{id}/pickup-complete |
| Expired Holds | Alert | Flagged orders past deadline with customer contact required | BRD 1.11.1: HOLD_EXPIRED -> CONTACT_CUSTOMER |
| Extend Deadline | Button | Extend pickup deadline for a held order | BRD 1.11.1: CONTACT_CUSTOMER -> READY_FOR_PICKUP |
| Refund Expired | Button | Process refund for expired hold if customer wants money back | BRD 1.11.1: CONTACT_CUSTOMER -> REFUNDED |
| BOPIS Indicator | Badge | Identifies orders originating from online purchase | BRD 1.11: In-store POS or Online order (BOPIS) |
| Print Pickup Slip | Button | Print pickup slip with order details | BRD 1.11: Print Pickup Slip |
| Action | Navigates To | Requires Role |
|---|
| Create hold (from checkout) | SCR-M01-04 Payment / Checkout (full payment) | CASHIER+ |
| Release to customer | Order COMPLETED; SCR-M01-09 Receipt | CASHIER+ |
| Refund expired hold | SCR-M01-14 Return Processing | MANAGER+ |
| Extend deadline | Stays (deadline updated) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-19 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 1.7, 1.7.3, 1.7.4 |
| Database Tables | orders (R/W), order_items (R/W), customers (R), inventory_levels (R), locations (R) |
| State Machine(s) | 7.8 Ship-to-Customer States (REQUESTED -> PAID -> PICKING -> PACKED -> SHIPPED -> DELIVERED) |
| Appendix F Services | sale.cart.command.service, sale.finalize.command.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires carrier API for real-time shipping cost calculation) |
| Route | /pos/sales/ship-to-customer |
Ship-to-Customer enables direct shipping from a source store to the customer’s address. Staff enter the customer’s shipping address, the system queries carrier APIs for real-time shipping rates (Standard 3-5 days, Express 1-2 days), and the customer pays the full item price plus shipping cost. The source store packs and ships the item with tracking.
| Element | Type | Description | Business Rule |
|---|
| Source Store Selector | Select | Choose which store has the item in stock | BRD 1.7.3: Source store with inventory |
| Shipping Address Form | Form | Customer address entry (or pre-fill from customer profile) | BRD 1.7.3: Enter Address Details |
| Shipping Rate Display | Table | Shows carrier options with prices and delivery estimates | BRD 1.7.3: Standard ($8.99) vs Express ($15.99) |
| Total Calculator | Panel | Item price + selected shipping cost | BRD 1.7.3: Total = Item Price + Shipping Cost |
| Tracking Info | Panel | Shows tracking number and carrier once shipped | BRD 1.7.4: Tracking number from carrier label |
| Shipment Status | Badge | REQUESTED / PAID / PICKING / PACKED / SHIPPED / DELIVERED | BRD 1.7.4: Ship-to-Customer State Machine |
| Customer Notifications | Info | Email sent at SHIPPED (tracking) and DELIVERED (confirmation) | BRD 1.7: TMPL-SHIPMENT-TRACKING, TMPL-DELIVERY-CONFIRMATION |
| Action | Navigates To | Requires Role |
|---|
| Confirm shipping option | SCR-M01-04 Payment / Checkout (item + shipping) | CASHIER+ |
| Cancel | SCR-M01-17 Multi-Store Inventory Lookup | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-20 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 1.8, 1.19, 1.1.2, 1.3.4, 1.4.2, 1.5.3 |
| Database Tables | orders (R), order_items (R), payments (R), returns (R), return_items (R), shifts (R), cash_drawers (R), cash_movements (R), gift_cards (R), gift_card_transactions (R), reports (R/W) |
| State Machine(s) | – |
| Appendix F Services | sale.history.query.service, sale.daily-summary.projection.service |
| User Roles | MANAGER, OWNER, AUDITOR |
| Offline Capable | No (requires server-side aggregation of sales data) |
| Route | /admin/reports/sales |
The Sales Reports Dashboard provides comprehensive sales analytics across all report categories defined in Module 1: daily sales summaries, hourly heatmaps, payment method breakdowns, discount usage, return summaries, gift card liability, variance history, and more. Managers can filter by date range, location, employee, and status, and export results to CSV.
| Element | Type | Description | Business Rule |
|---|
| Report Selector | Tab Group / Dropdown | Choose from 20+ report types across all sales subsections | BRD 1.1.2-1.18.4: All report types |
| Date Range Picker | Input | Filter by date range (today, this week, this month, custom) | BRD 1.19: Date-based filtering |
| Location Filter | Select | Filter by store location or “All Locations” | BRD 1.8: Per-location reporting |
| Employee Filter | Select | Filter by employee for commission and performance reports | BRD 1.8: Employee-specific data |
| Summary Cards | Panel Grid | Key metrics: Total Sales, Avg Transaction, Return Rate, etc. | BRD 1.1.2: Daily Sales Summary |
| Data Table | Table | Detailed tabular data for selected report | BRD 1.19: Paginated results |
| Chart Visualization | Chart | Bar charts, line charts, heatmaps for visual analysis | BRD 1.1.2: Hourly Sales Heatmap |
| Export CSV | Button | Export current report data to CSV file | BRD 1.19: Data export |
| Save Report | Button | Save report configuration for quick access | Reports table: Saved configurations |
| Action | Navigates To | Requires Role |
|---|
| Select report type | Stays (data reloads for selected report) | MANAGER+ |
| Export CSV | Download file (stays on page) | MANAGER+ |
| Click order row | SCR-M01-09 Receipt Print / Reprint (order detail) | MANAGER+ |
| Commission reports tab | SCR-M01-21 Commission Management | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-21 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 1.8 |
| Database Tables | orders (R), order_items (R), returns (R), customers (R) |
| State Machine(s) | – |
| Appendix F Services | sale.commission.command.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (requires server-side aggregation of commission data) |
| Route | /admin/reports/commissions |
The Commission Management screen provides detailed commission tracking per employee. It shows total sales, commission earned, returns impact (proportional reversal), and net commission for a configurable period. Managers can drill into individual transactions to see commission calculation details and review reversal adjustments from voids and returns.
| Element | Type | Description | Business Rule |
|---|
| Employee Selector | Select | Choose employee or view all employees | BRD 1.8: Per-employee commission tracking |
| Period Selector | Date Range | Select commission period (weekly, biweekly, monthly) | BRD 1.8.2: Period overview |
| Commission Summary | Table | Employee, Sales Count, Sales Total, Commission Earned, Returns Impact, Net | BRD 1.8.2: Commission Summary report |
| Commission Rate Display | Panel | Shows employee’s commission rate and tier | BRD 1.8.1: percentage_of_sale base method |
| Reversal Log | Table | Shows commission adjustments from voids (100%) and returns (proportional) | BRD 1.8.1: Void=full reversal, Return=proportional |
| Proportional Calc Detail | Panel | Original Commission x (Returned Value / Original Sale Value) | BRD 1.8.1: Proportional calculation formula |
| Export | Button | Export commission data for payroll processing | BRD 1.8.2: Commission by Employee report |
| Action | Navigates To | Requires Role |
|---|
| Click employee row | Drill-down to employee transaction detail | MANAGER+ |
| Click order in reversal log | SCR-M01-09 Receipt Print / Reprint (order detail) | MANAGER+ |
| Export | Download CSV (stays on page) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M01-22 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 1.16, 1.16.3 |
| Database Tables | orders (R/W), order_items (R), shifts (R), cash_counts (R), cash_movements (R) |
| State Machine(s) | 7.12 Connectivity States |
| Appendix F Services | sale.offline.sync.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (this screen reviews discrepancies detected during online sync) |
| Route | /admin/discrepancy-review |
The Manager Discrepancy Review screen displays all flagged discrepancies from offline-to-online sync operations and cash drawer variances. When the POS reconnects after offline operation, the server applies current prices (server-authoritative) and logs any differences. Managers review each flagged transaction, decide whether customer credits are warranted for price changes, and acknowledge or resolve each discrepancy.
| Element | Type | Description | Business Rule |
|---|
| Discrepancy Queue | Table | List of all flagged items: type, order, cached price vs server price, status | BRD 1.16.3: Server is authoritative |
| Discrepancy Type Filter | Select | Filter by: Price Changed, Out of Stock, Promotion Expired, Customer Deleted | BRD 1.16.3: Six discrepancy types |
| Price Difference Detail | Panel | Shows cached price at time of sale vs current server price, delta | BRD 1.16.3: Flag-on-sync price discrepancy |
| Customer Credit Action | Button | Issue store credit for price difference if warranted | BRD 1.16.3: Manager decides if credit warranted |
| Acknowledge | Button | Mark discrepancy as reviewed (no action needed) | BRD 1.16.3: Review and approve |
| Resolve | Button | Mark as resolved with notes | BRD 1.16.3: Resolution tracking |
| Cash Variance Section | Panel | Cash drawer variances from shift close operations | BRD 1.12.3: Variance History Report |
| Offline Sale Count | Badge | Total number of sales processed while offline | BRD 1.16: Queue count from sync |
| Action | Navigates To | Requires Role |
|---|
| Issue customer credit | Store credit created -> stays on page | MANAGER+ |
| Acknowledge discrepancy | Stays (item marked as reviewed) | MANAGER+ |
| Click order detail | SCR-M01-09 Receipt Print / Reprint | MANAGER+ |
| Resolve all | Stays (batch resolution) | OWNER+ |
BRD Sections: 2.1-2.8 | Appendix F: §F.5 (7 services) | Pattern: Standard CRUD
Cross-Reference: See Ch 05, Sections 2.1-2.8 for business rules. See Ch 08, Domain 5 (Customer Loyalty & Gift Cards) for table schemas. See Appendix F, §F.5 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M02-01 |
| Product(s) | All Roles |
| BRD Section(s) | 2.1 |
| Database Tables | customers (R), loyalty_accounts (R) |
| State Machine(s) | – |
| Appendix F Services | customer.search.query.service |
| User Roles | CASHIER, MANAGER, OWNER |
| Offline Capable | No (customer search requires real-time uniqueness and server query) |
| Route | /customers (MANAGER+), /pos/customers (CASHIER+ overlay) |
The Customer List is the primary directory for searching and browsing customer profiles. It supports search by name, phone, email, or loyalty number with real-time filtering. On the sales terminal, it appears as a search overlay for attaching customers to sales; for managers, it provides full list management with sorting, filtering by group/tier, and bulk export capabilities.
| Element | Type | Description | Business Rule |
|---|
| Search Bar | Input | Search by name, phone, email, or loyalty number | BRD 2.1: GET /customers/search |
| Customer Table | Table | Name, phone, email, tier, group, last visit, total spent | BRD 2.1: Paginated customer list |
| Tier Filter | Select | Filter by tier: All, Bronze, Silver, Gold | BRD 2.2: Customer tiers |
| Group Filter | Select | Filter by group: All, Retail, Wholesale, VIP, Staff | BRD 2.2: Customer groups |
| Sort Options | Select | Sort by: Name, Last Visit, Total Spent, Loyalty Points | BRD 2.1: Customer directory sorting |
| Create New | Button | Open customer creation form | BRD 2.1: POST /customers/create |
| Export CSV | Button | Export filtered customer list (max 1,000 rows) | BRD 2.5: Limit 1000 rows per batch |
| Quick Attach | Button | Attach selected customer to current POS sale (POS mode only) | BRD 1.1: Attach Customer to sale |
| Action | Navigates To | Requires Role |
|---|
| Click customer row | SCR-M02-02 Customer Profile / Detail | CASHIER+ |
| Click “Create New” | SCR-M02-03 Customer Create / Edit | CASHIER+ |
| Click “Export CSV” | Download file (stays on page) | MANAGER+ |
| Quick Attach (POS) | Returns to SCR-M01-01 Sales Terminal (customer attached) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-02 |
| Product(s) | All Roles |
| BRD Section(s) | 2.1, 2.3, 2.4 |
| Database Tables | customers (R), loyalty_accounts (R), loyalty_transactions (R), orders (R), returns (R), store_credits (R), gift_cards (R) |
| State Machine(s) | 7.11 Customer Tier States |
| Appendix F Services | customer.profile.crud.service, customer.search.query.service |
| User Roles | CASHIER, MANAGER, OWNER |
| Offline Capable | No (requires real-time customer data including balances and history) |
| Route | /customers/:id |
The Customer Profile is a dense information screen showing all aspects of a customer’s relationship with the business: personal details, contact information, loyalty tier and points, purchase history, store credit balances, notes and preferences, and communication settings. It serves as the central hub from which staff navigate to edit, merge, delete, or manage customer-specific actions.
| Element | Type | Description | Business Rule |
|---|
| Customer Header | Panel | Name, customer number, tier badge, group badge, last visit | BRD 2.1: Customer overview |
| Contact Info | Panel | Phone, email, shipping address, billing address | BRD 2.1: Distinct shipping and billing addresses |
| Loyalty Summary | Panel | Tier, points balance, lifetime points, point multiplier | BRD 1.15: Tier benefits display |
| Purchase History | Table | Recent orders with date, total, status, location | BRD 2.1: Sales history linked to customer |
| Store Credit Balance | Panel | Active store credits with amounts and expiry dates | Store credits table: remaining_amount, expires_at |
| Account Balance | Panel | On-account debt, credit limit, available credit | BRD 1.3.3: Credit Limit calculation |
| Notes & Preferences | Panel | Clothing size, shoe size, color preferences, free-form notes | BRD 2.3: Structured and free-form notes |
| Communication Prefs | Panel | Email opt-in, SMS opt-in, preferred contact, Do Not Contact flag | BRD 2.4: Marketing consent status |
| Tags | Badge Group | Customer tags (e.g., “High Value”, “Returns Often”) | Customers table: tags[] array |
| Tax Status | Badge | Tax exempt status and exemption certificate ID | BRD 2.1: Custom tax rates |
┌─────────────────────────────────────────────────────────────────────────────┐
│ CUSTOMER PROFILE [Edit] [Merge] [Delete] [?]│
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────┬─────────────────────────────────────┐│
│ │ JANE DOE #C-00142 │ LOYALTY ││
│ │ ★ Gold Tier VIP Group │ Tier: GOLD (2x points, 10% off) ││
│ │ │ Points: 2,450 ($24.50 available) ││
│ │ Phone: (804) 555-1234 │ Lifetime: 12,800 pts ││
│ │ Email: jane@example.com │ Next Downgrade: $5,000/yr spend ││
│ │ Last Visit: Feb 28, 2026 │ Annual Spend: $6,200 ││
│ │ Total Spent: $18,450 │ ││
│ │ Visits: 84 │ ACCOUNT ││
│ │ │ Credit Limit: $500 ││
│ │ Shipping: 123 Main St, Suite 4 │ Current Debt: $0.00 ││
│ │ Richmond, VA 23220 │ Available: $500.00 ││
│ │ Billing: Same as shipping │ Store Credits: $25.00 ││
│ │ │ ││
│ │ Tax: Standard (not exempt) │ Tags: [High Value] [VIP] ││
│ └───────────────────────────────────┴─────────────────────────────────────┘│
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ NOTES & PREFERENCES [Edit] │ │
│ │ Size: M | Shoe: 8.5 | Colors: Navy, Charcoal │ │
│ │ Brands: Levi's, Carhartt │ │
│ │ Note: "Prefers classic styles, allergic to wool" │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ COMMUNICATION [Edit] │ │
│ │ Email Marketing: ON | SMS Marketing: OFF │ │
│ │ Preferred Contact: Email | Do Not Contact: No │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ RECENT PURCHASES │ │
│ │ Date │ Order# │ Total │ Status │ │
│ │ 2026-02-28 │ LOC-20260228-012 │ $240.72 │ Completed │ │
│ │ 2026-02-15 │ LOC-20260215-042 │ $154.00 │ Partially Ret. │ │
│ │ 2026-01-30 │ LOC-20260130-008 │ $89.00 │ Completed │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Edit” | SCR-M02-03 Customer Create / Edit | CASHIER+ |
| Click “Merge” | SCR-M02-07 Customer Merge / Dedup | MANAGER+ |
| Click “Delete” | SCR-M02-08 Customer Deletion / Anonymize | MANAGER+ |
| Click order row | SCR-M01-09 Receipt Print / Reprint (order detail) | CASHIER+ |
| Click “Notes & Preferences Edit” | SCR-M02-05 Customer Notes & Preferences | CASHIER+ |
| Click “Communication Edit” | SCR-M02-06 Communication Preferences | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-03 |
| Product(s) | All Roles |
| BRD Section(s) | 2.1 |
| Database Tables | customers (R/W), loyalty_accounts (W) |
| State Machine(s) | – |
| Appendix F Services | customer.profile.crud.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (customer creation requires uniqueness check against server; blocked offline per BRD 1.16.2) |
| Route | /customers/new, /customers/:id/edit |
The Customer Create/Edit form handles profile creation and modification. It collects personal details (name, phone, email), separate shipping and billing addresses, customer group assignment (which determines price tier), tax exemption status, and initial communication preferences. Email and phone uniqueness is validated server-side to prevent duplicates.
| Element | Type | Description | Business Rule |
|---|
| First Name / Last Name | Input | Required fields | BRD 2.1: first_name, last_name NOT NULL |
| Phone | Input | Phone number with format validation | BRD 2.1: Unique per tenant (partial index) |
| Email | Input | Email with format validation | BRD 2.1: Unique per tenant (partial index) |
| Shipping Address | Form Group | Street, city, state, ZIP, country for physical delivery | BRD 2.1: Enter Physical Address (Shipping) |
| Billing Address | Form Group | Same as shipping checkbox, or separate billing address | BRD 2.1: Enter Billing Address (if different) |
| Customer Group | Select | Retail, Wholesale, VIP, Staff | BRD 2.2: Group determines Price Tier |
| Tax Exemption | Toggle + Input | Tax exempt status and exemption certificate ID | BRD 2.1: Custom Tax Rate override |
| Communication Prefs | Toggle Group | Email opt-in, SMS opt-in, preferred contact method | BRD 2.4: Initial consent settings |
| Date of Birth | Date Input | Birthday for loyalty program benefits | Customer model: date_of_birth |
| Company | Input | Company name for business customers | Customer model: company field |
| Save / Cancel | Button Pair | Submit form or discard changes | BRD 2.1: POST /customers/create or PATCH |
| Action | Navigates To | Requires Role |
|---|
| Save (create) | SCR-M02-02 Customer Profile (new customer) | CASHIER+ |
| Save (edit) | SCR-M02-02 Customer Profile (updated) | CASHIER+ |
| Cancel | SCR-M02-01 Customer List or SCR-M02-02 Profile | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-04 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.2 |
| Database Tables | customers (R/W), loyalty_accounts (R/W) |
| State Machine(s) | 7.11 Customer Tier States (BRONZE -> SILVER -> GOLD) |
| Appendix F Services | customer.group.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (requires server-side tier calculation and group management) |
| Route | /admin/customers/groups |
Customer Group/Tier Management allows administrators to configure customer groups (Retail, Wholesale, VIP, Staff), define automatic tier upgrade thresholds (Bronze at $0, Silver at $1,000/yr, Gold at $5,000/yr), and configure tier benefits (point multipliers, automatic discounts, early access). Managers can also manually assign or override customer groups and tiers.
| Element | Type | Description | Business Rule |
|---|
| Group List | Table | All customer groups with member count and pricing tier | BRD 2.2: Retail, Wholesale, VIP, Staff |
| Tier Thresholds | Form | Annual spend thresholds for each tier | BRD 1.15.1: $1,000 Silver, $5,000 Gold |
| Tier Benefits | Form | Point multiplier, discount %, early access per tier | BRD 1.15.1: Bronze 1x, Silver 1.5x+5%, Gold 2x+10% |
| Customer Assignment | Panel | Bulk assign/reassign customers to groups | BRD 2.2: Manual Group Assignment |
| Tier Distribution Chart | Chart | Visual breakdown of customers by tier | BRD 2.6.1: Tier Distribution Report |
| Auto-Tier Toggle | Toggle | Enable/disable automatic tier upgrades based on spend | BRD 2.2: Automatic Tier Upgrades (Background Job) |
| Price Tier Mapping | Table | Maps each group to its pricing rules | BRD 2.2: Group determines Price Tier |
| Action | Navigates To | Requires Role |
|---|
| Edit group settings | Stays (inline edit) | MANAGER+ |
| Click customer in group | SCR-M02-02 Customer Profile | MANAGER+ |
| Save tier thresholds | Stays (configuration saved) | OWNER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-05 |
| Product(s) | All Roles |
| BRD Section(s) | 2.3 |
| Database Tables | customers (R/W) |
| State Machine(s) | – |
| Appendix F Services | customer.notes.crud.service |
| User Roles | CASHIER, MANAGER |
| Offline Capable | No (requires server to persist preference updates) |
| Route | /customers/:id/notes |
The Customer Notes & Preferences screen provides both structured preference fields and free-form notes for customer profiles. Structured fields capture clothing size, shoe size, color preferences, and brand preferences. Free-form notes allow staff to record any additional observations. These notes are displayed at the POS when the customer is attached to a sale, enabling personalized service.
| Element | Type | Description | Business Rule |
|---|
| Clothing Size | Select | S, M, L, XL, XXL | BRD 2.3: Structured preferences |
| Shoe Size | Input | Numeric shoe size | BRD 2.3: Structured preferences |
| Color Preferences | Multi-Select | Preferred colors from configurable list | BRD 2.3: Color Preferences |
| Brand Preferences | Multi-Select | Preferred brands from configurable list | BRD 2.3: Brand Preferences |
| Free-Form Notes | Textarea | Open text for staff observations | BRD 2.3: “Prefers classic styles, allergic to wool” |
| Note History | Table | Chronological list of note additions with author and timestamp | BRD 2.3: Audit trail of note changes |
| POS Display Preview | Panel | Preview of how notes appear during POS sale attachment | BRD 2.3: Notes Display at POS |
| Save | Button | Persist all preference changes | BRD 2.3: PATCH /customers/{id}/preferences |
| Action | Navigates To | Requires Role |
|---|
| Save | SCR-M02-02 Customer Profile (preferences updated) | CASHIER+ |
| Cancel | SCR-M02-02 Customer Profile (no change) | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-06 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.4 |
| Database Tables | customers (R/W) |
| State Machine(s) | – |
| Appendix F Services | customer.communication.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (consent changes must be logged server-side immediately for compliance) |
| Route | /customers/:id/communication |
The Communication Preferences screen manages marketing consent and contact preferences for a customer. It controls email and SMS marketing opt-in/opt-out, preferred contact method, and the “Do Not Contact” flag that blocks all marketing outreach while preserving transactional notifications. All consent changes are logged with timestamps for privacy compliance audit trails.
| Element | Type | Description | Business Rule |
|---|
| Email Marketing Toggle | Toggle | Opt-in/opt-out for email marketing | BRD 2.4: Email Marketing [ON/OFF] |
| SMS Marketing Toggle | Toggle | Opt-in/opt-out for SMS marketing | BRD 2.4: SMS Marketing [ON/OFF] |
| Preferred Contact Method | Radio Group | Email, Phone, SMS | BRD 2.4: Preferred Contact selection |
| Do Not Contact | Toggle | Master block on all marketing outreach | BRD 2.4: Blocks all outreach |
| Consent Change Log | Table | Timestamp, field changed, old value, new value, changed by | BRD 2.4: Audit Trail for compliance |
| Privacy Notice | Info Panel | Displays consent terms and privacy policy reference | BRD 2.4: Privacy Compliance |
| Save | Button | Persist changes and log consent update | BRD 2.4: PATCH /customers/{id}/communication-prefs |
| Action | Navigates To | Requires Role |
|---|
| Save | SCR-M02-02 Customer Profile (prefs updated, consent logged) | MANAGER+ |
| Cancel | SCR-M02-02 Customer Profile (no change) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-07 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.5 |
| Database Tables | customers (R/W), loyalty_accounts (R/W), loyalty_transactions (R/W), orders (R/W), returns (R/W), store_credits (R/W) |
| State Machine(s) | – |
| Appendix F Services | customer.merge.command.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (requires server-side data transfer and uniqueness validation) |
| Route | /admin/customers/merge |
Customer Merge/Dedup enables managers to consolidate duplicate customer profiles. Staff select a “Source” (duplicate) and “Target” (primary) profile. The system transfers all sales history, loyalty points, account balances, and notes to the target. The higher tier is preserved. The source profile is soft-deleted (archived) with a merge audit trail.
| Element | Type | Description | Business Rule |
|---|
| Source Customer Selector | Search + Select | Select the duplicate profile to merge FROM | BRD 2.5: Select “Source” (Duplicate) |
| Target Customer Selector | Search + Select | Select the primary profile to merge INTO | BRD 2.5: Select “Target” (Primary) |
| Side-by-Side Comparison | Panel | Compare both profiles: name, email, phone, points, tier, spend | BRD 2.5: Visual comparison before merge |
| Data Transfer Preview | Table | Shows what will be transferred: history count, points, balance, notes | BRD 2.5: Move History, Loyalty, Balance to Target |
| Tier Resolution | Display | Shows which tier will be kept (higher of the two) | BRD 2.5: Keep Higher Tier |
| Notes Merge Preview | Panel | Shows how notes will be appended (source appended to target) | BRD 2.5: Merge Notes (Append Source to Target) |
| Confirm Merge | Button | Execute merge with confirmation dialog | BRD 2.5: POST /customers/merge |
| Cancel | Button | Cancel merge operation | BRD 2.5: No data changed |
| Action | Navigates To | Requires Role |
|---|
| Confirm merge | SCR-M02-02 Customer Profile (merged target profile) | MANAGER+ |
| Cancel | SCR-M02-01 Customer List | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-08 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.5 |
| Database Tables | customers (R/W), orders (R), store_credits (R), loyalty_accounts (R) |
| State Machine(s) | – |
| Appendix F Services | customer.privacy.command.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (requires server-side balance verification and anonymization) |
| Route | /admin/customers/:id/delete |
Customer Deletion/Anonymize provides safe deletion with guard rails. The system blocks deletion if the customer has outstanding on-account debt or open layaways. When deletion proceeds, personal data is anonymized (replaced with “Anonymous”) while sales history is retained for accounting integrity. This screen also handles GDPR/privacy data subject requests for export, deletion, or restriction.
| Element | Type | Description | Business Rule |
|---|
| Balance Check Display | Alert | Shows outstanding debt and open layaways (if any) | BRD 2.5: Cannot delete with outstanding balance |
| Block Alert | Alert | “Cannot Delete - Outstanding Balance: $X.XX” | BRD 2.5: Error if debt or open layaway |
| Anonymization Preview | Panel | Shows which fields will be scrubbed vs retained | BRD 2.5: Anonymize Personal Data; retain sales history |
| Confirm Delete | Button | Type-to-confirm deletion with customer name | BRD 2.5: DELETE /customers/{id} |
| Privacy Request Type | Radio Group | Export / Delete / Restrict processing | BRD 2.5: Data Subject Request types |
| Request ID | Display | Generated request tracking ID | BRD 2.5: Must complete within 30 days |
| Completion Deadline | Date Display | 30-day deadline for privacy request completion | BRD 2.5: 30-day compliance requirement |
| Action | Navigates To | Requires Role |
|---|
| Confirm deletion | SCR-M02-01 Customer List (customer removed) | MANAGER+ |
| Submit privacy request | Stays (request logged with tracking ID) | MANAGER+ |
| Cancel | SCR-M02-02 Customer Profile | MANAGER+ |
| Settle balance first | SCR-M02-02 Customer Profile (account tab) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-09 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.6, 5.17 |
| Database Tables | loyalty_accounts (R/W), loyalty_transactions (R/W), customers (R) |
| State Machine(s) | 7.11 Customer Tier States |
| Appendix F Services | sale.loyalty.command.service, customer.group.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (requires server-side aggregation of loyalty data) |
| Route | /admin/loyalty |
The Loyalty Admin Dashboard provides a comprehensive view of the loyalty program: total points economy (issued, redeemed, expired, outstanding), tier distribution, program configuration, and individual customer point adjustments. Managers can manually adjust points (with mandatory reason notes), configure point earning rates, and view expiry forecasts. This is the management counterpart to the sales terminal loyalty display (SCR-M01-13).
| Element | Type | Description | Business Rule |
|---|
| Points Economy Summary | Panel | Total issued, redeemed, expired, outstanding balance | BRD 1.15.2: Loyalty Points Summary report |
| Tier Distribution | Chart | Pie/bar chart of customers by tier (Bronze/Silver/Gold) | BRD 2.6.1: Tier Distribution Report |
| Points Expiry Forecast | Table | Customers with points expiring soon, amounts, dates | BRD 1.15.2: Points Expiry Forecast |
| Manual Points Adjustment | Form | Select customer, enter points (+/-), mandatory reason note | BRD 2.7 (Story 2.B.3): Manual adjustment with reason |
| Program Configuration | Form | Point earning rate, redemption ratio, tier thresholds, expiry rules | BRD 5.17: Loyalty program settings |
| Punch Card Activity | Table | Active punch cards, completion rates, average time to complete | BRD 1.15.2: Punch Card Activity report |
| ROI Analysis | Panel | Points cost vs additional revenue from loyalty customers | BRD 1.15.2: Loyalty ROI Analysis |
| Export | Button | Export loyalty data for analysis | BRD 2.6.1: Reports export |
| Action | Navigates To | Requires Role |
|---|
| Adjust points | Stays (points updated, reason logged) | MANAGER+ |
| Click customer row | SCR-M02-02 Customer Profile | MANAGER+ |
| Save configuration | Stays (program settings saved) | OWNER+ |
| Export | Download CSV (stays on page) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M02-10 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 2.4 |
| Database Tables | customers (R) |
| State Machine(s) | – |
| Appendix F Services | customer.communication.crud.service |
| User Roles | MANAGER, OWNER, AUDITOR |
| Offline Capable | No (requires server-side audit log data) |
| Route | /admin/customers/communication-log |
The Communication Log provides a complete audit trail of all marketing consent changes, automated notifications sent (welcome emails, tier upgrades, shipment tracking, refund confirmations), and privacy-related communications. This screen supports regulatory compliance by documenting every consent change with timestamp, source, and the user who made the change. Auditors use this for compliance verification.
| Element | Type | Description | Business Rule |
|---|
| Customer Filter | Search | Filter log by specific customer | BRD 2.4: Per-customer audit trail |
| Date Range Filter | Date Range | Filter by date range | BRD 2.4: Time-based filtering |
| Event Type Filter | Select | Filter by: Consent Change, Email Sent, SMS Sent, Privacy Request | BRD 2.4: All communication events |
| Log Table | Table | Timestamp, customer, event type, details, changed by, old/new value | BRD 2.4: All consent changes logged with timestamp |
| Email Template Log | Table | Emails sent: template ID, recipient, trigger event, delivery status | BRD 2.6.1: TMPL-WELCOME, TMPL-TIER-UPGRADE, etc. |
| Privacy Request Tracker | Table | Open privacy requests with type, status, deadline | BRD 2.5: 30-day compliance tracking |
| Export Audit Trail | Button | Export full communication audit log | BRD 2.4: Compliance export |
| Action | Navigates To | Requires Role |
|---|
| Click customer name | SCR-M02-02 Customer Profile | MANAGER+ |
| Click privacy request | SCR-M02-08 Customer Deletion / Anonymize | MANAGER+ |
| Export | Download CSV (stays on page) | AUDITOR+ |
BRD Sections: 3.1-3.15 | Appendix F: §F.6 (20 services) | Pattern: CRUD + Redis Cache
Cross-Reference: See Ch 05, Sections 3.1-3.15 for business rules. See Ch 08, Domain 1 (Product Catalog) for table schemas. See Appendix F, §F.6 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M03-01 |
| Product(s) | All Roles |
| BRD Section(s) | 3.1, 3.9 |
| Database Tables | products (R), variants (R), categories (R), brands (R), inventory_levels (R), tags (R), product_tag (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.product.query.service, catalog.search.service |
| User Roles | ALL |
| Offline Capable | Yes (sales terminal: cached product list from product_cache SQLite WASM table; management screens: No — requires server) |
| Route | /catalog/products |
Provides a searchable, filterable list of all products in the tenant’s catalog. Staff use this screen to find products by SKU, barcode, name, brand, or tag, with results returned in under 200ms. It serves as the primary navigation hub for all catalog management operations.
| Element | Type | Description | Business Rule |
|---|
| Search bar | Input | Full-text search with auto-complete (2+ chars, 150ms debounce, top 8 suggestions). Supports fuzzy matching (Levenshtein distance <= 2) | BRD 3.9.1 |
| Product table | Table | Columns: Image, SKU, Name, Brand, Category, Price, Stock (sum across locations), Status. Sortable by any column | BRD 3.1.3 |
| Filter sidebar | Panel | Filters: Category (hierarchy tree), Brand, Status (Draft/Active/Discontinued/Archived), Tags, Price range, Stock level (In Stock/Low/Out) | BRD 3.9.3 |
| Bulk actions toolbar | Button group | Select multiple rows → Bulk Edit, Bulk Channel Toggle, Bulk Delete, Bulk Category Move, Export CSV | BRD 3.6.2 |
| Recent searches | Panel | Last 10 searches per user in dropdown when search field focused | BRD 3.9.1 |
| Status badge | Badge | Color-coded lifecycle status: Draft (grey), Active (green), Discontinued (amber), Archived (red) | BRD 3.2.1 |
| Pagination controls | Panel | Page size (25/50/100), page navigation, total result count | BRD 3.1 |
| + New Product button | Button | Opens product creation form (SCR-M03-02) | BRD 3.1 |
| Action | Navigates To | Requires Role |
|---|
| Click product row | SCR-M03-02 Product Detail / Edit | ALL |
| Click “+ New Product” | SCR-M03-02 Product Detail / Edit (create mode) | MANAGER+ |
| Click “Bulk Channel Toggle” | SCR-M03-12 Multi-Channel Allocation (modal) | MANAGER+ |
| Click “Print Labels” (bulk) | SCR-M03-14 Label Printing | ALL |
| Click category in filter | Filters product list to selected category | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-02 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.1, 3.2, 3.4, 3.11, 3.12 |
| Database Tables | products (RW), variants (RW), categories (R), brands (R), tags (R), product_tag (RW), product_collection (RW), pricing_rules (R), collections (R) |
| State Machine(s) | Product Lifecycle (DRAFT → ACTIVE → DISCONTINUED → ARCHIVED) |
| Appendix F Services | catalog.product.crud.service, catalog.variant.crud.service, catalog.product.lifecycle.service, catalog.media.crud.service, catalog.barcode.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No — requires server for save operations |
| Route | /catalog/products/:id |
The primary form for creating and editing products. Displays all product attributes organized into tabbed sections: Identity, Pricing, Variants, Media, Channels, Inventory, and Custom Fields. Manages the product lifecycle state machine and enforces validation rules before publishing.
| Element | Type | Description | Business Rule |
|---|
| Product type selector | Input | Standard / Variant Parent / Composite / Service — sets form mode | BRD 3.1.1 |
| Identity section | Panel | SKU (auto-generated or manual), Name, Description, Brand (dropdown), Category (hierarchy picker), Product Group, Gender, Origin, Fabric, Season | BRD 3.1.3 |
| Pricing section | Panel | Base price, Cost price, Compare-at price, Tax code, Selling UoM, Purchasing UoM, UoM conversion factor | BRD 3.1.3, 3.3.1 |
| Variant matrix tab | Panel | Grid editor for size/color combinations — links to SCR-M03-03 | BRD 3.1.6 |
| Media tab | Panel | Image upload/reorder, primary image selection, video URLs | BRD 3.11.1 |
| Channel visibility tab | Panel | Toggle per channel (IN_STORE, ONLINE, WHOLESALE) with scheduled date windows | BRD 3.6.2 |
| Barcode section | Panel | Primary barcode (UPC-A/EAN-13/Internal), alternate barcodes list, auto-generate button | BRD 3.4.1, 3.4.2 |
| Tags & Collections | Panel | Freeform tag entry, collection assignment multi-select | BRD 3.5.2 |
| Custom fields section | Panel | Tenant-defined custom attributes (TEXT/NUMBER/LIST/BOOLEAN) | BRD 3.1.4 |
| Lifecycle status bar | Panel | Current status badge + action buttons: Publish (Draft→Active), Discontinue, Archive. Preconditions displayed | BRD 3.2.1, 3.2.2 |
| Shipping section | Panel | Shippable toggle, weight, dimensions, package type. Mandatory when shippable=true | BRD 3.1.3 |
| Clone button | Button | Creates a new DRAFT product with new auto-generated SKU, copies all fields | BRD 3.1.5 |
| Audit trail | Panel | Created by, updated by, timestamps, lifecycle transitions log | BRD 3.13.4 |
┌─────────────────────────────────────────────────────────────────────────┐
│ PRODUCT DETAIL: Classic Oxford Shirt (NXJ1078) [Active ●] [Clone] │
├──────────┬──────────────────────────────────────────────────────────────┤
│ Tabs: │ [Identity] [Pricing] [Variants] [Media] [Channels] [Custom]│
├──────────┴──────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────┐ ┌────────────────────────────────┐ │
│ │ SKU: NXJ1078 │ │ Primary Image [Upload] [▲▼] │ │
│ │ Name: Classic Oxford Shirt │ │ ┌──────────┐ ┌──────────┐ │ │
│ │ Brand: [Nexus ▼] │ │ │ │ │ │ │ │
│ │ Category: [Men > Tops ▼] │ │ │ img-1 │ │ img-2 │ │ │
│ │ Product Group: [Tops ▼] │ │ │ ★primary │ │ │ │ │
│ │ Gender: [Men ▼] │ │ └──────────┘ └──────────┘ │ │
│ │ Season: [Spring 2026 ▼] │ └────────────────────────────────┘ │
│ │ Origin: [Imported ▼] │ │
│ │ Fabric: [100% Cotton ] │ ┌────────────────────────────────┐ │
│ └─────────────────────────────┘ │ PRICING │ │
│ │ Base Price: [$29.00 ] │ │
│ ┌─────────────────────────────┐ │ Cost Price: [$12.00 ] │ │
│ │ BARCODE │ │ Compare At: [$35.00 ] │ │
│ │ Primary: [012345678901 ] │ │ Tax Code: [clothing ▼] │ │
│ │ Type: UPC-A │ │ Selling UoM: [EACH ▼] │ │
│ │ Alternates: + Add │ └────────────────────────────────┘ │
│ │ · VENDOR-SKU-X99 │ │
│ └─────────────────────────────┘ ┌────────────────────────────────┐ │
│ │ TAGS & COLLECTIONS │ │
│ ┌─────────────────────────────┐ │ Tags: [bestseller] [oxford] + │ │
│ │ SHIPPING │ │ Collections: [✓ New Arrivals] │ │
│ │ [✓] Shippable │ │ [✓ Staff Picks] │ │
│ │ Weight: [0.35] [lb ▼] │ └────────────────────────────────┘ │
│ │ Dims: [12x8x2] [in ▼] │ │
│ │ Package: [Box ▼] │ │
│ └─────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ [Save Draft] [Publish ▶] [Discontinue] [Delete] [Cancel] │
└─────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Variants” tab | SCR-M03-03 Variant Matrix Editor (inline) | MANAGER+ |
| Click “Publish” | Stays on page; status changes to ACTIVE. Validates: name, SKU, price, category set | MANAGER+ |
| Click “Discontinue” | Stays on page; status changes to DISCONTINUED. Blocks new POs | MANAGER+ |
| Click “Archive” | Stays on page; requires stock=0 at all locations | OWNER |
| Click “Clone” | SCR-M03-02 (new product, pre-filled, DRAFT status, new SKU) | MANAGER+ |
| Click “Print Label” | SCR-M03-14 Label Printing (pre-filled with this product) | ALL |
| Click “View Analytics” | SCR-M03-18 Product Analytics (filtered to this product) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-03 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.1.6 |
| Database Tables | products (R), variants (RW) |
| State Machine(s) | — |
| Appendix F Services | catalog.variant.crud.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /catalog/products/:id/variants |
A spreadsheet-like grid interface for managing variant products efficiently. Rows represent Dimension 1 values (e.g., sizes), columns represent Dimension 2 values (e.g., colors). Each cell shows price, cost, and stock level, enabling rapid inline editing and bulk variant creation.
| Element | Type | Description | Business Rule |
|---|
| Dimension config | Input | Up to 3 dimension names (e.g., Size, Color, Material) with ordered values | BRD 3.1.6 |
| Matrix grid | Table | Rows=Dim1, Cols=Dim2. Each cell: price / cost / stock. Click to edit inline. Tab navigates cells | BRD 3.1.6 |
| Add dimension value | Button | Add new size or color value — creates new variant row/column | BRD 3.1.6 |
| Bulk price update | Input | Set price/cost for entire row (size) or column (color) at once | BRD 3.1.6 |
| Changed cells highlight | Badge | Yellow highlight on modified cells until saved | BRD 3.1.6 |
| Save All Changes | Button | Persists all edits in one batch operation | BRD 3.1.6 |
| Generate barcodes | Button | Auto-generate internal barcodes for variants missing barcodes | BRD 3.4.2 |
| Variant active toggle | Input | Per-cell checkbox to activate/deactivate individual variants | BRD 3.1 |
| Action | Navigates To | Requires Role |
|---|
| Click “Save All Changes” | Stays on page; batch save all modified variants | MANAGER+ |
| Click variant SKU link | SCR-M03-02 Product Detail (variant tab focused) | MANAGER+ |
| Click “Generate Barcodes” | Stays on page; auto-generates internal barcodes for variants without barcodes | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-04 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.3.1, 3.3.2 |
| Database Tables | pricing_rules (RW), products (R), categories (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.pricing.crud.service, catalog.pricing.calculation.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/pricing |
Manages the 5-level price hierarchy (Manual Override > Promotion > Price Book > Channel > Base) and named price books. Staff create, edit, and schedule price books for specific customer groups, channels, or date ranges. Includes CSV bulk import of price book entries and conflict preview.
| Element | Type | Description | Business Rule |
|---|
| Price hierarchy diagram | Panel | Visual display of 5-level pricing cascade with current active rules count at each level | BRD 3.3.1 |
| Price books list | Table | Name, Customer Group, Channel, Start/End Date, Priority, Status (Active/Inactive), Entry Count | BRD 3.3.2 |
| Price book detail form | Modal | Name, description, customer_group_id, channel, start_date, end_date, priority, is_active | BRD 3.3.2 |
| Price book entries table | Table | SKU, Product Name, Override Price, Override Cost. Inline editable | BRD 3.3.2 |
| CSV import | Button | Upload CSV (sku, override_price, override_cost). Validates SKU existence and numeric formats | BRD 3.3.2 |
| Conflict checker | Panel | Preview which products have overlapping price books for same group/channel | BRD 3.3.5 |
| Price audit trail | Panel | Log of all price book activations, deactivations, and entry modifications | BRD 3.3.2 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Price Book” | Price book detail modal (create mode) | MANAGER+ |
| Click price book row | Price book detail modal (edit mode) with entries table | MANAGER+ |
| Click “Import CSV” | File upload dialog; validates and applies entries | MANAGER+ |
| Click “View Conflicts” | Conflict checker panel expands | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-05 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.3.3 |
| Database Tables | pricing_rules (RW), products (R), categories (R) |
| State Machine(s) | Promotion Lifecycle (DRAFT → SCHEDULED → ACTIVE → EXPIRED/CANCELLED) |
| Appendix F Services | catalog.pricing.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/promotions |
Creates and manages the four promotion types: Basic Discount, Tiered/Volume, BOGO/Cross-Item, and Scheduled/Automatic. Each promotion follows a lifecycle from DRAFT through ACTIVE to EXPIRED. Staff configure product scope, stacking rules, exclusivity, and date windows.
| Element | Type | Description | Business Rule |
|---|
| Promotions list | Table | Name, Type, Status, Start Date, End Date, Redemptions, Revenue Impact | BRD 3.3.3 |
| Promotion type selector | Input | BASIC, TIERED, BOGO, SCHEDULED — changes form fields dynamically | BRD 3.3.3 |
| Product scope selector | Input | ALL / CATEGORY / PRODUCT_LIST with category picker or product multi-select | BRD 3.3.3 |
| Tier editor | Panel | For TIERED type: min_qty, max_qty, price_per_unit rows. Add/remove tiers | BRD 3.3.3 |
| BOGO config | Panel | For BOGO: buy_product, buy_qty, get_product, get_qty, get_discount_type, get_discount_value | BRD 3.3.3 |
| Schedule config | Panel | For SCHEDULED: schedule_type (DATE_RANGE/RECURRING), recurrence_pattern | BRD 3.3.3 |
| Stacking rules | Input | stackable (boolean), exclusive (boolean). Combined discount cap = max_discount_percent (default 75%) | BRD 3.3.5 |
| Status badge | Badge | DRAFT (grey), SCHEDULED (blue), ACTIVE (green), EXPIRED (red), CANCELLED (dark) | BRD 3.3.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Promotion” | Promotion detail form (create mode) | MANAGER+ |
| Click “Schedule” on DRAFT | Stays on page; status → SCHEDULED, fields locked | MANAGER+ |
| Click “Cancel” on ACTIVE/SCHEDULED | Stays on page; status → CANCELLED (terminal) | MANAGER+ |
| Click “Clone” on EXPIRED | New promotion form pre-filled from source (DRAFT status) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-06 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.3.4 |
| Database Tables | pricing_rules (RW), products (RW), inventory_levels (R) |
| State Machine(s) | Markdown Request (PENDING → APPROVED/REJECTED) |
| Appendix F Services | catalog.markdown.command.service, catalog.pricing.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/markdowns |
Manages formal price reductions with approval workflows. Staff submit markdown requests specifying the product, new price, effective date, and reason. Managers review margin impact before approving. Also configures automatic markdown rules for slow-moving and aging inventory, and handles clearance tracking and write-offs.
| Element | Type | Description | Business Rule |
|---|
| Pending requests list | Table | Product, Current Price, Proposed Price, Margin Impact (%), Reason, Requested By, Date | BRD 3.3.4 |
| New markdown request form | Modal | Product picker, new_price, effective_date, reason (dropdown: Damaged, Price Match, Manager Discretion, Competitive Adjustment, Cost Change, Seasonal Reduction, Error Correction) | BRD 3.3.4 |
| Margin impact preview | Panel | Current margin vs. proposed margin, volume at each price point, total margin dollars change | BRD 3.3.4 |
| Auto-markdown rules | Table | Rule name, condition (Slow Mover/Aging/Season End), threshold, action (flag for review / apply immediately), status | BRD 3.3.4 |
| Clearance tracker | Table | Products flagged as clearance: product, original price, clearance price, days on clearance, units remaining, sell-through % | BRD 3.3.4 |
| Write-off form | Modal | Product, quantity, write_off_value (calculated), reason (DAMAGED/EXPIRED/RECALLED/SHRINKAGE/OBSOLETE), approved_by, location | BRD 3.3.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “Approve” on pending request | Stays on page; price change scheduled, pushed to POS terminals | MANAGER+ |
| Click “Reject” on pending request | Stays on page; rejection reason required, requester notified | MANAGER+ |
| Click “+ New Markdown Request” | New markdown request modal | CASHIER+ |
| Click “Configure Auto Rules” | Auto-markdown rules editor panel | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-07 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.3 |
| Database Tables | pricing_rules (RW), products (R), categories (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.pricing.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/coupons |
Creates and manages code-based discount coupons that cashiers enter at POS during checkout. Coupons are a special subset of promotions requiring manual code entry rather than automatic application. Staff configure discount type, usage limits, valid date ranges, and applicable products.
| Element | Type | Description | Business Rule |
|---|
| Coupon list | Table | Code, Name, Discount Type (% / $), Value, Max Uses, Current Uses, Status, Valid Dates | BRD 3.3 |
| Coupon detail form | Modal | Code (auto-generated or manual), name, discount_type (PERCENT/AMOUNT), discount_value, product_scope, max_uses, start_date, end_date | BRD 3.3 |
| Usage tracker | Panel | Redemption count, total discount given, revenue with coupon vs. without | BRD 3.3 |
| Product scope | Input | ALL / CATEGORY / PRODUCT_LIST — determines which products the coupon applies to | BRD 3.3 |
| Bulk generate | Button | Generate batch of unique single-use codes (e.g., 500 codes for campaign) | BRD 3.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Coupon” | Coupon detail modal | MANAGER+ |
| Click coupon row | Coupon detail modal (edit mode) | MANAGER+ |
| Click “Deactivate” | Stays on page; coupon disabled immediately | MANAGER+ |
| Click “Bulk Generate” | Bulk code generation modal | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-08 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.5.1, 3.5.3 |
| Database Tables | categories (RW), products (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.category.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/categories |
Manages the 4-level product category hierarchy (Department > Category > Subcategory > Sub-subcategory). Staff create, reorder, and nest categories using drag-and-drop. Each category can set default tax code, commission rate, and display image. Supports bulk product moves between categories.
| Element | Type | Description | Business Rule |
|---|
| Category tree | Panel | Expandable/collapsible 4-level tree with drag-and-drop reordering. Shows product count per node | BRD 3.5.1 |
| Category detail form | Panel | Name, parent category (dropdown), description, display_order, is_active, image/icon upload | BRD 3.5.1 |
| Default tax code | Input | Category-level default tax code inherited by products unless overridden | BRD 3.5.3 |
| Default commission rate | Input | Category-level commission % for sales commission calculation | BRD 3.5.3 |
| Product count | Badge | Number of products assigned to each category node | BRD 3.5.1 |
| Bulk move | Button | Select multiple products from list → move to different category | BRD 3.5.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Category” | Category detail form (create mode, parent pre-selected) | MANAGER+ |
| Click category node | Category detail form (edit mode) + product list filtered to category | MANAGER+ |
| Drag-and-drop category | Stays on page; reorders or re-nests category | MANAGER+ |
| Click “View Products” | SCR-M03-01 Product List (filtered to this category) | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-09 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.5.2 |
| Database Tables | tags (RW), product_tag (RW), collections (RW), product_collection (RW), products (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.tag.crud.service, catalog.collection.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/collections |
Manages freeform product tags and named collections (manual and rule-based). Tags provide flexible filtering; collections group products for marketing purposes (e.g., “Summer Essentials”, “New Arrivals”). Rule-based collections auto-populate based on configurable conditions like published_at date or category membership.
| Element | Type | Description | Business Rule |
|---|
| Tags list | Table | Tag name, color hex, product count. Inline create/edit/delete | BRD 3.5.2 |
| Tag color picker | Input | Hex color for UI display (validated #RRGGBB format) | Ch 08 tags table |
| Collections list | Table | Name, Type (Manual/Rule-Based), Product Count, Start Date, End Date, Status | BRD 3.5.2 |
| Collection detail form | Modal | Name, description, image, is_active, start_date, end_date | BRD 3.5.2 |
| Manual product assignment | Panel | Add/remove products via search or drag-and-drop with display_order | BRD 3.5.2 |
| Rule builder | Panel | For rule-based collections: IF conditions (category=X, published_at within last N days, tag=Y) THEN auto-include | BRD 3.5.2 |
| Auto-tagging rules | Table | Condition → Tag mappings (e.g., IF category=“Outerwear” AND created_at within 14 days THEN tag “new-outerwear”) | BRD 3.5.2 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Collection” | Collection detail modal | MANAGER+ |
| Click collection row | Collection detail modal (edit mode) with product list | MANAGER+ |
| Click “+ New Tag” | Inline tag creation row | MANAGER+ |
| Click “View Products” | SCR-M03-01 Product List (filtered by tag or collection) | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-10 |
| Product(s) | BUYER+ |
| BRD Section(s) | 3.5.5, 3.5.6 |
| Database Tables | products (R), collections (R), pricing_rules (R) |
| State Machine(s) | Season Lifecycle (PLANNING → ACTIVE → CLEARANCE → CLOSED) |
| Appendix F Services | catalog.collection.crud.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /catalog/seasons |
Manages formal buying seasons with lifecycle dates that track merchandise from buy planning through active selling, clearance, and close-out. Provides a calendar view of all seasons and enables sell-through tracking, carryover identification, and season-over-season comparison reporting.
| Element | Type | Description | Business Rule |
|---|
| Season calendar | Panel | Visual timeline showing all seasons with overlapping date ranges, color-coded by status | BRD 3.5.5 |
| Season list | Table | Name, Start Date, End Date, Status (PLANNING/ACTIVE/CLEARANCE/CLOSED), Product Count, Sell-Through % | BRD 3.5.5 |
| Season detail form | Modal | Name, start_date, end_date, status transition buttons | BRD 3.5.5 |
| Sell-through metrics | Panel | Units received, units sold, sell-through %, remaining inventory value, carryover count | BRD 3.5.6 |
| Season product list | Table | Products assigned to this season with sales performance per product | BRD 3.5.5 |
| Reporting dimensions | Panel | Department, Category, Brand, Season, Location multi-dimensional analysis | BRD 3.5.6 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Season” | Season detail modal | MANAGER+ |
| Click season row | Season detail modal with product list and metrics | MANAGER+ |
| Click “Move to Clearance” | Stays on page; status → CLEARANCE, triggers clearance pricing rules | MANAGER+ |
| Click “Close Season” | Stays on page; status → CLOSED (terminal), remaining inventory flagged as carryover | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-11 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.4 |
| Database Tables | products (RW), variants (RW) |
| State Machine(s) | — |
| Appendix F Services | catalog.barcode.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/barcodes |
Centralized barcode management for the entire catalog. Provides tools for bulk barcode import, auto-generation of internal barcodes, barcode coverage auditing, and scan failure log review. Supports UPC-A, EAN-13, and configurable internal barcode formats.
| Element | Type | Description | Business Rule |
|---|
| Barcode coverage summary | Panel | Total products, products with primary barcode, products with internal-only, products without barcode, coverage % | BRD 3.4.4 |
| Products without barcodes | Table | Products missing primary barcode — with bulk auto-generate option | BRD 3.4.2 |
| Bulk CSV import | Button | Upload CSV mapping barcodes to existing SKUs. Validates uniqueness, reports conflicts | BRD 3.4.2 |
| Internal barcode config | Panel | Prefix configuration (e.g., “INT-”), next sequence number preview | BRD 3.4.1 |
| Scan failure log | Table | Scanned value, timestamp, terminal, resolution (created new / manual lookup / abandoned) | BRD 3.4.4 |
| Duplicate barcode audit | Table | Barcode value, conflicting products, resolution status | BRD 3.4.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “Auto-Generate” on missing barcodes list | Stays on page; generates internal barcodes for selected products | MANAGER+ |
| Click “Import CSV” | File upload dialog with validation results | MANAGER+ |
| Click product row | SCR-M03-02 Product Detail (barcode section focused) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-12 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.6 |
| Database Tables | products (R), variants (R), inventory_levels (R), locations (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.product.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/channels |
Controls product visibility and inventory allocation across sales channels (IN_STORE, ONLINE, WHOLESALE). Supports two allocation modes: Shared Pool (all channels sell from same stock) and Dedicated Allocation (reserved quantities per channel). Enables bulk channel toggles and scheduled visibility windows.
| Element | Type | Description | Business Rule |
|---|
| Channel list | Table | Channel name, type (PHYSICAL/DIGITAL/B2B), is_default, product count, system flag | BRD 3.6.1 |
| Allocation mode selector | Input | Shared Pool (default) or Dedicated Allocation — tenant-wide setting | BRD 3.6.3 |
| Product-channel matrix | Table | Products as rows, channels as columns, toggles for visibility with optional date windows | BRD 3.6.2 |
| Dedicated allocation grid | Table | (Only in Dedicated mode) Product × Location × Channel: allocated_qty, sold_qty, available_qty | BRD 3.6.3 |
| Channel pricing overrides | Panel | Per-product per-channel price overrides and compare-at prices | BRD 3.6.4 |
| Bulk channel toggle | Button | Select multiple products → toggle channel visibility in batch | BRD 3.6.2 |
| Stockout warnings | Badge | “Channel Stockout” flag when a channel’s allocated qty reaches 0 | BRD 3.6.3 |
| Action | Navigates To | Requires Role |
|---|
| Toggle channel visibility | Stays on page; updates product-channel record | MANAGER+ |
| Click “Reallocate” | Modal to move allocated qty between channels | MANAGER+ |
| Click “Channel Reports” | SCR-M03-18 Product Analytics (channel tab) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-13 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.8 |
| Database Tables | brands (RW), products (R), purchase_orders (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.vendor.crud.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /catalog/vendors |
Manages supplier/vendor records including contact information, payment terms, lead times, and the many-to-many vendor-product relationship. Each product can be sourced from multiple vendors with vendor-specific cost, SKU, and lead time. Designates primary vendors for automatic PO generation.
| Element | Type | Description | Business Rule |
|---|
| Vendor list | Table | Name, Code, Status (Active/Inactive), Product Count, Payment Terms, Lead Time, Last PO Date | BRD 3.8.1 |
| Vendor detail form | Panel | Name, code, tax_id, contact (email, phone, address, contact_person), payment_terms, currency, minimum_order, lead_time_days, preferred_carrier | BRD 3.8.1 |
| Vendor-product table | Table | Product SKU, Vendor SKU, Vendor Cost, Is Primary, Lead Time Override, Min Order Qty, Last Ordered | BRD 3.8.2 |
| Primary vendor toggle | Input | Designate primary vendor per product (one per product enforced) | BRD 3.8.2 |
| Performance metrics | Panel | PO count, on-time %, avg lead time, fill rate, defect rate, cost variance | BRD 3.8.4 |
| Cost comparison | Table | Compare vendor pricing for same product across multiple vendors | BRD 3.8.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Vendor” | Vendor detail form (create mode) | MANAGER+ |
| Click vendor row | Vendor detail form (edit mode) with product list | MANAGER+ |
| Click “Create PO” | SCR-M04-04 PO Create (vendor pre-selected) | BUYER+ |
| Click “View RMAs” | SCR-M04-21 Vendor RMA (filtered to this vendor) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-14 |
| Product(s) | All Roles |
| BRD Section(s) | 3.10 |
| Database Tables | products (R), variants (R), pricing_rules (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.label.print.service |
| User Roles | ALL |
| Offline Capable | No — requires printer connection |
| Route | /catalog/labels |
Generates and prints barcode labels, price tags, and shelf labels for products. Supports multiple label types (price tag, shelf label, barcode-only) with configurable templates. Handles batch printing for new receiving, re-pricing, and routine label replacement.
| Element | Type | Description | Business Rule |
|---|
| Label type selector | Input | Price Tag (barcode + price + name), Shelf Label (category + price), Barcode Only (barcode + SKU) | BRD 3.10.1 |
| Template picker | Input | Predefined label dimensions: Avery 5160, Avery 5163, Dymo 30252, custom | BRD 3.10.2 |
| Product queue | Table | Products to print: SKU, Name, Variant, Price, Quantity of labels. Add via search, scan, or bulk select | BRD 3.10.3 |
| Label preview | Panel | Visual preview of label layout before printing | BRD 3.10.2 |
| Printer selector | Input | Available label printers (Zebra, Dymo, Brother) | BRD 3.10.3 |
| Print trigger indicators | Badge | Shows auto-print triggers: price change, new receiving, markdown applied | BRD 3.10.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “Print” | Sends print job to selected printer | ALL |
| Click “Add Products” | Search/scan dialog to add products to queue | ALL |
| Click “Print All Received” | Adds all products from most recent PO receive to queue | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-15 |
| Product(s) | BUYER+ |
| BRD Section(s) | 3.11 |
| Database Tables | products (RW), variants (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.media.crud.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/media |
Centralized media management for product images and videos. Provides bulk upload, drag-and-drop reordering, primary image designation, and variant-specific image assignment. Supports image optimization, CDN sync, and batch operations across multiple products.
| Element | Type | Description | Business Rule |
|---|
| Media gallery grid | Panel | Thumbnail grid of all product images with product name overlay. Drag-and-drop reorder | BRD 3.11.1 |
| Upload zone | Panel | Drag-and-drop or file picker for bulk image upload. Supports JPG, PNG, WebP | BRD 3.11.1 |
| Primary image selector | Button | Star icon to designate primary display image per product | BRD 3.11.1 |
| Variant image assignment | Panel | Assign specific images to specific variants (e.g., blue shirt photo → Blue variant) | BRD 3.11.1 |
| Video URLs | Input | External video URLs (YouTube, Vimeo) linked to products | BRD 3.11.2 |
| Sync status | Badge | CDN sync status per image: synced, pending, error | BRD 3.11.3 |
| Products without images | Table | Products missing primary image — filter for quick remediation | BRD 3.11.1 |
| Action | Navigates To | Requires Role |
|---|
| Click product thumbnail | SCR-M03-02 Product Detail (media tab) | MANAGER+ |
| Drag-and-drop images | Stays on page; reorders image display priority | MANAGER+ |
| Click “Bulk Upload” | File picker for multi-file upload | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-16 |
| Product(s) | OWNER |
| BRD Section(s) | 3.12, 5.12 |
| Database Tables | products (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.notes.crud.service, setup.customfield.crud.service |
| User Roles | OWNER |
| Offline Capable | No |
| Route | /catalog/custom-fields |
Configures tenant-defined custom attribute definitions that extend the standard product data model. Allows creating TEXT, NUMBER, LIST, and BOOLEAN fields with validation rules. Custom fields appear on the product edit form and can be made searchable, filterable, and required.
| Element | Type | Description | Business Rule |
|---|
| Custom fields list | Table | Name, Type (TEXT/NUMBER/LIST/BOOLEAN), Required, Searchable, Filterable, Display Order, Usage Count | BRD 3.1.4 |
| Field definition form | Modal | name, type, list_values[] (for LIST type), required, searchable, filterable, display_order | BRD 3.1.4 |
| List values editor | Panel | For LIST type: ordered list of allowed values with add/remove | BRD 3.1.4 |
| Field limit indicator | Badge | “X / 50 custom fields defined” — shows limit enforcement | BRD 3.1.4 (max 50 per tenant) |
| Usage preview | Panel | Shows where field appears: product form position, search index status, filter sidebar inclusion | BRD 3.1.4 |
| Structured notes config | Panel | Note types (INTERNAL, VENDOR, COMPLIANCE) and file attachment settings (max size, allowed types) | BRD 3.12.1, 3.12.2 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Field” | Field definition modal | OWNER |
| Click field row | Field definition modal (edit mode) | OWNER |
| Click “Archive” on field | Stays on page; field hidden from form but preserved in historical data | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-17 |
| Product(s) | All Roles |
| BRD Section(s) | 3.9 |
| Database Tables | products (R), variants (R), categories (R), inventory_levels (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.search.service |
| User Roles | ALL |
| Offline Capable | Yes (POS: searches product_cache SQLite table with degraded fuzzy matching) |
| Route | /pos/search (POS context) |
POS-optimized product search and discovery interface. Provides category browsing tiles, quick-add favorites grid, barcode scanner integration, and product substitution suggestions. Designed for cashier speed with large touch targets and instant results (<200ms).
| Element | Type | Description | Business Rule |
|---|
| Search bar | Input | Full-text search with auto-complete, fuzzy matching, recent searches. Barcode scanner auto-submit | BRD 3.9.1 |
| Category browse tiles | Panel | Top-level categories as large touch tiles. Tap to drill into subcategories | BRD 3.9.2 |
| Quick-add favorites | Panel | Configurable grid of frequently sold products per staff member. One-tap to add to cart | BRD 3.9.4 |
| Search results grid | Panel | Product cards: image, name, price, stock level, variant indicator. Tap to add or view variants | BRD 3.9.1 |
| Substitution suggestions | Panel | When product is out of stock, shows similar alternatives with stock availability | BRD 3.9.5 |
| Advanced filters | Panel | Category, Brand, Price Range, In-Stock Only, Tags. Collapsible sidebar | BRD 3.9.3 |
| Recent searches | Panel | Last 10 searches with result count, re-execute on tap | BRD 3.9.1 |
| Action | Navigates To | Requires Role |
|---|
| Tap product card | Adds product to cart (sales terminal) or navigates to detail (management view) | ALL |
| Tap variant indicator | Variant selector modal (size/color picker) | ALL |
| Tap category tile | Drills into subcategory product list | ALL |
| Tap substitution | Adds substitute product to cart | ALL |
| Tap “Manage Favorites” | Quick-add favorites editor (personal per user) | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-M03-18 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 3.14 |
| Database Tables | products (R), variants (R), inventory_levels (R), inventory_transactions (R), pricing_rules (R) |
| State Machine(s) | — |
| Appendix F Services | catalog.analytics.query.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /catalog/analytics |
Comprehensive product performance analytics dashboard. Displays embedded product metrics (velocity, margin, sell-through), ABC classification analysis, and catalog-wide KPIs. Enables data-driven decisions on pricing, restocking, and product lifecycle management.
| Element | Type | Description | Business Rule |
|---|
| KPI summary cards | Panel | Total SKUs, Active Products, Avg Margin %, Top Seller (7d), Worst Performer (7d), New Products (30d) | BRD 3.14.3 |
| ABC classification chart | Panel | Pareto chart showing A (top 20% revenue), B (next 30%), C (bottom 50%) products. Interactive click-through | BRD 3.14.2 |
| Sales velocity heatmap | Panel | Product × Location matrix with color-coded sales velocity (hot/warm/cold) | BRD 3.14.1 |
| Margin analysis table | Table | Product, Sell Price, WAC, Gross Margin $, Gross Margin %, Units Sold, Total Margin. Sortable | BRD 3.14.1 |
| Pricing report | Table | Price book usage, promotion performance, markdown history, conflict resolution log | BRD 3.3.6 |
| Category sales breakdown | Panel | Revenue by category hierarchy with drill-down | BRD 3.5.4 |
| Channel comparison | Panel | Channel revenue, units, margin side-by-side comparison chart | BRD 3.6.5 |
| Date range selector | Input | 7d, 30d, 90d, custom range for all metrics | BRD 3.14 |
| Export | Button | CSV and PDF export of all analytics data | BRD 3.14.4 |
| Action | Navigates To | Requires Role |
|---|
| Click product in ABC chart | SCR-M03-02 Product Detail | MANAGER+ |
| Click category in breakdown | SCR-M03-01 Product List (filtered to category) | MANAGER+ |
| Click “Export Report” | Downloads CSV or PDF | MANAGER+ |
| Click velocity cell | SCR-M04-02 Inventory List (filtered to product + location) | MANAGER+ |
BRD Sections: 4.1-4.19 | Appendix F: §F.7 (23 services) | Pattern: Materialized + ES Audit Trail
Cross-Reference: See Ch 05, Sections 4.1-4.19 for business rules. See Ch 08, Domain 3 (Inventory) for table schemas. See Appendix F, §F.7 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M04-01 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.17 |
| Database Tables | inventory_levels (R), inventory_transactions (R), purchase_orders (R), transfer_orders (R), locations (R), products (R), variants (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.dashboard.projection.service, inventory.report.query.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/dashboard |
At-a-glance inventory health overview with eight KPI cards, trend indicators, and drill-down links to detailed reports. Provides multi-location summary with filters for location, category, brand, and date range. Serves as the primary inventory management landing page.
| Element | Type | Description | Business Rule |
|---|
| Total Inventory Value (WAC) | Panel | Sum of (available_qty x WAC) across all locations. 30-day trend arrow + % change | BRD 4.17.1 |
| Low Stock Items | Panel | Count of products where available_qty <= reorder_point. Delta from prior week | BRD 4.17.1 |
| Pending PO Count | Panel | Count of POs in OPEN/PARTIAL status with total pending PO value | BRD 4.17.1 |
| Open Transfers | Panel | Count of transfers in REQUESTED/APPROVED/PICKING/SHIPPED status with in-transit items count | BRD 4.17.1 |
| Upcoming Counts | Panel | Count of scheduled counts in next 7 days with next count date and type | BRD 4.17.1 |
| Shrinkage % | Panel | (Total variance value / Total inventory value) x 100 for last 30 days vs. prior period | BRD 4.17.1 |
| Dead Stock Count | Panel | Products with zero sales velocity in last 90 days. Delta from prior month | BRD 4.17.1 |
| Avg Days of Supply | Panel | Average days_of_supply across active products. Top 3 categories with lowest supply | BRD 4.17.1 |
| Dashboard filters | Input | Location (All/specific), Category, Date Range, Brand | BRD 4.17.1 |
| Active alerts feed | Panel | Recent LOW_STOCK, OVERSTOCK, SHRINKAGE, AGING_INVENTORY, PO_OVERDUE alerts | BRD 4.16.1 |
┌─────────────────────────────────────────────────────────────────────────┐
│ INVENTORY DASHBOARD [All Locations ▼] [30 Days ▼] │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌──────────┐ │
│ │ TOTAL VALUE │ │ LOW STOCK │ │ PENDING POs │ │ OPEN │ │
│ │ $847,230 ▲2% │ │ 23 items ▼3 │ │ 8 POs ($12.4K) │ │ XFERS: 5 │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ └──────────┘ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌──────────┐ │
│ │ UPCOMING COUNTS │ │ SHRINKAGE % │ │ DEAD STOCK │ │ AVG DAYS │ │
│ │ 2 (next: Mon) │ │ 1.2% ▼0.3% │ │ 15 items ▲2 │ │ SUPPLY │ │
│ │ │ │ │ │ │ │ 42 days │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ ACTIVE ALERTS [View All →] │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ ● CRITICAL Shrinkage 8.2% on CNT-2026-00031 at Store A │ │
│ │ ▲ WARNING Low Stock: 23 items below reorder point at Store B │ │
│ │ ▲ WARNING PO #PO-2026-00042 overdue by 3 days (Vendor: Nike) │ │
│ │ ○ INFO Overstock: 12 items >90 days supply at HQ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ INVENTORY BY LOCATION │
│ ┌──────────┬──────────┬──────────┬──────────┬──────────┐ │
│ │ Store GM │ Store HM │ Store LM │ Store NM │ HQ (WH) │ │
│ │ $182K │ $165K │ $158K │ $147K │ $195K │ │
│ │ 1,245 SKU│ 1,180 SKU│ 1,090 SKU│ 1,050 SKU│ 1,420 SKU│ │
│ │ 3 low ▲ │ 5 low ▼ │ 8 low ▲ │ 4 low ─ │ 3 low ▼ │ │
│ └──────────┴──────────┴──────────┴──────────┴──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Low Stock Items” KPI | SCR-M04-03 Low Stock Alerts | MANAGER+ |
| Click “Pending POs” KPI | SCR-M04-05 PO Approval / Track | BUYER+ |
| Click “Open Transfers” KPI | SCR-M04-17 Transfer Create / Track | MANAGER+ |
| Click “Upcoming Counts” KPI | SCR-M04-09 Stock Count Session | MANAGER+ |
| Click location card | SCR-M04-02 Inventory List (filtered to location) | MANAGER+ |
| Click alert row | Navigates to relevant detail screen based on alert type | MANAGER+ |
| Click “View All Reports” | SCR-M04-22 Inventory Reports | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-02 |
| Product(s) | All Roles |
| BRD Section(s) | 4.1, 4.2 |
| Database Tables | inventory_levels (R), products (R), variants (R), locations (R) |
| State Machine(s) | Inventory Status (AVAILABLE, QUARANTINE, DAMAGED, PENDING_INSPECTION, RESERVED, IN_TRANSIT) |
| Appendix F Services | inventory.level.query.service, inventory.status-model.service |
| User Roles | ALL |
| Offline Capable | Yes (POS: reads from product_cache SQLite table; shows cached on_hand qty) |
| Route | /inventory/levels |
Displays current stock quantities for all products at a selected location, broken down by inventory status (Available, Reserved, In-Transit, Quarantine, Damaged). Shows the computed available quantity (on_hand - committed - reserved) and visual indicators for low stock and reorder point thresholds.
| Element | Type | Description | Business Rule |
|---|
| Location selector | Input | Dropdown to select location. Default: user’s assigned location | BRD 4.1 |
| Inventory table | Table | SKU, Product Name, Variant, Available, Reserved, In-Transit, Quarantine, Damaged, On-Hand (total), Reorder Point, WAC | BRD 4.1.5 |
| Status breakdown | Panel | Per-row expandable showing qty by each status with last_status_change_at | BRD 4.2.1 |
| Low stock indicator | Badge | Red/amber badge when available_qty <= reorder_point | BRD 4.5 |
| Min display qty warning | Badge | Advisory badge when available_qty < min_display_qty. Suggests transfer from location with highest stock | BRD 4.2.4 |
| Filters | Panel | Category, Brand, Stock Status (All/Low/Out/Overstock), Search by SKU/Name | BRD 4.1 |
| Balance equation | Panel | Header showing: Available = On-Hand - Reserved - In-Transit - Quarantine - Damaged | BRD 4.1.5 |
| Export | Button | CSV export of current inventory snapshot | BRD 4.17.2 |
| Action | Navigates To | Requires Role |
|---|
| Click product row | Product inventory detail (movement history for this product+location) | ALL |
| Click “New Adjustment” | SCR-M04-15 Adjustment Request (product pre-selected) | CASHIER+ |
| Click “Request Transfer” | SCR-M04-17 Transfer Create (destination pre-selected) | MANAGER+ |
| Click “Create Count” | SCR-M04-09 Stock Count Session (location pre-selected) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-03 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.16 |
| Database Tables | inventory_levels (R), products (R), variants (R), locations (R), purchase_orders (R) |
| State Machine(s) | Alert Lifecycle (TRIGGERED → ACKNOWLEDGED → RESOLVED) |
| Appendix F Services | inventory.alert.service, inventory.reorder.engine.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/alerts |
Displays all active inventory alerts across five types: Low Stock, Overstock, Shrinkage Threshold, Aging Inventory, and PO Overdue. Provides acknowledge/resolve workflow, auto-resolution tracking, and one-click actions to create POs or transfers from alert context.
| Element | Type | Description | Business Rule |
|---|
| Alert tabs | Panel | Tabs: All, Low Stock, Overstock, Shrinkage, Aging, PO Overdue. Count badges per tab | BRD 4.16.1 |
| Alert list | Table | Alert Type, Severity (CRITICAL/WARNING/INFO), Product, Location, Message, Triggered At, Status, Acknowledged By | BRD 4.16.2 |
| Severity indicators | Badge | Red=CRITICAL, Amber=WARNING, Blue=INFO | BRD 4.16.1 |
| Data snapshot | Panel | Expandable per alert showing key metrics at alert time (e.g., available_qty, reorder_point) | BRD 4.16.2 |
| One-click actions | Button | “Create PO” (for low stock), “Create Transfer” (for overstock/imbalance), “View Count” (for shrinkage) | BRD 4.16.1 |
| Acknowledge button | Button | Mark alert as acknowledged — staff is aware and working on it | BRD 4.16.3 |
| Auto-resolved indicator | Badge | Shows when alert was auto-resolved (e.g., stock received, sale occurred) | BRD 4.16.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “Create PO” on low stock alert | SCR-M04-04 PO Create (product + vendor pre-filled) | BUYER+ |
| Click “Create Transfer” | SCR-M04-17 Transfer Create (product pre-filled) | MANAGER+ |
| Click “Acknowledge” | Stays on page; alert status → ACKNOWLEDGED | MANAGER+ |
| Click “View Count” on shrinkage alert | SCR-M04-13 Count Results Review (count session linked) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-04 |
| Product(s) | BUYER+ |
| BRD Section(s) | 4.3 |
| Database Tables | purchase_orders (RW), purchase_order_items (RW), products (R), variants (R), brands (R), locations (R) |
| State Machine(s) | PO Lifecycle (DRAFT → PENDING_APPROVAL → SUBMITTED → PARTIALLY_RECEIVED → FULLY_RECEIVED → CLOSED / CANCELLED) |
| Appendix F Services | inventory.po.command.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/purchase-orders/new, /inventory/purchase-orders/:id/edit |
Creates and edits purchase orders for inventory replenishment. Staff select a vendor, add line items with quantities and costs, set expected delivery dates, and submit for approval or directly to the vendor. Supports auto-generation from reorder alerts and PO templates.
| Element | Type | Description | Business Rule |
|---|
| PO header | Panel | PO number (auto: PO-YYYY-NNNNN), Vendor selector, Destination Location, Expected Date, Notes | BRD 4.3.4 |
| Vendor product picker | Panel | Shows vendor’s product catalog with vendor SKU, vendor cost, lead time. Search + filter | BRD 4.3.3 |
| Line items table | Table | Product, Variant, Vendor SKU, Qty Ordered, Unit Cost, Line Total. Inline editable | BRD 4.3.5 |
| PO summary | Panel | Line count, subtotal, tax_amount, shipping_cost, total_amount | BRD 4.3.4 |
| Approval indicator | Badge | Shows if PO total exceeds auto-approve threshold ($2,000 default). “Requires Manager Approval” warning | BRD 4.3.2 |
| Auto-generated flag | Badge | “Auto-Generated” badge if created by reorder engine | BRD 4.5.2 |
| Status bar | Panel | Current status badge + available actions based on state | BRD 4.3.1 |
| Landed cost section | Panel | Freight, duties, customs, handling fields. Allocation method selector (BY_UNIT/BY_VALUE/BY_WEIGHT) | BRD 4.11.1 |
┌─────────────────────────────────────────────────────────────────────────┐
│ PURCHASE ORDER: PO-2026-00042 [DRAFT ○] [Save] │
├─────────────────────────────────────────────────────────────────────────┤
│ Vendor: [Nike USA ▼] Destination: [HQ Warehouse ▼] │
│ Expected: [2026-03-15 📅] Notes: [Spring restock order ] │
│ ⚠ Total exceeds $2,000 — Manager approval required on submit │
├─────────────────────────────────────────────────────────────────────────┤
│ LINE ITEMS [+ Add Product] │
│ ┌─────┬──────────────────────┬────────┬─────┬──────────┬─────────────┐ │
│ │ # │ Product / Variant │ V-SKU │ Qty │ Unit Cost│ Line Total │ │
│ ├─────┼──────────────────────┼────────┼─────┼──────────┼─────────────┤ │
│ │ 1 │ Oxford Shirt - S/Blu │ NK-4401│ 20 │ $12.00 │ $240.00 │ │
│ │ 2 │ Oxford Shirt - M/Blu │ NK-4402│ 30 │ $12.00 │ $360.00 │ │
│ │ 3 │ Oxford Shirt - L/Blu │ NK-4403│ 25 │ $12.00 │ $300.00 │ │
│ │ 4 │ Oxford Shirt - XL/Bl │ NK-4404│ 15 │ $13.00 │ $195.00 │ │
│ │ 5 │ Classic Polo - M/Wht │ NK-5501│ 40 │ $10.00 │ $400.00 │ │
│ │ 6 │ Classic Polo - L/Wht │ NK-5502│ 35 │ $10.00 │ $350.00 │ │
│ └─────┴──────────────────────┴────────┴─────┴──────────┴─────────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ COST ALLOCATION │ SUMMARY │
│ Freight: [$500.00 ] │ Subtotal: $1,845.00 │
│ Duties: [$300.00 ] │ Tax: $0.00 │
│ Customs: [$100.00 ] │ Shipping: $500.00 │
│ Handling: [$80.00 ] │ ──────────────────────── │
│ Method: [BY_UNIT ▼] │ Total: $2,345.00 │
├─────────────────────────────────────────────────────────────────────────┤
│ [Save Draft] [Submit to Vendor ▶] [Cancel] │
└─────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Save Draft” | Stays on page; PO saved as DRAFT | BUYER+ |
| Click “Submit to Vendor” | If total <= threshold: status → SUBMITTED. If > threshold: status → PENDING_APPROVAL | BUYER+ |
| Click “Cancel PO” | Stays on page; status → CANCELLED | MANAGER+ |
| Click vendor name | SCR-M03-13 Vendor Management (vendor detail) | MANAGER+ |
| Click “Use Template” | SCR-M04-06 PO Templates (select and apply) | BUYER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-05 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.3 |
| Database Tables | purchase_orders (RW), purchase_order_items (R), brands (R), locations (R) |
| State Machine(s) | PO Lifecycle (DRAFT → PENDING_APPROVAL → SUBMITTED → PARTIALLY_RECEIVED → FULLY_RECEIVED → CLOSED / CANCELLED) |
| Appendix F Services | inventory.po.command.service, inventory.po.query.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/purchase-orders |
Lists all purchase orders with status tracking, filtering, and approval workflow. Managers review and approve/reject POs exceeding the auto-approve threshold. Buyers track PO status from submission through receiving. Shows overdue PO alerts and expected delivery timelines.
| Element | Type | Description | Business Rule |
|---|
| PO list | Table | PO Number, Vendor, Status, Location, Order Date, Expected Date, Total Value, Received %, Overdue flag | BRD 4.3 |
| Status filter tabs | Panel | All, Draft, Pending Approval, Submitted, Partially Received, Fully Received, Closed, Cancelled | BRD 4.3.1 |
| Approval queue | Panel | POs in PENDING_APPROVAL status with Approve/Reject buttons. Shows PO total vs. threshold | BRD 4.3.2 |
| Overdue indicator | Badge | Red badge when expected_date passed and status is SUBMITTED/PARTIALLY_RECEIVED | BRD 4.3.6 |
| PO detail drawer | Panel | Slide-out panel showing full PO header + line items + receiving history | BRD 4.3 |
| Timeline view | Panel | Visual timeline of PO state transitions with timestamps and actors | BRD 4.3.1 |
| Action | Navigates To | Requires Role |
|---|
| Click “Approve” on pending PO | Stays on page; PO status → SUBMITTED | MANAGER+ |
| Click “Reject” on pending PO | Rejection reason modal; PO status → REJECTED → DRAFT (for revision) | MANAGER+ |
| Click PO row | SCR-M04-04 PO Create/Edit (read-only if not DRAFT) | BUYER+ |
| Click “Receive” | SCR-M04-07 Receiving & Inspection (PO pre-selected) | CASHIER+ |
| Click “+ New PO” | SCR-M04-04 PO Create | BUYER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-06 |
| Product(s) | BUYER+ |
| BRD Section(s) | 4.3 |
| Database Tables | purchase_orders (R), purchase_order_items (R), brands (R), products (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.po.command.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/purchase-orders/templates |
Manages reusable purchase order templates for recurring vendor orders. Templates store pre-configured vendor, product line items, and default quantities, allowing staff to create new POs from templates with one click. Reduces repetitive data entry for routine restocking.
| Element | Type | Description | Business Rule |
|---|
| Template list | Table | Template Name, Vendor, Product Count, Last Used, Created By | BRD 4.3 |
| Template detail form | Panel | Name, Vendor (locked), line items (product, default qty, unit cost) | BRD 4.3 |
| “Use Template” button | Button | Creates a new DRAFT PO pre-filled from template. Staff can modify before submitting | BRD 4.3 |
| Save as template | Button | Save current PO as reusable template (strips PO-specific dates and numbers) | BRD 4.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “Use Template” | SCR-M04-04 PO Create (pre-filled from template) | BUYER+ |
| Click template row | Template detail form (edit mode) | MANAGER+ |
| Click “+ New Template” | Template detail form (create mode) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-07 |
| Product(s) | All Roles |
| BRD Section(s) | 4.4 |
| Database Tables | purchase_orders (RW), purchase_order_items (RW), inventory_levels (RW), inventory_transactions (RW), products (R), variants (R) |
| State Machine(s) | PO Lifecycle (SUBMITTED → PARTIALLY_RECEIVED → FULLY_RECEIVED) |
| Appendix F Services | inventory.receiving.command.service |
| User Roles | CASHIER, MANAGER, OWNER |
| Offline Capable | No — inventory updates require server |
| Route | /inventory/receiving |
Processes inbound inventory from four source types: PO shipments, inter-store transfers, customer returns (return-to-stock), and vendor RMA replacements. Staff scan or enter received quantities, inspect items, flag discrepancies, and confirm receipt. Inventory is incremented and WAC is recalculated on confirmation.
| Element | Type | Description | Business Rule |
|---|
| Source type selector | Input | PO Receive / Transfer Receive / Return-to-Stock / RMA Replacement | BRD 4.4.1 |
| PO/Transfer picker | Input | Select open PO or in-transit transfer to receive against | BRD 4.4 |
| Line items table | Table | Product, Variant, Ordered Qty, Previously Received, Receiving Now, Discrepancy. Scanner-primary input | BRD 4.4.3 |
| Scanner mode | Panel | Barcode scanner auto-increments received qty per scan. Manual entry fallback | BRD 4.4.9 |
| Inspection checklist | Panel | Per-line inspection: condition (GOOD/DAMAGED/WRONG_ITEM), notes | BRD 4.4 |
| Non-PO receive | Panel | Receive without PO: mandatory reason code (sample, gift, found, correction) | BRD 4.4.6 |
| Open receive mode | Panel | Allows receiving items not on the PO — flags as unexpected and requires reason | BRD 4.4.4 |
| WAC recalculation preview | Panel | Shows current WAC, new landed cost, and projected new WAC after receive | BRD 4.11.2 |
| Action | Navigates To | Requires Role |
|---|
| Click “Confirm Receive” | Stays on page; inventory incremented, WAC recalculated, PO status updated | CASHIER+ |
| Click “Report Discrepancy” | SCR-M04-08 Receiving Variance (pre-filled) | CASHIER+ |
| Click “Print Labels” | SCR-M03-14 Label Printing (received products queued) | ALL |
| Click “View PO” | SCR-M04-04 PO Create/Edit (read-only) | BUYER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-08 |
| Product(s) | All Roles |
| BRD Section(s) | 4.4.5, 4.4.7 |
| Database Tables | purchase_orders (R), purchase_order_items (R), inventory_transactions (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.receiving.command.service |
| User Roles | CASHIER, MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/receiving/:id/variance |
Handles discrepancies between ordered/expected quantities and actually received quantities. Supports the triple approach: log a note (minor variance), auto-draft an RMA (defective items), or quarantine items for further inspection. Also manages over-shipment decisions (keep, return, or quarantine).
| Element | Type | Description | Business Rule |
|---|
| Variance summary | Table | Product, Ordered Qty, Received Qty, Variance (+/-), Variance %, Resolution | BRD 4.4.5 |
| Resolution actions | Input | Per-line: Note Only / Draft RMA / Quarantine. Default based on variance type | BRD 4.4.5 |
| Over-shipment handler | Panel | For positive variances: Accept & Add to Inventory / Return to Vendor / Quarantine for Review | BRD 4.4.7 |
| Condition notes | Input | Free-text notes per variance line explaining the discrepancy | BRD 4.4.5 |
| Auto-RMA draft | Button | Creates draft RMA for defective items detected during receiving | BRD 4.4.5 |
| Variance history | Table | Historical receiving variances by vendor for performance tracking | BRD 4.17.2 |
| Action | Navigates To | Requires Role |
|---|
| Click “Create RMA” for defective variance | SCR-M04-21 Vendor RMA (pre-filled from variance data) | MANAGER+ |
| Click “Accept Over-Shipment” | Stays on page; inventory incremented for excess qty | MANAGER+ |
| Click “Quarantine” | Stays on page; items moved to QUARANTINE status | MANAGER+ |
| Click “Save & Close” | Returns to SCR-M04-07 Receiving | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-09 |
| Product(s) | All Roles |
| BRD Section(s) | 4.6 |
| Database Tables | inventory_levels (R), inventory_transactions (R), products (R), variants (R), locations (R) |
| State Machine(s) | Count Lifecycle (CREATED → IN_PROGRESS → REVIEW → APPROVED / CANCELLED) |
| Appendix F Services | inventory.count.command.service, inventory.count.query.service |
| User Roles | MANAGER, OWNER (create); CASHIER+ (count) |
| Offline Capable | Partial (POS: scanner counting can work offline; sync on reconnect) |
| Route | /inventory/counts/:id |
Primary interface for conducting physical inventory counts. Managers create count sessions specifying type, location, scope, and mode (Freeze/Snapshot). Staff perform scanner-primary counting or manual entry. The screen tracks progress, shows expected vs. counted quantities, and handles the complete count lifecycle.
| Element | Type | Description | Business Rule |
|---|
| Count header | Panel | Count number (CNT-YYYY-NNNNN), type (Full/Cycle/Scanner/Monthly/On-Demand), location, mode (FREEZE/SNAPSHOT), scope, status, assigned_to | BRD 4.6.2 |
| Mode indicator | Badge | FREEZE: “Sales Suspended at This Location” warning. SNAPSHOT: “Sales continue — reconciled at review” | BRD 4.6.4 |
| Count entry table | Table | Product, Variant, Expected Qty, Counted Qty, Variance, Variance %, Count Method (Scanner/Manual), Notes | BRD 4.6.3 |
| Scanner input | Panel | Active barcode scanner listener. Each scan increments counted_qty by 1. Beep + product name confirmation | BRD 4.6.5 |
| Manual entry toggle | Button | Switch to manual qty entry for items with damaged/missing barcodes | BRD 4.6.5 |
| Section progress | Panel | For scoped counts: progress bar showing sections/categories completed vs. remaining | BRD 4.6.1 |
| Unrecognized barcode handler | Modal | “Unknown barcode — search product manually?” with product search | BRD 4.6.5 |
| Out-of-scope warning | Badge | Products scanned that are not in count scope — option to add | BRD 4.6.5 |
┌─────────────────────────────────────────────────────────────────────────┐
│ STOCK COUNT: CNT-2026-00031 [IN_PROGRESS ●] [FREEZE MODE ⚠] │
│ Location: Store A | Type: Cycle Count | Scope: Men's Tops │
│ Assigned: Sarah M. | Started: 2026-03-01 08:15 │
├─────────────────────────────────────────────────────────────────────────┤
│ ⚠ FREEZE MODE ACTIVE — Sales suspended at Store A │
├─────────────────────────────────────────────────────────────────────────┤
│ SCANNER INPUT: [Scan barcode or type SKU... ] [Manual Mode] │
│ Last scan: "Classic Oxford Shirt - M/Blue" → Count: 23 │
├─────────────────────────────────────────────────────────────────────────┤
│ SECTION PROGRESS: Men's Tops [████████░░░░] 67% │
│ ┌──────────────────────┬──────┬─────────┬──────────┬──────┬─────────┐ │
│ │ Product / Variant │ Exp. │ Counted │ Variance │ Var% │ Method │ │
│ ├──────────────────────┼──────┼─────────┼──────────┼──────┼─────────┤ │
│ │ Oxford Shirt - S/Blu │ 15 │ 14 │ -1 │ -6.7%│ Scanner │ │
│ │ Oxford Shirt - M/Blu │ 22 │ 23 │ +1 │ +4.5%│ Scanner │ │
│ │ Oxford Shirt - L/Blu │ 18 │ 18 │ 0 │ 0.0%│ Scanner │ │
│ │ Oxford Shirt - XL/Bl │ 8 │ 6 │ -2 │ -25%│ Scanner │ │
│ │ Classic Polo - S/Wht │ 12 │ -- │ -- │ -- │ Pending │ │
│ │ Classic Polo - M/Wht │ 20 │ -- │ -- │ -- │ Pending │ │
│ │ Classic Polo - L/Wht │ 15 │ -- │ -- │ -- │ Pending │ │
│ └──────────────────────┴──────┴─────────┴──────────┴──────┴─────────┘ │
├─────────────────────────────────────────────────────────────────────────┤
│ Counted: 4/7 items | Total scans: 61 | High variance: 1 item │
├─────────────────────────────────────────────────────────────────────────┤
│ [Save Progress] [Submit for Review ▶] [Cancel] │
└─────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click “Submit for Review” | SCR-M04-13 Count Results Review (auto-navigates) | CASHIER+ |
| Click “Save Progress” | Stays on page; progress saved, count remains IN_PROGRESS | CASHIER+ |
| Click “Cancel” | Stays on page; confirmation dialog. Status → CANCELLED. If FREEZE: sales resume | MANAGER+ |
| Scan barcode | Stays on page; increments counted_qty for matched product | CASHIER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-10 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.6.4 |
| Database Tables | inventory_levels (R), locations (R), products (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.count.command.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/counts/freeze |
Manages the FREEZE mode for inventory counts, controlling which locations have sales suspended during counting. Shows active freezes across all locations, provides ability to release freeze early, and manages queued transfers that are held until count completion.
| Element | Type | Description | Business Rule |
|---|
| Active freezes list | Table | Location, Count ID, Count Type, Start Time, Duration, Status, Queued Transfers count | BRD 4.6.4 |
| Freeze impact preview | Panel | Before starting freeze: estimated duration, expected revenue impact, affected terminals count | BRD 4.6.4 |
| Queued transfers | Table | Transfers held during freeze — to/from the frozen location | BRD 4.6.4 |
| POS terminal status | Panel | Per-terminal display at frozen location: “Count Mode — Sales Suspended” message active | BRD 4.6.4 |
| Emergency release | Button | Release freeze early — requires reason. Queued transfers process immediately | BRD 4.6.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “Release Freeze” | Stays on page; sales resume at location, queued transfers process | MANAGER+ |
| Click count row | SCR-M04-09 Stock Count Session | MANAGER+ |
| Click queued transfer | SCR-M04-17 Transfer Create/Track (transfer detail) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-11 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 4.6.5 |
| Database Tables | inventory_levels (R), products (R), variants (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.count.command.service |
| User Roles | ALL |
| Offline Capable | Yes (counts stored locally; synced when online) |
| Route | /pos/count/:id |
POS-optimized barcode scanning interface for inventory counting. Designed for handheld scanner use with large text, audio feedback, and minimal interaction. Each scan increments the count by 1. Supports fallback to manual entry for items with damaged barcodes.
| Element | Type | Description | Business Rule |
|---|
| Scanner listener | Panel | Active barcode input field. Auto-focus. Each scan: beep + product name + running count | BRD 4.6.5 |
| Running count display | Panel | Large font: “Product XYZ: 23 counted” with +1 animation on each scan | BRD 4.6.5 |
| Count progress | Panel | Items counted vs. total expected items. Progress bar | BRD 4.6.5 |
| Manual entry mode | Button | Switch to keyboard qty input for specific product | BRD 4.6.5 |
| Unknown barcode modal | Modal | Product search by SKU/name when barcode not recognized | BRD 4.6.5 |
| Count summary | Panel | Total scans, unique products counted, estimated completion % | BRD 4.6.5 |
| Action | Navigates To | Requires Role |
|---|
| Click “Submit for Review” | SCR-M04-13 Count Results Review | CASHIER+ |
| Click “Save & Exit” | Stays on count list; progress saved | CASHIER+ |
| Scan barcode | Stays on page; increments count for matched product | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-12 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.6.8 |
| Database Tables | rfid_scan_sessions (RW), rfid_scan_events (R), session_operators (RW), rfid_tags (R), inventory_levels (R), locations (R) |
| State Machine(s) | RFID Count Session (same as stock count lifecycle) |
| Appendix F Services | inventory.count.command.service, inventory.count.query.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No (management side; Raptag mobile handles offline scanning) |
| Route | /inventory/counts/rfid |
Management-side interface for RFID-assisted counting sessions conducted via the Raptag mobile application. Managers create RFID count sessions, assign sections to operators (up to 10), monitor real-time upload progress, review chunked sync status, and manage server-side deduplication of overlapping reads.
| Element | Type | Description | Business Rule |
|---|
| RFID session list | Table | Session ID, Location, Type (full_inventory/cycle_count/spot_check), Status, Operator Count, Tag Reads, Sync % | BRD 4.6.8 |
| Operator assignment | Panel | Add operators (up to 10), assign sections (e.g., “Sarah: Men’s Tops”), track join/leave status | BRD 4.6.8 |
| Chunked upload monitor | Panel | Per-operator: chunks uploaded, chunks pending, sync errors. 5,000 events per chunk | BRD 4.6.8 |
| Dedup results | Panel | Tags scanned by multiple operators with RSSI comparison. Shows which read was kept | BRD 4.6.8 |
| Session completion check | Badge | “All operators submitted” or “Waiting for: James (2 chunks pending)” | BRD 4.6.8 |
| EPC-to-product mapping | Table | EPC reads matched to products/variants via rfid_tag_mappings | BRD 4.6.8 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New RFID Session” | Session creation form (location, type, operator assignment) | MANAGER+ |
| Click “View Results” | SCR-M04-13 Count Results Review (RFID session data) | MANAGER+ |
| Click “Remove Operator” | Stays on page; operator removed from session (data preserved) | MANAGER+ |
| Click operator row | Operator detail: sections assigned, chunks uploaded, tags read | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-13 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.6 |
| Database Tables | inventory_levels (R), inventory_transactions (R), products (R), variants (R) |
| State Machine(s) | Count Lifecycle (REVIEW stage) |
| Appendix F Services | inventory.count.query.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/counts/:id/review |
Presents the variance report from a completed stock count for manager review before adjustments are applied. Shows expected vs. counted quantities for every product in scope, highlights high-variance items, and provides per-line accept/reject controls. For SNAPSHOT mode, displays reconciliation adjustments for sales and transfers that occurred during the count.
| Element | Type | Description | Business Rule |
|---|
| Variance summary | Panel | Total items counted, items with variance, total positive variance, total negative variance, net variance, variance value at cost | BRD 4.6.3 |
| Variance table | Table | Product, Variant, Expected Qty, Counted Qty, Variance, Variance %, Count Method (Scanner/Manual/RFID), Accept/Reject toggle, Notes | BRD 4.6.3 |
| High-variance highlight | Badge | Red highlight on lines where variance % exceeds shrinkage_threshold_pct (default 5%) | BRD 4.16.1 |
| SNAPSHOT reconciliation | Panel | For SNAPSHOT mode: shows sales_during_count, receives_during_count, adjusted_expected_qty | BRD 4.6.4 |
| Cost impact preview | Panel | Total cost impact of accepting all variances (positive and negative) | BRD 4.7.2 |
| Count method breakdown | Panel | Percentage of items counted via Scanner vs. Manual vs. RFID | BRD 4.6.5 |
| Action | Navigates To | Requires Role |
|---|
| Click “Approve All Adjustments” | SCR-M04-14 Count Approval (confirmation) | MANAGER+ |
| Click “Reject” on individual line | Stays on page; line excluded from adjustment | MANAGER+ |
| Click “Request Recount” | SCR-M04-09 Stock Count Session (new count for specific items) | MANAGER+ |
| Click “Export Variance Report” | Downloads CSV/PDF of variance data | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-14 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.6 |
| Database Tables | inventory_levels (RW), inventory_transactions (RW), products (R), variants (R) |
| State Machine(s) | Count Lifecycle (REVIEW → APPROVED) |
| Appendix F Services | inventory.count.command.service, inventory.level.adjustment.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/counts/:id/approve |
Final confirmation step for applying count variance adjustments to inventory. Displays a summary of all accepted adjustments, the total cost impact, and requires manager confirmation. On approval, inventory quantities are updated, COUNT_ADJUST movements are logged, and if FREEZE mode was active, sales resume at the location.
| Element | Type | Description | Business Rule |
|---|
| Adjustment summary | Panel | Total lines to adjust, net quantity change, total cost impact (at WAC), approved_by field | BRD 4.6 |
| Accepted adjustments list | Table | Product, Variant, Old Qty, New Qty, Change, Cost Impact — only accepted lines shown | BRD 4.6.3 |
| Freeze release indicator | Badge | “Approving will release FREEZE and resume sales at [Location]” (if FREEZE mode) | BRD 4.6.4 |
| Confirmation checkbox | Input | “I confirm these inventory adjustments are accurate” — required before approve button enables | BRD 4.6 |
| Movement log preview | Panel | Preview of COUNT_ADJUST movement records that will be created | BRD 4.12.1 |
| Action | Navigates To | Requires Role |
|---|
| Click “Approve & Apply” | Stays on page; inventory updated, movements logged, count status → APPROVED. If FREEZE: sales resume | MANAGER+ |
| Click “Back to Review” | SCR-M04-13 Count Results Review | MANAGER+ |
| Click “Cancel Count” | Stays on page; count status → CANCELLED, no inventory changes. If FREEZE: sales resume | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-15 |
| Product(s) | All Roles |
| BRD Section(s) | 4.7 |
| Database Tables | inventory_levels (R), inventory_transactions (R), products (R), variants (R), locations (R) |
| State Machine(s) | Adjustment Workflow (PENDING → APPROVED / REJECTED) |
| Appendix F Services | inventory.level.adjustment.service |
| User Roles | ALL (create); MANAGER+ (approve) |
| Offline Capable | No — requires server for submission |
| Route | /inventory/adjustments/new |
Staff submit manual inventory adjustment requests when they discover discrepancies between system quantities and physical reality outside of a formal stock count. All adjustments require manager approval before inventory changes. Supports positive adjustments (found stock) and negative adjustments (shrinkage, damage, theft).
| Element | Type | Description | Business Rule |
|---|
| Product selector | Input | Search by SKU, barcode, or name. Shows current available qty at selected location | BRD 4.7.2 |
| Location selector | Input | Location where adjustment applies | BRD 4.7.2 |
| Qty change | Input | Positive (found stock) or negative (shrinkage/damage). Must not be 0 | BRD 4.7.2 |
| Reason code selector | Input | Standard codes: DAMAGED, THEFT, COUNT_CORRECTION, SAMPLE, WRITE_OFF, FOUND_STOCK, RETURN_TO_STOCK, OTHER + tenant custom codes | BRD 4.7.3 |
| Notes | Input | Free-text explanation. Mandatory when reason code = OTHER or custom code has requires_notes=true | BRD 4.7.2 |
| Cost impact preview | Panel | Calculated: qty_change x weighted_avg_cost. Shows dollar impact before submission | BRD 4.7.2 |
| Pending adjustments | Table | List of user’s pending adjustments with status tracking | BRD 4.7.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “Submit for Approval” | Stays on page; adjustment created as PENDING. Notification sent to managers | ALL |
| Click pending adjustment row | Adjustment detail view (read-only until approved/rejected) | ALL |
| Click “View History” | SCR-M04-22 Inventory Reports (adjustment history filter) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-16 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.7 |
| Database Tables | inventory_levels (RW), inventory_transactions (RW), products (R), variants (R) |
| State Machine(s) | Adjustment Workflow (PENDING → APPROVED / REJECTED) |
| Appendix F Services | inventory.level.adjustment.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/adjustments/approve |
Manager queue for reviewing and approving/rejecting pending inventory adjustment requests. Shows adjustment details including product, location, quantity change, reason code, cost impact, and requester information. Approved adjustments immediately update inventory quantities and create movement records.
| Element | Type | Description | Business Rule |
|---|
| Pending queue | Table | Adjustment #, Product, Location, Qty Change, Reason Code, Requested By, Date, Cost Impact, Days Pending | BRD 4.7.1 |
| Adjustment detail | Panel | Full detail: current qty, proposed new qty, reason, notes, cost impact, requester info | BRD 4.7.2 |
| Approve button | Button | Applies adjustment to inventory, creates ADJUSTMENT_UP or ADJUSTMENT_DOWN movement | BRD 4.7.1 |
| Reject button | Button | Requires rejection reason. Inventory unchanged. Requester notified | BRD 4.7.1 |
| Concurrent adjustment warning | Badge | Warning when multiple pending adjustments exist for same product+location | BRD 4.7.4 |
| Approval history | Table | Recently approved/rejected adjustments for audit trail | BRD 4.7.5 |
| Action | Navigates To | Requires Role |
|---|
| Click “Approve” | Stays on page; inventory updated, movement logged, requester notified | MANAGER+ |
| Click “Reject” | Rejection reason modal; inventory unchanged, requester notified | MANAGER+ |
| Click product link | SCR-M04-02 Inventory List (filtered to product+location) | MANAGER+ |
| Click “View All History” | SCR-M04-22 Inventory Reports (adjustment history) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-17 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.8 |
| Database Tables | transfer_orders (RW), transfer_order_items (RW), inventory_levels (RW), inventory_transactions (RW), locations (R), products (R), variants (R) |
| State Machine(s) | Transfer Lifecycle (REQUESTED → APPROVED → PICKING → SHIPPED → IN_TRANSIT → RECEIVED → COMPLETED / REJECTED / CANCELLED) |
| Appendix F Services | inventory.transfer.command.service, inventory.transfer.query.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/transfers |
Creates and tracks inter-store inventory transfers. Supports both Pull model (destination requests from source) and Push model (HQ pushes to stores). Full lifecycle from request through pick, ship, transit, receive, and verification. Includes auto-suggest transfer recommendations based on sales velocity imbalances.
| Element | Type | Description | Business Rule |
|---|
| Transfer list | Table | Transfer #, Source, Destination, Direction (PULL/PUSH), Status, Priority, Shipped Date, Items Count, Tracking # | BRD 4.8.3 |
| Status filter tabs | Panel | All, Requested, Approved, Picking, Shipped, In-Transit, Received, Completed, Cancelled | BRD 4.8.1 |
| Create transfer form | Modal | Source location, Destination location, Direction (PULL/PUSH), Priority (Normal/Urgent/Customer Request), line items (product, qty_requested) | BRD 4.8.3 |
| Auto-suggest panel | Panel | System recommendations: product, source (highest stock), destination (lowest stock), suggested qty, days-of-supply comparison | BRD 4.8.7 |
| Pick list | Panel | For PICKING status: items to pick with scan verification | BRD 4.8.1 |
| Ship confirmation | Panel | Enter qty_shipped per line, tracking_number, carrier. Source inventory decremented | BRD 4.8.4 |
| Receive confirmation | Panel | Enter qty_received per line, condition (GOOD/DAMAGED/WRONG_ITEM), variance notes | BRD 4.8.4 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Transfer” | Transfer creation modal | MANAGER+ |
| Click “Approve” on requested transfer | Stays on page; status → APPROVED, pick list generated | MANAGER+ (source location) |
| Click “Ship” | Stays on page; inventory decremented at source, status → SHIPPED | MANAGER+ |
| Click “Receive” | Receive confirmation panel; inventory incremented at destination | MANAGER+ |
| Click “View Suggestions” | Auto-suggest panel with rebalancing recommendations | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-18 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.5 |
| Database Tables | inventory_levels (RW), products (R), variants (R), locations (R), purchase_orders (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.reorder.engine.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/reorder |
Configures automatic reorder point calculation and draft PO generation. Displays velocity-based reorder points per product per location, allows static overrides by managers, monitors dead stock detection, and shows auto-generated draft POs for review. Controls the reorder engine’s background job schedule and parameters.
| Element | Type | Description | Business Rule |
|---|
| Reorder points table | Table | Product, Location, Current Qty, Calculated Reorder Point, Override Value (if set), Days of Supply, Velocity (90d), Override Active (Y/N) | BRD 4.5.1 |
| Static override form | Modal | Product, Location, override_reorder_point, override_reason (mandatory). Visual indicator shows calculated vs. override | BRD 4.5.3 |
| Auto-PO queue | Table | Auto-generated draft POs awaiting review. Badge: “N draft POs auto-generated” | BRD 4.5.2 |
| Dead stock list | Table | Products with zero velocity for 90+ days. Actions: Markdown, Transfer, Write-Off, Dismiss | BRD 4.5.4 |
| Override audit | Table | Active overrides: product, location, override value, calculated value, reason, set by, set date, days active | BRD 4.5.5 |
| Reorder engine config | Panel | Safety stock calculation (1.65 sigma), velocity window (90d), check frequency, account_for_open_pos toggle | BRD 4.5.1 |
| Action | Navigates To | Requires Role |
|---|
| Click “Set Override” | Override form modal | MANAGER+ |
| Click “Remove Override” | Stays on page; returns to dynamic calculation | MANAGER+ |
| Click auto-PO row | SCR-M04-04 PO Create (auto-generated PO, editable) | BUYER+ |
| Click dead stock “Transfer” | SCR-M04-17 Transfer Create (product pre-filled) | MANAGER+ |
| Click dead stock “Markdown” | SCR-M03-06 Markdown Workflow (product pre-filled) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-19 |
| Product(s) | OWNER |
| BRD Section(s) | 4.7.3 |
| Database Tables | inventory_transactions (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.level.adjustment.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/reason-codes |
Manages tenant-defined custom reason codes for inventory adjustments, extending the standard set (DAMAGED, THEFT, COUNT_CORRECTION, etc.). Custom codes appear alongside standard codes in all adjustment workflows and reports. Supports direction constraints, mandatory notes, and deactivation (soft delete).
| Element | Type | Description | Business Rule |
|---|
| Standard codes table | Table | Code, Display Name, Direction, Description — read-only, system-defined | BRD 4.7.3 |
| Custom codes table | Table | Code, Display Name, Direction (POSITIVE/NEGATIVE/BOTH), Requires Notes, Sort Order, Status (Active/Inactive), Usage Count | BRD 4.7.3 |
| Custom code form | Modal | code (uppercase, alphanumeric + underscore), display_name, description, direction, requires_notes, sort_order | BRD 4.7.3 |
| Usage analytics | Panel | Per-code: adjustment count, total qty impact, total cost impact, last used date | BRD 4.7.5 |
| Code validation | Badge | Prevents duplicate codes and conflicts with standard codes | BRD 4.7.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New Reason Code” | Custom code form modal | MANAGER+ |
| Click custom code row | Custom code form modal (edit mode) | MANAGER+ |
| Click “Deactivate” | Stays on page; code hidden from dropdown but preserved in historical records | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-20 |
| Product(s) | All Roles |
| BRD Section(s) | 4.10 |
| Database Tables | products (R), variants (R), inventory_levels (R), inventory_transactions (R), locations (R) |
| State Machine(s) | Serial Status (IN_STOCK → SOLD → RETURNED → IN_STOCK / RMA / WRITE_OFF) |
| Appendix F Services | inventory.serial-lot.command.service |
| User Roles | CASHIER, MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/serials |
Manages serial number and lot/batch tracking for products that require individual unit traceability. Provides serial number lookup, status history, customer association, and recall support. Enforces serial capture at receiving and sale for serial-tracked products.
| Element | Type | Description | Business Rule |
|---|
| Serial search | Input | Search by serial number, product SKU, or customer name. Returns full serial history | BRD 4.10.1 |
| Serial detail | Panel | Serial number, product, current status (IN_STOCK/SOLD/RETURNED/RMA/WRITE_OFF), current location, received_at, received_via, sold_at, sold_to customer, sale_order_id | BRD 4.10.1 |
| Serial status timeline | Panel | Visual timeline of serial status changes with timestamps, actors, and source documents | BRD 4.10.1 |
| Lot inventory table | Table | Lot number, product, location, qty_received, qty_on_hand, qty_sold, received_date, expiry_date, age (days), source PO | BRD 4.10.2 |
| Recall lookup | Panel | Enter lot number → shows all units: in stock (by location), sold (customer, date, order), returned | BRD 4.10.2 |
| Warranty lookup | Panel | Enter serial → shows customer, purchase date, location, order number for warranty claims | BRD 4.10.3 |
| Action | Navigates To | Requires Role |
|---|
| Click serial in results | Serial detail panel with full history | ALL |
| Click customer link | Customer detail screen (from sales module) | MANAGER+ |
| Click order link | Order detail screen (from sales module) | MANAGER+ |
| Click “Recall Report” | Downloads lot trace report (CSV/PDF) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-21 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.9 |
| Database Tables | purchase_orders (R), inventory_levels (RW), inventory_transactions (RW), products (R), variants (R), brands (R) |
| State Machine(s) | RMA Lifecycle (DRAFT → SUBMITTED → VENDOR_APPROVED/VENDOR_REJECTED → SHIPPED_BACK → CREDIT_RECEIVED/REPLACEMENT_RECEIVED → CLOSED) |
| Appendix F Services | inventory.rma.command.service |
| User Roles | MANAGER, OWNER, BUYER |
| Offline Capable | No |
| Route | /inventory/rma |
Manages vendor return merchandise authorizations for both defective returns and overstock returns. Tracks the full RMA lifecycle from draft through vendor response, shipping, and credit/replacement resolution. Inventory is decremented only when items are physically shipped back to the vendor.
| Element | Type | Description | Business Rule |
|---|
| RMA list | Table | RMA #, Vendor, Type (DEFECTIVE_RETURN/OVERSTOCK_RETURN), Status, Source Location, Total Value, Credit Amount, Days Open | BRD 4.9.1 |
| RMA type selector | Input | Defective Return (inspection required) or Overstock Return (vendor agreement required) | BRD 4.9.6 |
| RMA detail form | Panel | RMA header: vendor, source_location, reason, notes. For overstock: vendor_agreement_ref, restocking_fee_pct | BRD 4.9.2 |
| Line items table | Table | Product, Variant, Qty, Unit Cost, Line Total, Condition Notes, Inspection Result | BRD 4.9.2 |
| Inspection result | Input | Per-line: CONFIRMED_DEFECTIVE, COSMETIC_DAMAGE, NOT_AS_DESCRIBED, NOT_INSPECTED (overstock only) | BRD 4.9.2 |
| Credit calculator | Panel | For overstock: Gross Credit, Restocking Fee (%), Restocking Fee Amount, Net Credit | BRD 4.9.6 |
| Status timeline | Panel | Visual progression through RMA states with timestamps | BRD 4.9.1 |
| Ship back form | Panel | Tracking number, ship date. Inventory decremented on ship | BRD 4.9.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “+ New RMA” | RMA detail form (create mode) | MANAGER+ |
| Click “Submit to Vendor” | Stays on page; status → SUBMITTED, line items locked | MANAGER+ |
| Click “Mark Vendor Approved” | Stays on page; status → VENDOR_APPROVED | MANAGER+ |
| Click “Ship Back” | Ship back form; inventory decremented at source location | MANAGER+ |
| Click “Record Credit” | Credit amount entry; status → CREDIT_RECEIVED | BUYER+ |
| Click “Receive Replacement” | Creates linked PO for replacement items; status → REPLACEMENT_RECEIVED | BUYER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-22 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.17.2 |
| Database Tables | inventory_levels (R), inventory_transactions (R), purchase_orders (R), transfer_orders (R), products (R), variants (R), locations (R), brands (R) |
| State Machine(s) | — |
| Appendix F Services | inventory.report.query.service, inventory.movement.query.service |
| User Roles | MANAGER, OWNER, BUYER (scoped by role) |
| Offline Capable | No |
| Route | /inventory/reports |
Centralized inventory reporting hub providing access to all 33 inventory reports defined in the master report suite. Supports filtering by location, category, brand, vendor, date range, and custom grouping keys. All reports exportable to CSV and PDF with role-based access control.
| Element | Type | Description | Business Rule |
|---|
| Report catalog | Panel | 33 reports organized by category: Stock Levels, Purchase Orders, Receiving, Counting, Adjustments, Transfers, RMA, Costing, Serial/Lot, Alerts | BRD 4.17.2 |
| Report builder | Panel | Select report → configure filters (location, category, brand, date range) → generate | BRD 4.17.2 |
| Common filters | Input | Location (All/specific), Category, Brand, Vendor, Date Range, Status | BRD 4.17.2 |
| Grouping keys | Input | Per-report grouping options (e.g., by Location, by Category, by Vendor) | BRD 4.17.2 |
| Report output | Table | Tabular results with sortable columns and inline drill-down | BRD 4.17.2 |
| Export options | Button | CSV, PDF. Schedule recurring reports (email delivery) | BRD 4.17.2 |
| Access control indicator | Badge | Shows which reports are available to current user role | BRD 4.17.3 |
| Action | Navigates To | Requires Role |
|---|
| Click report in catalog | Report builder with report-specific filter options | MANAGER+ (scoped) |
| Click “Export CSV” | Downloads report data as CSV | MANAGER+ |
| Click “Export PDF” | Downloads formatted PDF report | MANAGER+ |
| Click “Schedule Report” | Report scheduling modal (frequency, recipients) | MANAGER+ |
| Click product/SKU in results | SCR-M04-02 Inventory List (filtered) or SCR-M03-02 Product Detail | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M04-23 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 4.13 |
| Database Tables | inventory_levels (RW), products (R), variants (R), locations (R) |
| State Machine(s) | Reservation Lifecycle (ACTIVE → COMMITTED / RELEASED / EXPIRED) |
| Appendix F Services | inventory.reservation.command.service |
| User Roles | MANAGER, OWNER |
| Offline Capable | No |
| Route | /inventory/reservations |
Manages and monitors all active inventory reservations across five types: Sale Cart, Parked Transaction, Transfer, Online Order, and Hold-for-Pickup. Provides visibility into reserved quantities, allows manual release of stuck reservations, and monitors hold-for-pickup expirations with countdown timers.
| Element | Type | Description | Business Rule |
|---|
| Reservation type tabs | Panel | All, Sale Cart, Parked Transaction, Transfer, Online Order, Hold-for-Pickup. Count badges per tab | BRD 4.2.2 |
| Active reservations table | Table | Product, Variant, Location, Qty Reserved, Type, Status, Source Document, Reserved By, Reserved At, Expires At | BRD 4.2.2 |
| Hold-for-pickup countdown | Panel | Orders with pickup holds showing countdown timers. Reminder sent at 2 days before expiry | BRD 4.13.4 |
| Expired reservations | Table | Recently expired reservations: auto-released with reason. Stock returned to AVAILABLE | BRD 4.2.2 |
| Manual release | Button | Release stuck reservation (e.g., abandoned cart, system error). Requires reason | BRD 4.2.2 |
| Reservation impact summary | Panel | Total reserved qty across all types, breakdown by location, impact on available stock | BRD 4.1.5 |
| Parked sale warnings | Panel | Products with parked sale reservations showing terminal and sale reference | BRD 4.13.3 |
| Action | Navigates To | Requires Role |
|---|
| Click “Release” on reservation | Stays on page; reservation released, stock returns to AVAILABLE. Requires reason | MANAGER+ |
| Click source document link | Navigates to source: sale detail, parked sale, transfer, or order | MANAGER+ |
| Click “Extend Hold” on pickup | Stays on page; extends hold expiry (max 30 days total) | MANAGER+ |
| Click “View Expired” | Switches to expired reservations table | MANAGER+ |
BRD Sections: 5.1-5.21 | Appendix F: §F.8 (21 services) | Pattern: Standard CRUD
Cross-Reference: See Ch 05, Sections 5.1-5.21 for business rules. See Ch 08, Domains 8-16 for table schemas. See Appendix F, §F.8 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M05-01 |
| Product(s) | OWNER |
| BRD Section(s) | 5.20 |
| Database Tables | tenants (R/W), locations (R/W), users (R/W), registers (R/W), tax_jurisdictions (R/W), tax_rates (R/W), tenant_settings (R/W), roles (R/W), role_permissions (R/W), devices (R/W), payment_terminals (R/W) |
| State Machine(s) | 5.20.4 Onboarding State Tracking |
| Appendix F Services | setup.onboarding.wizard.service, setup.settings.crud.service, setup.location.crud.service, setup.user.crud.service, setup.register.crud.service, setup.tax.crud.service |
| User Roles | OWNER |
| Offline Capable | No |
| Route | /admin/onboarding |
The Onboarding Wizard is a 13-step guided setup workflow that provisions a new tenant from initial registration through operational go-live readiness. It ensures every required configuration area is addressed before the tenant begins processing transactions. Steps 1-5 and 7 and 9 are mandatory for go-live; remaining steps are recommended but deferrable.
| Element | Type | Description | Business Rule |
|---|
| Step indicator bar | Panel | Horizontal progress bar showing all 13 steps with completion status (green = complete, grey = pending, yellow = skipped) | BRD 5.20.1 |
| Current step content | Panel | Dynamic content area rendering the form fields for the active step | BRD 5.20.2 |
| Step navigation buttons | Button | “Back” and “Next” buttons to move between steps; “Skip” for optional steps | BRD 5.20.2 |
| Go-Live Checklist panel | Panel | Step 13: automated validation of 9 mandatory checks and 7 advisory checks with pass/fail indicators | BRD 5.20.3 |
| Mandatory check indicators | Badge | Red/green badges for each of the 9 mandatory checks (locations, registers, users, tax, payment, email, currency, timezone) | BRD 5.20.3 |
| Advisory warning list | Panel | Yellow warnings for recommended but non-blocking checks (Shopify, label printers, receipt customisation) | BRD 5.20.3 |
| “Go Live” button | Button | Enabled only when all 9 mandatory checks pass; activates tenant for live operations | BRD 5.20.3 |
| Progress persistence | Badge | Displays “Step X of 13” with auto-save; wizard state restored on return | BRD 5.20.4 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEXUS ADMIN — Onboarding Wizard [Will] [?] [X] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ● ● ● ● ● ○ ○ ○ ○ ○ ○ ○ ○ Step 5 of 13: Users & Roles │
│ 1 2 3 4 5 6 7 8 9 10 11 12 13 │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ CREATE USERS │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Display Name [________________________] │ │
│ │ Email [________________________] │ │
│ │ PIN (4-6 digit) [______] │ │
│ │ Role [OWNER ▼] │ │
│ │ Location [Garden Mall ▼] ☑ Primary │ │
│ │ [+ Add User] │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ CREATED USERS │
│ ┌──────────────────┬──────────┬─────────┬──────────────┐ │
│ │ Name │ Role │ PIN │ Location │ │
│ ├──────────────────┼──────────┼─────────┼──────────────┤ │
│ │ Will Johnson │ OWNER │ **** │ Garden Mall │ │
│ │ Sarah Adams │ MANAGER │ **** │ Heritage Mall│ │
│ └──────────────────┴──────────┴─────────┴──────────────┘ │
│ │
│ [◄ Back] [Skip] [Next ►] │
└─────────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Complete Step 13 + Go Live | SCR-M05-02 System Settings | OWNER |
| Skip optional step | Next wizard step | OWNER |
| Click “Back” | Previous wizard step | OWNER |
| Abandon wizard (close) | Nexus POS Dashboard (wizard progress saved) | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-02 |
| Product(s) | OWNER |
| BRD Section(s) | 5.2 |
| Database Tables | tenant_settings (R/W), tenants (R) |
| State Machine(s) | None |
| Appendix F Services | setup.settings.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/general |
The System Settings screen provides tenant-level identity, operational defaults, and visual branding configuration. Administrators configure the company name, logo, timezone, date format, session policies, and customer-facing visual identity. Settings are organised into three tabs: Core, Operational, and Branding.
| Element | Type | Description | Business Rule |
|---|
| Tenant name input | Input | Trading name displayed in headers and reports (max 100 chars) | BRD 5.2.1 |
| Legal entity name input | Input | Registered business name for invoices (max 200 chars) | BRD 5.2.1 |
| Company logo upload | Input | PNG/SVG upload with preview (max 2MB, min 200x200px) | BRD 5.2.1 |
| Default timezone selector | Input | IANA timezone dropdown; applies to all locations unless overridden | BRD 5.2.1 |
| Base currency display | Badge | Read-only after first transaction; shows ISO 4217 code (e.g., USD) | BRD 5.2.1 — immutable after first transaction |
| Auto-logout timeout | Input | Minutes of inactivity before POS session logout (5-120 range) | BRD 5.2.2 |
| Failed login lockout | Input | Max consecutive failed attempts before lockout (default: 5) | BRD 5.2.2 |
| Primary/Accent colour pickers | Input | Hex colour selectors for brand_primary_color and brand_accent_color | BRD 5.2.4 |
| Login background image upload | Input | JPG/PNG (max 5MB, 1920x1080 recommended) | BRD 5.2.4 |
| Business hours table | Table | Per-location, per-day-of-week open/close times with is_closed toggle | BRD 5.2.3 |
| Holiday calendar | Table | Date, name, applies_to, modified hours, recurring flag | BRD 5.2.3 |
| Action | Navigates To | Requires Role |
|---|
| Save Settings | Same screen (confirmation toast) | ADMIN+ |
| Upload logo | Same screen (preview updates) | ADMIN+ |
| Manage Business Hours | Inline editor expands | ADMIN+ |
| Manage Holiday Calendar | Modal dialog | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-03 |
| Product(s) | OWNER |
| BRD Section(s) | 5.4 |
| Database Tables | locations (R/W), tax_jurisdictions (R), tenant_settings (R) |
| State Machine(s) | None |
| Appendix F Services | setup.location.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/locations |
The Location Management screen defines the physical topology of the tenant’s retail operation. Administrators create, edit, and deactivate store locations and warehouse facilities. Every inventory balance, register, user assignment, and transaction is scoped to a location, making this a foundational configuration screen.
| Element | Type | Description | Business Rule |
|---|
| Location list table | Table | Sortable table of all locations with code, name, type, city, status | BRD 5.4 |
| Add Location button | Button | Opens modal to create new STORE or WAREHOUSE location | BRD 5.4.1 |
| Location type selector | Input | Dropdown: STORE or WAREHOUSE; warehouses cannot have registers | BRD 5.4.1 |
| Address fields | Input | Street, city, state, ZIP, country (ISO 3166-1 alpha-2) | BRD 5.4.2 |
| Tax jurisdiction assignment | Input | Dropdown linking location to a tax_jurisdiction record | BRD 5.4.2 — tax_jurisdiction_id required |
| Timezone override | Input | IANA timezone; overrides tenant default for this location | BRD 5.4.2 |
| Franchise flag | Input | Checkbox for is_franchise (different reporting/fee rules) | BRD 5.4.2 |
| Sort order | Input | Integer for display ordering in dropdowns and reports | BRD 5.4.2 |
| Deactivate toggle | Button | Sets is_active=false; prevents new transactions at location | BRD 5.4.2 |
| Action | Navigates To | Requires Role |
|---|
| Add Location | Modal form (stays on screen) | ADMIN+ |
| Edit Location | Inline edit / modal | ADMIN+ |
| View Location Registers | SCR-M05-08 Register Management (filtered) | ADMIN+ |
| Deactivate Location | Confirmation dialog | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-04 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 5.5 |
| Database Tables | tenant_users (R/W), users (R/W), roles (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.user.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/users |
The User Management screen provides creation, editing, and deactivation of user accounts across the tenant. Each user represents a staff member who interacts with the POS system. Administrators assign roles, set PINs, configure location assignments, and manage commission rates from this screen.
| Element | Type | Description | Business Rule |
|---|
| User list table | Table | All users with display name, email, role, primary location, status, last login | BRD 5.5.1 |
| Add User button | Button | Opens form to create new user with email, PIN, role, and location | BRD 5.5.1 |
| Email input | Input | Unique per tenant; used for standard login | BRD 5.5.1 |
| PIN input | Input | 4-6 digit numeric PIN for POS login; unique per tenant; stored as bcrypt hash | BRD 5.5.1 |
| Role selector | Input | Dropdown: OWNER, ADMIN, MANAGER, STAFF, BUYER | BRD 5.5.3 |
| Location assignment panel | Panel | Multi-select locations with primary location toggle | BRD 5.5.2 |
| Commission rate input | Input | Decimal percentage (e.g., 5.00 for 5%); null = no commission | BRD 5.5.1 |
| Deactivate/Reactivate toggle | Button | Sets is_active; deactivation invalidates all active sessions | BRD 5.5.1 |
| Failed login count badge | Badge | Shows current failed_login_count and locked_until status | BRD 5.5.1 |
| Reset lockout button | Button | Clears failed_login_count and locked_until for locked users | BRD 5.5.5 |
| Action | Navigates To | Requires Role |
|---|
| Add User | Modal form (stays on screen) | ADMIN+ |
| Edit User | Inline edit / detail panel | ADMIN+ |
| View User Activity | SCR-M05-21 Audit Log Viewer (filtered by user) | ADMIN+ |
| Manage Roles | SCR-M05-05 Role & Permission Config | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-05 |
| Product(s) | OWNER |
| BRD Section(s) | 5.5 |
| Database Tables | roles (R/W), role_permissions (R/W), tenant_users (R) |
| State Machine(s) | None |
| Appendix F Services | setup.role.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/roles |
The Role & Permission Config screen provides granular control over which capabilities each role has access to. Administrators view and edit the feature toggle matrix for all five predefined roles (OWNER, ADMIN, MANAGER, STAFF, BUYER) and can create custom roles by duplicating and modifying an existing role’s permissions.
| Element | Type | Description | Business Rule |
|---|
| Role list sidebar | Panel | List of all roles with user count badge per role | BRD 5.5.3 |
| Feature toggle matrix | Table | Grid of feature_code rows x role columns with toggle switches | BRD 5.5.4 |
| Permission description | Panel | Shows description of selected feature code on hover/click | BRD 5.5.4 |
| OWNER lock indicator | Badge | Shows locked toggles for OWNER role (manage_settings, manage_users always true) | BRD 5.5.4 — OWNER cannot lose manage_settings/manage_users |
| Duplicate role button | Button | Creates custom role from existing role’s toggles (is_system=false) | BRD 5.5.4 |
| User count per role | Badge | Number of active users assigned to each role | BRD 5.5.3 |
| Action | Navigates To | Requires Role |
|---|
| Toggle feature permission | Same screen (real-time save) | ADMIN+ |
| Create custom role | Same screen (new role appears in sidebar) | ADMIN+ |
| Delete custom role | Confirmation dialog (only if no users assigned) | OWNER |
| View users with role | SCR-M05-04 User Management (filtered by role) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-06 |
| Product(s) | All Roles |
| BRD Section(s) | 5.5 |
| Database Tables | users (R), tenant_users (R), roles (R), role_permissions (R), tenant_settings (R) |
| State Machine(s) | 7.12 Connectivity States |
| Appendix F Services | crosscutting.auth.service |
| User Roles | All (unauthenticated) |
| Offline Capable | Yes (POS terminal only) — Cached credentials allow PIN login when API is unreachable; standard email/password login requires connectivity |
| Route | /login |
The Login screen provides two authentication flows: email/password for standard access and PIN-based quick login for POS terminal cashiers. The POS PIN login supports offline operation using cached credential hashes stored in the local SQLite WASM database, enabling staff to continue working during network outages.
| Element | Type | Description | Business Rule |
|---|
| Company logo | Panel | Displays tenant’s company_logo_url with login_tagline below | BRD 5.2.4 |
| Branded background | Panel | Custom login_bg_image_url or system default | BRD 5.2.4 |
| Email input | Input | Email address for standard login | BRD 5.5.5 |
| Password input | Input | Password validated against Argon2id hash | BRD 5.5.1 |
| PIN input (POS) | Input | 4-6 digit numeric PIN pad with large touch targets | BRD 5.5.5 |
| Lockout warning | Badge | Displays remaining lockout time when account is locked | BRD 5.2.2 — lockout_duration_minutes |
| Offline indicator (POS) | Badge | Shows “Offline Mode” banner when API is unreachable | BRD 5.5.5 / ADR-048 |
| Forgot password link | Button | Triggers TMPL-PASSWORD-RESET email | BRD 5.15.2 |
| Action | Navigates To | Requires Role |
|---|
| Successful standard login | Dashboard (role-appropriate home) | Any authenticated |
| Successful POS PIN login | POS Terminal Home / SCR-M05-07 Clock-In | Any authenticated |
| Failed login (max attempts) | Same screen with lockout message | N/A |
| Forgot Password | Same screen (email sent confirmation) | N/A |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-07 |
| Product(s) | CASHIER+ |
| BRD Section(s) | 5.6 |
| Database Tables | clock_records (R/W), tenant_users (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.timetracking.command.service |
| User Roles | All POS users |
| Offline Capable | Yes — Clock events queued locally and synced when connectivity restores |
| Route | /pos/clock |
The Clock-In/Clock-Out screen records staff work time for basic payroll reporting. Staff clock in via PIN after POS login and clock out at the end of their work period. Managers can view current clock-in status for all staff at the location and manually edit missed clock-out entries with audit notes.
| Element | Type | Description | Business Rule |
|---|
| Clock-In button | Button | Records clock_in timestamp for authenticated user at current location | BRD 5.6.1 |
| Clock-Out button | Button | Records clock_out timestamp; required before end-of-day close | BRD 5.6.1 |
| Current status indicator | Badge | Shows “Clocked In since HH:MM” or “Not Clocked In” | BRD 5.6.1 |
| Duration timer | Panel | Running timer showing elapsed time since clock-in | BRD 5.6.1 |
| Manager override panel | Panel | Allows MANAGER+ to manually set clock-out time with required notes field | BRD 5.6.1 |
| Staff clock status list | Table | (Manager view) All users at location with current clock-in/out status | BRD 5.6.1 |
| 16-hour alert indicator | Badge | Warning when clock-in exceeds 16 hours without clock-out | BRD 5.6.1 |
| Action | Navigates To | Requires Role |
|---|
| Clock In | POS Terminal Home | All POS users |
| Clock Out | POS Login screen | All POS users |
| Manager: Edit missed clock-out | Same screen (inline edit with notes) | MANAGER+ |
| View clock history | Same screen (expandable history panel) | MANAGER+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-08 |
| Product(s) | OWNER |
| BRD Section(s) | 5.7 |
| Database Tables | registers (R/W), register_ip_changes (R/W), devices (R/W), locations (R), register_profiles (R) |
| State Machine(s) | 5.7.2 Register State Machine (ACTIVE / MAINTENANCE / RETIRED) |
| Appendix F Services | setup.register.crud.service, setup.device.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/registers |
The Register Management screen maintains the register registry across all tenant locations. Administrators create registers, assign profiles (Full POS or Mobile), pair physical devices, manage IP addresses, and control register status through the ACTIVE/MAINTENANCE/RETIRED lifecycle. This screen enforces the IP change limit (max 2 per 365 days) and OWNER-only retirement with type-to-confirm safety.
| Element | Type | Description | Business Rule |
|---|
| Register list table | Table | Registers grouped by location with number, name, profile, status, IP, last seen | BRD 5.7.1 |
| Location filter | Input | Dropdown to filter registers by location | BRD 5.7.1 |
| Add Register button | Button | Create register with number, name, profile, and location | BRD 5.7.1 |
| Status badge | Badge | Colour-coded: green=ACTIVE, yellow=MAINTENANCE, red=RETIRED | BRD 5.7.2 |
| IP address field | Input | IPv4/IPv6 address; shows remaining IP changes count for the year | BRD 5.7.1 — ERR-5071: max 2 changes per 365 days |
| Take Offline button | Button | Transitions ACTIVE to MAINTENANCE | BRD 5.7.2 |
| Bring Online button | Button | Transitions MAINTENANCE to ACTIVE | BRD 5.7.2 |
| Retire Register button | Button | OWNER-only; type-to-confirm “RETIRE” dialog | BRD 5.7.2 — ERR-5072 |
| Device pairing panel | Panel | Shows paired devices with hardware_id, type, is_primary, last_seen_at | BRD 5.7.3 |
| Peripheral assignments | Table | Receipt printer, label printer, scanner, payment terminal, cash drawer per register | BRD 5.7.5 |
| Action | Navigates To | Requires Role |
|---|
| Add Register | Modal form (stays on screen) | ADMIN+ |
| Change IP Address | Confirmation dialog showing remaining changes | ADMIN+ |
| Retire Register | Type-to-confirm “RETIRE” modal | OWNER only |
| Pair Device | SCR-M05-08 device pairing sub-panel | ADMIN+ |
| View Register Profile | SCR-M05-09 Register Profiles | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-09 |
| Product(s) | OWNER |
| BRD Section(s) | 5.7 |
| Database Tables | register_profiles (R), registers (R) |
| State Machine(s) | None |
| Appendix F Services | setup.register.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/registers/profiles |
The Register Profiles screen displays the two system-defined register profiles (Full POS and Mobile Checkout) and their function availability matrix. This is a reference screen showing which POS functions are available on each terminal type. Custom profiles are not supported to prevent untested UI configurations.
| Element | Type | Description | Business Rule |
|---|
| Profile comparison table | Table | Side-by-side matrix of FULL_POS vs MOBILE with function availability (Y/N) | BRD 5.7.4 |
| Profile description | Panel | Description of each profile’s intended use case | BRD 5.7.4 |
| Function list | Table | All 15 POS functions (sale, return, exchange, layaway, etc.) with descriptions | BRD 5.7.4 |
| Registers using profile | Badge | Count of registers assigned to each profile | BRD 5.7.4 |
| Required peripherals indicator | Panel | Shows minimum required peripherals per profile (Full POS: printer+scanner+terminal+drawer; Mobile: scanner+terminal) | BRD 5.7.5 |
| Action | Navigates To | Requires Role |
|---|
| View registers using profile | SCR-M05-08 Register Management (filtered by profile) | ADMIN+ |
| Back to Register Management | SCR-M05-08 Register Management | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-10 |
| Product(s) | OWNER |
| BRD Section(s) | 5.7 |
| Database Tables | registers (R/W), devices (R/W) |
| State Machine(s) | 5.7.2 Register State Machine |
| Appendix F Services | setup.register.crud.service |
| User Roles | OWNER |
| Offline Capable | No |
| Route | /admin/settings/registers/:id/retire (modal) |
The Register Retirement screen is a confirmation modal that enforces the OWNER-only, type-to-confirm safety protocol for permanently decommissioning a register. Retired registers cannot be reactivated, and all transaction history is preserved. This screen displays the full impact warning and requires exact-match text entry of “RETIRE”.
| Element | Type | Description | Business Rule |
|---|
| Register details summary | Panel | Shows register number, name, location, profile, and transaction count | BRD 5.7.2 |
| Warning message | Panel | Full text: “This action permanently retires this register. Retired registers cannot be reactivated…” | BRD 5.7.2 |
| Confirmation text input | Input | Text field requiring exact entry of “RETIRE” (case-sensitive) | BRD 5.7.2 — ERR-5072 |
| Confirm Retire button | Button | Disabled until confirmation text matches exactly | BRD 5.7.2 |
| Cancel button | Button | Returns to Register Management without changes | BRD 5.7.2 |
| Action | Navigates To | Requires Role |
|---|
| Confirm retirement | SCR-M05-08 Register Management (register now shows RETIRED status) | OWNER only |
| Cancel | SCR-M05-08 Register Management | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-11 |
| Product(s) | OWNER |
| BRD Section(s) | 5.11, 6.8 |
| Database Tables | payment_terminals (R/W), register_peripherals (R/W), locations (R), registers (R) |
| State Machine(s) | 6.8 Terminal State Machine (active / offline / maintenance / disabled) |
| Appendix F Services | setup.payment-method.crud.service, integration.payment-processor.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/payments/terminals |
The Payment Terminal Config screen manages the registration and pairing of physical payment processing devices (card readers, NFC terminals) to registers and locations. Administrators configure processor credentials (via Integration Hub), register terminal hardware, and assign terminals to specific registers. The SAQ-A semi-integrated architecture ensures no card data touches the POS system.
| Element | Type | Description | Business Rule |
|---|
| Terminal list table | Table | All payment terminals with terminal_id, name, location, processor, type, status | BRD 5.11.3 / 6.8.2 |
| Add Terminal button | Button | Register new terminal with ID, name, location, processor, and type | BRD 6.8.2 |
| Terminal type selector | Input | integrated, standalone, virtual, mobile | BRD 6.8.2 |
| Processor selector | Input | Dropdown of configured payment processors (Stripe, Square, Adyen) | BRD 6.8.3 |
| Capability badges | Badge | Contactless, EMV chip, swipe support indicators per terminal | Ch 08 Domain 14 |
| Register assignment | Input | Link terminal to a specific register via register_peripherals | BRD 5.7.5 |
| Health status indicator | Badge | Last transaction, last batch, current status | BRD 6.8.2 |
| Action | Navigates To | Requires Role |
|---|
| Add Terminal | Modal form (stays on screen) | ADMIN+ |
| Assign to Register | SCR-M05-08 Register Management | ADMIN+ |
| Test Connection | Same screen (connection test result) | ADMIN+ |
| View Payment Batches | Inline expandable panel | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-12 |
| Product(s) | OWNER |
| BRD Section(s) | 5.11 |
| Database Tables | payment_methods (R/W), location_payment_methods (R/W), locations (R), tenant_settings (R/W) |
| State Machine(s) | None |
| Appendix F Services | setup.payment-method.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/payments/methods |
The Payment Methods Setup screen configures which payment methods are accepted across the tenant and per location. Administrators enable/disable CASH, CREDIT_CARD, GIFT_CARD, STORE_CREDIT, LAYAWAY_PAYMENT, and FINANCING methods. Cash rounding rules (nearest cent, nickel, or dime) are also configured here.
| Element | Type | Description | Business Rule |
|---|
| Payment method list | Table | All 6 payment types with tenant-level enabled toggle, requires processor flag, split capability, offline support | BRD 5.11.1 |
| Per-location matrix | Table | Grid of locations x payment methods with per-location enable/disable toggles | BRD 5.11.2 |
| CASH lock indicator | Badge | CASH is always enabled and cannot be disabled at any location | BRD 5.11.2 |
| Cash rounding rule selector | Input | Dropdown: NEAREST_CENT, NEAREST_NICKEL, NEAREST_DIME | BRD 5.11.4 |
| Method display name | Input | Customisable name per method (e.g., “Visa/MC/Amex” instead of “Credit/Debit Card”) | BRD 5.11.1 |
| Offline capability indicator | Badge | Shows which methods work offline (CASH only) | BRD 5.11.1 |
| Action | Navigates To | Requires Role |
|---|
| Toggle method tenant-wide | Same screen (cascades to all locations) | ADMIN+ |
| Toggle method per location | Same screen | ADMIN+ |
| Configure payment terminals | SCR-M05-11 Payment Terminal Config | ADMIN+ |
| Save rounding rules | Same screen (confirmation toast) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-13 |
| Product(s) | OWNER |
| BRD Section(s) | 5.9 |
| Database Tables | tax_jurisdictions (R/W), tax_rates (R/W), location_tax_jurisdictions (R/W), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.tax.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/tax |
The Tax Jurisdiction Config screen manages the 3-level compound tax system (State/County/City). Administrators create tax jurisdictions, define rate levels with effective dates, and assign jurisdictions to store locations. Future tax rate changes can be scheduled by setting an effective date in the future. The screen also displays the calculated compound rate for each location.
| Element | Type | Description | Business Rule |
|---|
| Jurisdiction list table | Table | All jurisdictions with code, name, state_name, active rates summary, location count | BRD 5.9.1 |
| Add Jurisdiction button | Button | Create jurisdiction with code (e.g., “VA-NFK”) and name | BRD 5.9.1 |
| Rate levels panel | Panel | Up to 3 rate rows per jurisdiction: STATE, COUNTY, CITY with rate_percent and effective_date | BRD 5.9.1 |
| Compound rate calculator | Badge | Shows summed effective rate (e.g., “State 4.3% + County 0.7% + City 1.0% = 6.0%”) | BRD 5.9.1 |
| Future rate indicator | Badge | Scheduled rates highlighted with effective_date and countdown | BRD 5.9.1 |
| Location-jurisdiction assignment | Table | Which jurisdiction is assigned to each store location | BRD 5.4.2 |
| Rate history | Table | Expandable historical rates per jurisdiction level for audit | BRD 5.9.1 |
| Tax reporting period selector | Input | MONTHLY or QUARTERLY dropdown | BRD 5.9.4 |
| Action | Navigates To | Requires Role |
|---|
| Add Jurisdiction | Modal form (stays on screen) | ADMIN+ |
| Add/Edit rate level | Inline edit within jurisdiction panel | ADMIN+ |
| Schedule future rate | Same screen (rate appears with future badge) | ADMIN+ |
| Assign to location | Same screen (location-jurisdiction matrix) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-14 |
| Product(s) | MANAGER+ |
| BRD Section(s) | 5.9 |
| Database Tables | customers (R/W), products (R), tax_jurisdictions (R) |
| State Machine(s) | None |
| Appendix F Services | setup.tax.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/tax/exemptions |
The Tax Exemption Management screen provides a consolidated view of all tax-exempt customers and tax-exempt products across the tenant. Administrators can review exemption certificates, check expiry dates, and manage product-level tax exemption flags. Expired certificates are highlighted for follow-up action before the next sale.
| Element | Type | Description | Business Rule |
|---|
| Exempt customers table | Table | Customers with tax_exempt=true, certificate number, expiry date, status | BRD 5.9.3 |
| Expired certificate warning | Badge | Red highlight for certificates past expiry_date | BRD 5.9.3 — “Tax exemption certificate expired” warning at POS |
| Certificate number input | Input | State or federal exemption certificate number (max 50 chars) | BRD 5.9.3 |
| Expiry date input | Input | Certificate expiration date; system validates at time of sale | BRD 5.9.3 |
| Exempt products list | Table | Products with tax_exempt=true flag, grouped by category | BRD 5.9.3 |
| Tax calculation priority diagram | Panel | Visual display of priority: Product exempt > Customer exempt > Jurisdiction rate | BRD 5.9.2 |
| Action | Navigates To | Requires Role |
|---|
| Edit customer exemption | Customer detail modal | ADMIN+ |
| Toggle product tax exemption | Same screen (inline toggle) | ADMIN+ |
| Export exempt customer list | CSV/PDF download | ADMIN+ |
| View tax calculation priority | Same screen (expandable diagram) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-15 |
| Product(s) | OWNER |
| BRD Section(s) | 5.10 |
| Database Tables | uom (R/W), uom_conversions (R/W), tenant_settings (R) |
| State Machine(s) | None |
| Appendix F Services | setup.uom.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/uom |
The UOM Setup screen manages predefined and tenant-customizable units of measure used for selling, purchasing, and inventory tracking. Administrators review the 12 system-predefined UoMs, create custom UoMs with conversion factors, and manage the conversion table between related units. This enables scenarios where products are purchased in bulk (cases, dozens) and sold individually (each, pair).
| Element | Type | Description | Business Rule |
|---|
| System UoM list | Table | 12 predefined UoMs (EACH, PAIR, PACK, BOX, DOZEN, CASE, YARD, METER, FOOT, KG, LB, OZ) — read-only | BRD 5.10.1 |
| Custom UoM list | Table | Tenant-created UoMs with code, name, category, conversion factor, base UoM | BRD 5.10.2 |
| Add Custom UoM button | Button | Create UoM with code, name, category (QUANTITY/LENGTH/WEIGHT), and conversion factor to base | BRD 5.10.2 |
| Conversion table | Table | From-UoM to To-UoM with factor; auto-generates inverse conversion | BRD 5.10.3 |
| Category filter | Input | Filter UoMs by QUANTITY, LENGTH, or WEIGHT | BRD 5.10.1 |
| Deactivate UoM | Button | Soft-delete custom UoMs (system UoMs cannot be deactivated) | BRD 5.10.2 |
| Action | Navigates To | Requires Role |
|---|
| Add Custom UoM | Modal form (stays on screen) | ADMIN+ |
| Edit Custom UoM | Inline edit | ADMIN+ |
| View products using UoM | Product list filtered by selling_uom or purchasing_uom | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-16 |
| Product(s) | OWNER |
| BRD Section(s) | 5.13 |
| Database Tables | approval_rules (R/W), approval_requests (R/W), tenant_users (R), roles (R) |
| State Machine(s) | 5.13.3 Approval Request Lifecycle (PENDING / APPROVED / REJECTED / ESCALATED / AUTO_REJECTED) |
| Appendix F Services | setup.approval-workflow.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/approvals |
The Approval Workflows screen configures approval rules that gate sensitive business actions behind manager or administrator review. Each of the 9 approvable actions (PO creation, inventory adjustments, refunds, voids, transfers, price markdowns, discount overrides, vendor RMAs) has its own rule with threshold, approver role, notification method, and escalation timeout.
| Element | Type | Description | Business Rule |
|---|
| Approval rules table | Table | 9 approvable actions with enabled toggle, threshold value, threshold type, approver role | BRD 5.13.1 |
| Threshold value input | Input | Dollar amount, unit count, or percentage depending on action | BRD 5.13.2 |
| Threshold type selector | Input | AMOUNT, UNITS, PERCENT, ALWAYS | BRD 5.13.2 |
| Approver role selector | Input | MANAGER, ADMIN, or OWNER minimum role to approve | BRD 5.13.2 |
| Notification method | Input | IN_APP, EMAIL, or BOTH | BRD 5.13.5 |
| Escalation timeout | Input | Hours before escalation to next-higher role (default 24) | BRD 5.13.4 |
| Auto-reject toggle | Input | Whether timed-out requests are auto-rejected | BRD 5.13.2 |
| Pending approvals queue | Table | Current PENDING and ESCALATED requests with action, requester, value, timestamp | BRD 5.13.3 |
| Action | Navigates To | Requires Role |
|---|
| Edit approval rule | Inline edit (stays on screen) | ADMIN+ |
| Approve/Reject request | Same screen (request status updated) | MANAGER+ (per rule) |
| View escalation chain | Inline expansion: MANAGER -> ADMIN -> OWNER | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-17 |
| Product(s) | OWNER |
| BRD Section(s) | 5.8 |
| Database Tables | printers (R/W), register_printers (R/W), registers (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.printer.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/printers |
The Printer Configuration screen manages the central registry of all receipt and label printers across all tenant locations. Administrators register printers, configure connection settings, link printers to registers in specific roles (primary receipt, label, secondary receipt), and monitor printer health status via automated network pings.
| Element | Type | Description | Business Rule |
|---|
| Printer list table | Table | All printers with name, type (RECEIPT/LABEL), location, connection, model, health status | BRD 5.8.1 |
| Add Printer button | Button | Manual registration with name, type, connection_type, address, paper_width | BRD 5.8.1 |
| Discover Printers button | Button | Network subnet scan on ports 9100 (RAW) and 631 (IPP); returns candidates | BRD 5.8.5 |
| Health status badge | Badge | ONLINE (green), OFFLINE (red), ERROR (orange), UNKNOWN (grey) | BRD 5.8.6 |
| Connection type selector | Input | USB, NETWORK_IP, BLUETOOTH | BRD 5.8.1 |
| Paper width selector | Input | Receipt: 58MM/80MM; Label: 25x50MM, 50x25MM, 50x75MM, CUSTOM | BRD 5.8.1 |
| Register-printer links | Table | Which registers use this printer and in what role (PRIMARY_RECEIPT, LABEL, SECONDARY_RECEIPT) | BRD 5.8.4 |
| Shared printer toggle | Input | Whether multiple registers can use this printer (network printers only) | BRD 5.8.1 |
| Action | Navigates To | Requires Role |
|---|
| Add Printer (manual) | Modal form (stays on screen) | ADMIN+ |
| Discover Printers (network scan) | Discovery results panel on same screen | ADMIN+ |
| Link to Register | Same screen (register-printer assignment panel) | ADMIN+ |
| Test Print | Same screen (sends test page to selected printer) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-18 |
| Product(s) | OWNER |
| BRD Section(s) | 5.14 |
| Database Tables | receipt_config (R/W), email_receipt_templates (R/W), tenant_settings (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.receipt.crud.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/receipts |
The Receipt Builder provides full customisation of receipt layout, content, and formatting for both printed thermal receipts and email receipts. Administrators toggle field visibility, reorder sections via drag-and-drop, configure header/footer text and logos, select paper width and font size, and preview changes in real-time with a simulated thermal receipt rendering.
| Element | Type | Description | Business Rule |
|---|
| Field toggle list | Panel | All 17 receipt fields with show/hide toggles and drag-and-drop reorder | BRD 5.14.1 |
| Live receipt preview | Panel | Real-time simulated receipt with sample data, monospace font, configured paper width | BRD 5.14.7 |
| Header configuration | Input | Three header lines (max 100 chars each) + logo upload (PNG/BMP, max 300px wide) | BRD 5.14.3 |
| Footer configuration | Input | Three footer lines (max 200 chars each); blank lines omitted | BRD 5.14.4 |
| Paper width selector | Input | 58MM (~32 chars/line) or 80MM (~48 chars/line) | BRD 5.14.2 |
| Font size selector | Input | SMALL, MEDIUM, LARGE | BRD 5.14.2 |
| Line separator style | Input | DASH, EQUALS, BLANK, STAR | BRD 5.14.2 |
| Location override toggle | Input | Per-location receipt config vs tenant-wide default | BRD 5.14.5 |
| Email receipt tab | Panel | HTML template editor with merge fields, subject line, and “Send Test Email” button | BRD 5.14.6 |
| Action | Navigates To | Requires Role |
|---|
| Save receipt config | Same screen (confirmation toast, preview updates) | ADMIN+ |
| Send Test Email | Same screen (sends sample email receipt to admin’s email) | ADMIN+ |
| Create location override | Same screen (new location-specific config tab) | ADMIN+ |
| Reset to defaults | Confirmation dialog, then same screen | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-19 |
| Product(s) | OWNER |
| BRD Section(s) | 5.15, 6.9 |
| Database Tables | email_templates (R/W), integration_providers (R/W), integration_credentials (R/W), tenant_settings (R) |
| State Machine(s) | 7.14 Integration Connection States |
| Appendix F Services | setup.email-template.crud.service, integration.email.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/email |
The Email Config & Templates screen manages the email provider connection (SMTP, SendGrid, or Mailgun) and the complete template registry for all automated communications. Administrators configure provider credentials, send test emails, and enable/disable individual templates from a catalog of 13 pre-seeded templates covering sales receipts, refund confirmations, order notifications, inventory alerts, and system emails.
| Element | Type | Description | Business Rule |
|---|
| Provider config panel | Panel | Provider type (SMTP/SENDGRID/MAILGUN), host, port, credentials, from address | BRD 6.9.1 |
| Connection test button | Button | Sends test email to verify provider credentials | BRD 6.9.1 |
| Template catalog table | Table | 13 templates with code, name, trigger event, recipient type, enabled toggle | BRD 5.15.2 |
| Template editor | Panel | Subject and body HTML editor with merge field insertion toolbar | BRD 5.15.3 |
| Merge fields reference | Panel | Expandable list of all available merge fields by category (common, transaction, inventory) | BRD 5.15.4 |
| Send preview button | Button | Sends preview email with sample data to admin’s email | BRD 5.15.3 |
| Delivery monitoring | Panel | Bounce rate, consecutive failures per address, suppression list | BRD 6.9.2 |
| Action | Navigates To | Requires Role |
|---|
| Save provider config | Same screen (connection test recommended) | ADMIN+ |
| Test connection | Same screen (success/failure indicator) | ADMIN+ |
| Edit template | Inline editor on same screen | ADMIN+ |
| Toggle template enabled | Same screen (immediate effect) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-20 |
| Product(s) | OWNER |
| BRD Section(s) | 5.16 |
| Database Tables | rfid_config (R/W), rfid_readers (R/W), rfid_printers (R/W), rfid_tags (R), rfid_scan_sessions (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.integrations-hub.config.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/rfid |
The RFID Configuration screen manages all RFID hardware, EPC encoding parameters, tag printing settings, and scan session configuration for the dedicated inventory counting subsystem. Administrators register readers via claim codes, configure SGTIN-96 encoding parameters, manage RFID-enabled label printers, and set variance thresholds for count sessions. RFID is counting-only and does not participate in sales, receiving, or transfers.
| Element | Type | Description | Business Rule |
|---|
| EPC encoding panel | Panel | Company prefix, partition, filter, indicator, format regex; set during onboarding | BRD 5.16.2 |
| Reader list table | Table | Registered readers with name, model, serial, location, status, last_seen_at | BRD 5.16.1 |
| Generate claim code button | Button | Creates 6-character alphanumeric code valid for 24 hours (one-time use) | BRD 5.16.1 |
| Reader status badges | Badge | active (green), offline (yellow/alert after 15min), maintenance, retired | BRD 5.16.1 |
| RFID printer list | Table | Registered RFID printers with model, location, DPI, label size, rfid_position | BRD 5.16.3 |
| Variance threshold config | Panel | Auto-approve (0%), review (1-2%), manager review (3-5%), mandatory recount (>5%) | BRD 5.16.4 |
| Session parameters | Panel | Timeout (480min), auto-save interval (30s), chunk upload size (5000), RSSI threshold (-70dBm) | BRD 5.16.4 |
| Tag stats summary | Badge | Total active tags, tags per location, void/lost counts | BRD 5.16.5 |
| Action | Navigates To | Requires Role |
|---|
| Generate claim code | Same screen (displays code with 24h expiry countdown) | ADMIN+ |
| Register printer | Modal form (stays on screen) | ADMIN+ |
| Edit EPC config | Same screen (inline edit, requires confirmation for changes) | OWNER |
| View scan sessions | Separate RFID session history page | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-21 |
| Product(s) | OWNER |
| BRD Section(s) | 5.18 |
| Database Tables | audit_log (R), audit_config (R/W), tenant_users (R), locations (R) |
| State Machine(s) | None |
| Appendix F Services | setup.audit.config.service, crosscutting.audit-log.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/audit |
The Audit Log Viewer provides a searchable, filterable view of the tamper-evident audit trail for every significant action in the system. Administrators can filter by category (LOGIN, SALE, VOID, etc.), date range, user, location, and entity type. The screen also manages audit configuration including category toggles, retention policies, and export settings.
| Element | Type | Description | Business Rule |
|---|
| Audit log table | Table | Paginated list with category, action, actor, role, location, entity, timestamp, details | BRD 5.18.4 |
| Category filter | Input | Multi-select from 12 audit categories (LOGIN, SALE, RETURN, VOID, etc.) | BRD 5.18.1 |
| Date range picker | Input | Start/end date with max range of 365 days per query | BRD 5.18.3 |
| User filter | Input | Dropdown of all tenant users to filter by actor | BRD 5.18.4 |
| Location filter | Input | Dropdown to filter by location | BRD 5.18.4 |
| Details expansion | Panel | Click-through to JSON details showing before/after values for changes | BRD 5.18.4 |
| Export button | Button | Export filtered results as CSV, JSON, or PDF (max 10,000 rows per export) | BRD 5.18.3 |
| Retention config panel | Panel | Retention days (min 90), archive toggle, archive format, purge after days | BRD 5.18.2 |
| Category toggle panel | Panel | Enable/disable audit logging per category | BRD 5.18.1 |
| Action | Navigates To | Requires Role |
|---|
| Filter audit log | Same screen (results update) | ADMIN+ |
| Export results | CSV/JSON/PDF download | ADMIN+ |
| View entry details | Same screen (expanded detail panel) | ADMIN+ |
| Edit retention config | Same screen (settings panel) | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M05-22 |
| Product(s) | OWNER |
| BRD Section(s) | 5.19 |
| Database Tables | tenant_settings (R/W) |
| State Machine(s) | None |
| Appendix F Services | setup.rules.engine.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/settings/business-rules |
The Business Rules screen provides a structured editor for all configurable business rules across the POS system. Rather than raw YAML editing, the screen presents rules as organised form fields grouped by module (Sales, Customers, Catalog, Inventory). Each field maps to a YAML key in the consolidated configuration with validation, defaults, and contextual help. Advanced users can switch to raw YAML view.
| Element | Type | Description | Business Rule |
|---|
| Module tabs | Panel | Tabs for Sales, Customers, Catalog, Inventory rule sections | BRD 5.19 |
| Return policy fields | Input | Full refund days (30), store credit days (90), restocking fee %, final sale categories | BRD 5.19.1 |
| Parked sales config | Input | Max per terminal (5), TTL hours (4), reservation type (soft/hard) | BRD 5.19.1 |
| Discount limits | Input | Max line discount % (20), max global discount % (15), require reason code toggle | BRD 5.19.1 |
| Cash drawer settings | Input | Variance tolerance ($5.00), blind count toggle, max opening float ($500) | BRD 5.19.1 |
| Offline mode config | Panel | Read-only display of allowed/blocked offline operations | BRD 5.19.1 |
| Inventory rules | Input | Low stock threshold, reorder point formula, count frequency | BRD 5.19.4 |
| Raw YAML toggle | Button | Switch between form view and raw YAML editor for advanced users | BRD 5.19 |
| Reset to defaults button | Button | Resets all rules to system defaults with confirmation | BRD 5.19 |
| Validation indicators | Badge | Green check or red X per field showing valid/invalid configuration | BRD 5.19 |
| Action | Navigates To | Requires Role |
|---|
| Save rules | Same screen (confirmation toast, validation runs) | ADMIN+ |
| Reset to defaults | Confirmation dialog, then same screen | OWNER |
| Switch to YAML view | Same screen (raw YAML editor) | ADMIN+ |
| View rule documentation | Contextual help panel expands | ADMIN+ |
BRD Sections: 6.1-6.13 | Appendix F: §F.9 (20 services) | Pattern: CRUD + Audit ES
Cross-Reference: See Ch 05, Sections 6.1-6.13 for business rules. See Ch 08, Domain 14 (Integration) for table schemas. See Appendix F, §F.9 for service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-M06-01 |
| Product(s) | OWNER |
| BRD Section(s) | 6.11 |
| Database Tables | integration_providers (R), integration_sync_log (R), integration_credentials (R) |
| State Machine(s) | 7.14 Integration Connection States, 7.13 Integration Sync States |
| Appendix F Services | integration.provider.registry.service, integration.circuit-breaker.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations |
The Integration Hub Dashboard is the central management console for all external system integrations. It provides a consolidated health view across all six integration types (Shopify, Amazon, Google Merchant, Payment Processor, Email Provider, Shipping Carrier) with real-time status indicators, sync latency metrics, rate limit usage, and error counts. Administrators can trigger manual syncs and drill into individual integration details.
| Element | Type | Description | Business Rule |
|---|
| Integration cards grid | Panel | Card per configured integration showing status dot, provider name, last sync time, error count | BRD 6.11.4 |
| Health status indicator | Badge | Green (CONNECTED), yellow (RATE_LIMITED), red (ERROR/DISCONNECTED) per integration | BRD 6.11.4 |
| Last sync timestamp | Badge | Time since last successful sync with colour coding (<30min green, 30min-2hr yellow, >2hr red) | BRD 6.11.4 |
| Error count (24h) | Badge | Rolling error count with severity colours (0=green, 1-5=yellow, >5=red) | BRD 6.11.4 |
| Sync latency gauge | Panel | Average sync latency in ms (<2000 green, 2000-5000 yellow, >5000 red) | BRD 6.11.4 |
| Rate limit bar | Panel | Visual bar showing rate limit consumption % per integration | BRD 6.11.4 |
| Sync Now button | Button | Manual sync trigger per integration (requires ADMIN role) | BRD 6.11.4 |
| Add Integration button | Button | Opens provider type selection and connection wizard | BRD 6.11.1 |
| Credential expiry banner | Panel | Warning banner when OAuth token expires within 30 days | BRD 6.11.2 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEXUS ADMIN — Integration Hub [Will] [?] [X] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ INTEGRATION STATUS [+ Add Integration] │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │
│ │ ● Shopify │ │ ○ Amazon SP-API │ │ ○ Google Merch. │ │
│ │ CONNECTED │ │ NOT CONFIGURED │ │ NOT CONFIGURED │ │
│ │ Last sync: 3 min ago │ │ -- │ │ -- │ │
│ │ Errors (24h): 0 │ │ │ │ │ │
│ │ Latency: 1,240ms │ │ [Configure] │ │ [Configure] │ │
│ │ Rate limit: ████░ 62%│ │ │ │ │ │
│ │ [Sync Now] [Details] │ │ │ │ │ │
│ └──────────────────────┘ └──────────────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────┐ │
│ │ ● Payment Processor │ │ ● Email (SendGrid) │ │ ○ Shipping │ │
│ │ CONNECTED │ │ CONNECTED │ │ NOT CONFIGURED │ │
│ │ Last sync: 1 min ago │ │ Last sync: 12 min ago│ │ Planned v2.0 │ │
│ │ Errors (24h): 0 │ │ Errors (24h): 1 │ │ │ │
│ │ Terminals: 4 active │ │ Bounce rate: 0.2% │ │ │ │
│ │ [Details] │ │ [Details] │ │ │ │
│ └──────────────────────┘ └──────────────────────┘ └──────────────────┘ │
│ │
│ RECENT SYNC ACTIVITY │
│ ┌────────┬──────────────────┬───────────┬──────────┬────────┬───────────┐ │
│ │ Time │ Integration │ Type │ Records │ Status │ Duration │ │
│ ├────────┼──────────────────┼───────────┼──────────┼────────┼───────────┤ │
│ │ 14:32 │ Shopify │ WEBHOOK_IN│ 1 │ ✓ │ 340ms │ │
│ │ 14:30 │ Shopify │ RECON │ 847 │ ✓ │ 4,200ms │ │
│ │ 14:28 │ Email │ MANUAL │ 1 │ ✗ │ 1,100ms │ │
│ └────────┴──────────────────┴───────────┴──────────┴────────┴───────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Click integration card | Individual integration detail screen (SCR-M06-02 through SCR-M06-08) | ADMIN+ |
| Sync Now | Same screen (sync status updates in real-time) | ADMIN+ |
| Add Integration | Integration type selection modal | ADMIN+ |
| View sync log | SCR-M06-11 Integration Health Monitor | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-02 |
| Product(s) | OWNER |
| BRD Section(s) | 6.3 |
| Database Tables | integration_providers (R/W), integration_credentials (R/W), tenant_settings (R/W) |
| State Machine(s) | 7.14 Integration Connection States |
| Appendix F Services | integration.shopify.product-sync.service, integration.shopify.webhook-handler.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/shopify/setup |
The Shopify Setup screen manages the OAuth connection to a Shopify store, configures sync mode (POS-master vs bidirectional), and sets up webhook subscriptions. Administrators enter the shop URL, initiate the OAuth flow, verify the connection, and configure the fundamental sync behaviour that determines how product, inventory, and order data flows between the POS and Shopify.
| Element | Type | Description | Business Rule |
|---|
| Shop URL input | Input | Shopify store URL (e.g., nexus-clothes.myshopify.com) | BRD 6.3 |
| Connect button | Button | Initiates OAuth 2.0 flow for offline access token | BRD 6.2.2 |
| Connection status | Badge | NOT_CONFIGURED, CONNECTING, CONNECTED, ERROR | BRD 7.14 |
| Sync mode selector | Input | pos_master (default) or bidirectional | BRD 6.3.1 |
| API preference | Input | GraphQL (default) or REST | BRD 6.3.6 |
| Third-party POS toggle | Input | Enables Shopify third-party POS integration rules | BRD 6.3.12 |
| Webhook status panel | Panel | List of subscribed webhook topics with active/inactive status | BRD 6.3.11 |
| Verify connection button | Button | Tests credentials and API access | BRD 6.2.1 |
| Disconnect button | Button | Revokes OAuth token and marks integration inactive | BRD 6.2.1 |
| Action | Navigates To | Requires Role |
|---|
| Connect to Shopify | Shopify OAuth redirect, then returns to same screen | ADMIN+ |
| Verify connection | Same screen (status badge updates) | ADMIN+ |
| Configure inventory sync | SCR-M06-03 Shopify Inventory Sync Config | ADMIN+ |
| Disconnect | Confirmation dialog, then same screen | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-03 |
| Product(s) | OWNER |
| BRD Section(s) | 6.3, 6.7 |
| Database Tables | integration_providers (R/W), tenant_settings (R/W), locations (R), integration_sync_log (R) |
| State Machine(s) | 7.13 Integration Sync States |
| Appendix F Services | integration.shopify.inventory-sync.service, integration.cross-platform.inventory-orchestrator.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/shopify/inventory |
The Shopify Inventory Sync Config screen manages real-time inventory synchronisation between the POS and Shopify. Administrators configure location-to-Shopify-location mapping, safety buffer quantities, reconciliation intervals, and sync triggers. The screen displays sync status per location and provides controls for the safety buffer system that holds back inventory from online availability.
| Element | Type | Description | Business Rule |
|---|
| Location mapping table | Table | POS locations mapped to Shopify locations for inventory sync | BRD 6.3.1 |
| Safety buffer config | Input | Per-location quantity or percentage to hold back from Shopify availability | BRD 6.7.2 — Channel Available = POS Available - Safety Buffer |
| Reconciliation interval | Input | Minutes between full inventory reconciliation (default: 15) | BRD 6.3.14 |
| Sync trigger list | Panel | Events that trigger immediate inventory sync (sale, return, adjustment, transfer, receiving) | BRD 6.3.14 |
| Last reconciliation status | Badge | Timestamp and result of last full reconciliation | BRD 6.7.1 |
| Oversell prevention toggle | Input | Block sale if available_qty <= 0 | BRD 6.7.3 |
| Sync failure freeze setting | Input | Minutes to freeze marketplace quantity on sync failure (default: 120) | BRD 6.7.5 |
| Action | Navigates To | Requires Role |
|---|
| Save sync config | Same screen (confirmation toast) | ADMIN+ |
| Force reconciliation | Same screen (reconciliation runs, status updates) | ADMIN+ |
| View sync log | SCR-M06-11 Integration Health Monitor (filtered to Shopify) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-04 |
| Product(s) | OWNER |
| BRD Section(s) | 6.3 |
| Database Tables | integration_sync_log (R), orders (R), locations (R), integration_providers (R) |
| State Machine(s) | 7.13 Integration Sync States |
| Appendix F Services | integration.shopify.order-sync.service, integration.shopify.webhook-handler.service |
| User Roles | ADMIN, OWNER, MANAGER |
| Offline Capable | No |
| Route | /admin/integrations/shopify/orders |
The Shopify Order Fulfillment screen displays incoming Shopify orders that require POS-side fulfillment. Orders appear within 60 seconds of placement via webhook, with inventory reserved immediately. Managers can view order details, assign fulfillment to a location, update fulfillment status, and push tracking information back to Shopify.
| Element | Type | Description | Business Rule |
|---|
| Pending orders table | Table | Incoming Shopify orders awaiting fulfillment with order number, items, total, timestamp | BRD 6.3 |
| Fulfillment location selector | Input | Assign order to a POS store location for fulfillment | BRD 6.3 |
| Order detail panel | Panel | Line items, customer info, shipping address, payment status | BRD 6.3 |
| Fulfillment status update | Button | Mark as picking, packed, shipped with tracking number entry | BRD 6.3 |
| BOPIS indicator | Badge | “Buy Online, Pick Up In Store” tag for applicable orders | BRD 6.3.1 |
| Sync status | Badge | Shows if fulfillment update has been pushed to Shopify | BRD 6.3 |
| Action | Navigates To | Requires Role |
|---|
| Assign to location | Same screen (order assigned) | MANAGER+ |
| Mark as fulfilled | Same screen (status pushes to Shopify) | MANAGER+ |
| View order detail | Expandable panel on same screen | MANAGER+ |
| View all sync activity | SCR-M06-11 Integration Health Monitor | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-05 |
| Product(s) | OWNER |
| BRD Section(s) | 6.4 |
| Database Tables | integration_providers (R/W), integration_credentials (R/W), tenant_settings (R/W) |
| State Machine(s) | 7.14 Integration Connection States |
| Appendix F Services | integration.amazon.catalog-sync.service, integration.amazon.order-sync.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/amazon/setup |
The Amazon Setup screen manages the SP-API OAuth connection to Amazon Seller Central. Administrators configure marketplace, region, fulfillment mode (FBM/FBA), and notification delivery method (SQS or polling). The OAuth flow exchanges a Login with Amazon (LWA) refresh token for short-lived access tokens that are automatically refreshed.
| Element | Type | Description | Business Rule |
|---|
| Seller ID input | Input | Amazon Seller Central seller identifier | BRD 6.4.1 |
| OAuth connect button | Button | Initiates LWA OAuth 2.0 flow | BRD 6.4.1 |
| Connection status | Badge | NOT_CONFIGURED, CONNECTING, CONNECTED, ERROR | BRD 7.14 |
| Marketplace selector | Input | US (ATVPDKIKX0DER), CA, UK, etc. | BRD 6.4.1 |
| Region selector | Input | NA, EU, FE | BRD 6.4.1 |
| Fulfillment mode | Input | FBM (Fulfilled by Merchant), FBA (Fulfilled by Amazon), or both | BRD 6.4.5 |
| Order poll interval | Input | Seconds between order polling (default: 120) | BRD 6.4.4 |
| Notification delivery | Input | SQS or polling | BRD 6.4.6 |
| Safety buffer config | Input | Quantity or percentage to hold back from Amazon availability | BRD 6.7.2 |
| Seller code compliance toggle | Input | Enforce Amazon seller code rules | BRD 6.4.8 |
| Action | Navigates To | Requires Role |
|---|
| Connect to Amazon | LWA OAuth redirect, then returns to same screen | ADMIN+ |
| Verify connection | Same screen (status badge updates) | ADMIN+ |
| Configure listings | SCR-M06-06 Amazon Catalog / Listings | ADMIN+ |
| Disconnect | Confirmation dialog, then same screen | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-06 |
| Product(s) | OWNER |
| BRD Section(s) | 6.4 |
| Database Tables | integration_providers (R), integration_sync_log (R), products (R), variants (R) |
| State Machine(s) | 7.16 Product Sync Validation States |
| Appendix F Services | integration.amazon.catalog-sync.service, integration.amazon.inventory-sync.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/amazon/listings |
The Amazon Catalog / Listings screen shows the sync status of all POS products with their Amazon marketplace listings. Administrators can view validation status per product, identify items failing Amazon compliance rules (bullet point limits, search term byte limits, image requirements), and trigger manual sync operations for individual products or in bulk.
| Element | Type | Description | Business Rule |
|---|
| Product listing table | Table | POS products with Amazon sync status, ASIN, listing status, last sync, validation state | BRD 6.4.2 / 6.4.3 |
| Validation status column | Badge | DRAFT, VALID, INVALID, SYNCED, SYNC_FAILED, BLOCKED per product | BRD 7.16 |
| Compliance warnings | Panel | Products failing Amazon rules: max 5 bullet points, 1000 chars/bullet, 250 bytes search terms | BRD 6.4.8 |
| Bulk sync button | Button | Sync all valid products to Amazon via flat-file feed | BRD 6.4.3 |
| Individual sync button | Button | Sync single product to Amazon | BRD 6.4.3 |
| FBA/FBM status | Badge | Per-product fulfillment assignment | BRD 6.4.5 |
| Image validation | Badge | Shows if product images meet Amazon requirements (white background, min 1000px) | BRD 6.6.2 |
| Action | Navigates To | Requires Role |
|---|
| Sync product | Same screen (sync status updates) | ADMIN+ |
| Bulk sync all | Same screen (bulk operation progress bar) | ADMIN+ |
| Fix validation error | Product edit screen in Catalog module | ADMIN+ |
| View sync log | SCR-M06-11 Integration Health Monitor (filtered to Amazon) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-07 |
| Product(s) | OWNER |
| BRD Section(s) | 6.5 |
| Database Tables | integration_providers (R/W), integration_credentials (R/W), tenant_settings (R/W) |
| State Machine(s) | 7.14 Integration Connection States |
| Appendix F Services | integration.google.product-sync.service, integration.google.inventory-sync.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/google/setup |
The Google Merchant Setup screen manages the service account OAuth connection to Google Merchant Center. Administrators upload the service-account JSON key file, configure the Merchant ID, enable Local Inventory Ads (LIA), set product update frequency, and configure Google Business Profile integration for local listing enrichment.
| Element | Type | Description | Business Rule |
|---|
| Merchant ID input | Input | Google Merchant Center merchant identifier | BRD 6.5.1 |
| Service account key upload | Input | JSON key file upload (stored encrypted) | BRD 6.5.1 |
| Connection status | Badge | NOT_CONFIGURED, CONNECTING, CONNECTED, ERROR | BRD 7.14 |
| Local Inventory Ads toggle | Input | Enable/disable LIA for local inventory visibility in Google Shopping | BRD 6.5.3 |
| Product update frequency | Input | 2x_daily (default), daily, or hourly | BRD 6.5 |
| Image validation strict toggle | Input | Enforce Google image requirements (min 1000x1000, no watermarks, no text overlay) | BRD 6.5.7 |
| GTIN required toggle | Input | Require barcode (GTIN/UPC/EAN) for all products synced to Google | BRD 6.5.6 |
| Content API migration banner | Panel | Deadline reminder for Merchant API migration (2026-08-18) | BRD 6.5.10 |
| Action | Navigates To | Requires Role |
|---|
| Upload service account key | Same screen (connection test runs) | ADMIN+ |
| Verify connection | Same screen (status badge updates) | ADMIN+ |
| Configure validation | SCR-M06-08 Google Validation Dashboard | ADMIN+ |
| Disconnect | Confirmation dialog, then same screen | OWNER |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-08 |
| Product(s) | OWNER |
| BRD Section(s) | 6.5 |
| Database Tables | integration_providers (R), integration_sync_log (R), products (R), variants (R) |
| State Machine(s) | 7.16 Product Sync Validation States |
| Appendix F Services | integration.google.product-sync.service, integration.cross-platform.validation.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/google/validation |
The Google Validation Dashboard shows product compliance status against Google Merchant Center requirements. Administrators can identify products with disapproval risks (missing GTIN, invalid images, incorrect pricing, missing product type taxonomy) and fix issues before they cause Google disapprovals. The disapproval prevention engine pre-validates products before pushing.
| Element | Type | Description | Business Rule |
|---|
| Validation summary cards | Panel | Total products, valid count, invalid count, blocked count, synced count | BRD 6.5.8 |
| Invalid products table | Table | Products failing Google rules with specific failure reasons | BRD 6.5.8 |
| Image compliance column | Badge | Pass/fail per product for image requirements (size, format, no watermarks) | BRD 6.5.7 |
| GTIN/barcode status | Badge | Missing barcode indicator per product | BRD 6.5.6 |
| Price match validation | Badge | Verifies POS price matches Google listing price | BRD 6.5 |
| Product type taxonomy | Badge | Google product category assignment status | BRD 6.5.6 |
| Disapproval prevention log | Table | Products caught by pre-validation before being pushed to Google | BRD 6.5.8 |
| Action | Navigates To | Requires Role |
|---|
| Fix product issue | Product edit screen in Catalog module | ADMIN+ |
| Re-validate product | Same screen (validation re-runs) | ADMIN+ |
| Force sync valid products | Same screen (bulk push to Google) | ADMIN+ |
| View disapproval details | Expandable detail panel per product | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-09 |
| Product(s) | OWNER |
| BRD Section(s) | 6.6 |
| Database Tables | integration_providers (R), products (R), variants (R), integration_sync_log (R) |
| State Machine(s) | 7.16 Product Sync Validation States |
| Appendix F Services | integration.cross-platform.validation.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/validation |
The Cross-Platform Validation screen applies the strictest-rule-wins validation engine across all connected channels (Shopify, Amazon, Google Merchant). It shows a unified view of product readiness per platform, identifies which platform’s rules are causing failures, and provides a consolidated validation matrix for titles, descriptions, images, barcodes, and required attributes.
| Element | Type | Description | Business Rule |
|---|
| Platform readiness matrix | Table | Products x Platforms grid showing pass/fail per channel | BRD 6.6 — strictest-rule-wins |
| Unified validation rules | Panel | Combined requirements: title max 150 chars, description max 5000 chars, image min 1000px, no watermarks | BRD 6.6.1 |
| Image requirements matrix | Table | Per-platform image requirements side-by-side comparison | BRD 6.6.2 |
| Failing products list | Table | Products that fail at least one platform’s validation with specific failure reasons per platform | BRD 6.6.3 |
| Pre-sync validation toggle | Input | Enable/disable automatic pre-sync validation before pushing to any channel | BRD 6.6.3 |
| Platform-specific attributes | Panel | Required fields per platform (Amazon bullet points, Google product type, Shopify tags) | BRD 6.6.4 |
| Action | Navigates To | Requires Role |
|---|
| Fix product issue | Product edit screen in Catalog module | ADMIN+ |
| Re-validate all products | Same screen (bulk re-validation runs) | ADMIN+ |
| View platform detail | SCR-M06-06/08 (Amazon/Google validation screens) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-10 |
| Product(s) | OWNER |
| BRD Section(s) | 6.7 |
| Database Tables | integration_providers (R), integration_sync_log (R), inventory_levels (R), locations (R) |
| State Machine(s) | 7.13 Integration Sync States |
| Appendix F Services | integration.cross-platform.inventory-orchestrator.service, integration.shopify.inventory-sync.service, integration.amazon.inventory-sync.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/inventory |
The Inventory Sync Dashboard provides a unified view of inventory levels across all connected channels (POS, Shopify, Amazon, Google). Administrators monitor safety buffer calculations, channel-available quantities, oversell prevention status, and sync failure freeze states. The screen shows real-time inventory allocation across platforms with the formula: Channel Available = POS Available - Safety Buffer.
| Element | Type | Description | Business Rule |
|---|
| Channel inventory table | Table | Product x Channel grid showing POS qty, safety buffer, channel-available qty per platform | BRD 6.7.2 |
| Safety buffer summary | Panel | Per-location and per-channel buffer configuration with current allocation | BRD 6.7.2 |
| Sync status per channel | Badge | Last sync time, success/failure, latency per channel | BRD 6.7.1 |
| Oversell prevention status | Badge | Active/inactive indicator with oversell event count | BRD 6.7.3 |
| Sync failure freeze indicator | Badge | Products currently frozen due to sync failure (120-min freeze window) | BRD 6.7.5 |
| Reconciliation schedule | Panel | Next scheduled reconciliation per channel (Shopify 15min, Amazon 30min, Google 6hr) | BRD 6.7.1 |
| Force reconciliation button | Button | Trigger immediate full inventory reconciliation across all channels | BRD 6.7.1 |
| Action | Navigates To | Requires Role |
|---|
| Force reconciliation | Same screen (reconciliation runs) | ADMIN+ |
| Edit safety buffers | Same screen (inline edit per channel/location) | ADMIN+ |
| View sync failures | SCR-M06-12 Error DLQ Management | ADMIN+ |
| View channel detail | Platform-specific sync config (SCR-M06-03) | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-11 |
| Product(s) | OWNER |
| BRD Section(s) | 6.11 |
| Database Tables | integration_sync_log (R), integration_providers (R) |
| State Machine(s) | 7.13 Integration Sync States, 7.14 Integration Connection States |
| Appendix F Services | integration.provider.registry.service, integration.circuit-breaker.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/health |
The Integration Health Monitor provides a detailed sync log and operational metrics across all integrations. Administrators can filter by integration type, sync type (webhook, scheduled, manual, bulk), status, date range, and entity type. The screen shows circuit breaker states, retry attempts, and dead-letter queue entries for failed operations.
| Element | Type | Description | Business Rule |
|---|
| Sync log table | Table | Paginated log with integration, sync_type, direction, entity_type, status, records, duration, timestamp | BRD 6.11.3 |
| Integration type filter | Input | Multi-select: Shopify, Amazon, Google, Payment, Email, Shipping | BRD 6.11.3 |
| Sync type filter | Input | WEBHOOK_IN, WEBHOOK_OUT, SCHEDULED_PULL, SCHEDULED_PUSH, RECONCILIATION, MANUAL, BULK_OPERATION, NOTIFICATION | BRD 6.11.3 |
| Status filter | Input | SUCCESS, FAILED, PARTIAL, SKIPPED, RETRYING | BRD 6.11.3 |
| Circuit breaker status | Panel | Per-provider circuit state: CLOSED (green), HALF_OPEN (yellow), OPEN (red) | BRD 6.2.4 |
| Error detail expansion | Panel | Click-through to full error_details text for failed entries | BRD 6.11.3 |
| Retry status tracker | Badge | Shows retry attempt count and next retry time for RETRYING entries | BRD 6.2.3 |
| Action | Navigates To | Requires Role |
|---|
| Filter sync log | Same screen (results update) | ADMIN+ |
| View error details | Same screen (expanded detail panel) | ADMIN+ |
| Retry failed operation | Same screen (retry initiated) | ADMIN+ |
| View DLQ entries | SCR-M06-12 Error DLQ Management | ADMIN+ |
| Attribute | Value |
|---|
| Screen ID | SCR-M06-12 |
| Product(s) | OWNER |
| BRD Section(s) | 6.2 |
| Database Tables | integration_sync_log (R/W), integration_providers (R) |
| State Machine(s) | 7.13 Integration Sync States |
| Appendix F Services | integration.dead-letter.service, integration.idempotency.service |
| User Roles | ADMIN, OWNER |
| Offline Capable | No |
| Route | /admin/integrations/dlq |
The Error DLQ (Dead-Letter Queue) Management screen displays integration messages that have failed all retry attempts (3 retries with exponential backoff: 5s, 15s, 45s) and been moved to the dead-letter queue for manual review. Administrators can inspect error details, retry individual messages, replay batches, or discard messages that are no longer relevant. The DLQ retains entries for 24 hours before auto-purge.
| Element | Type | Description | Business Rule |
|---|
| DLQ entries table | Table | Failed messages with integration, entity_type, entity_id, external_id, error details, failed_at | BRD 6.2.3 |
| Error detail panel | Panel | Full error message, stack trace, request/response payloads | BRD 6.2.3 |
| Retry button | Button | Re-enqueue message for another round of retries (with new idempotency window) | BRD 6.2.5 |
| Batch retry button | Button | Retry all selected DLQ entries | BRD 6.2.3 |
| Discard button | Button | Remove message from DLQ (acknowledge as unrecoverable) | BRD 6.2.3 |
| Integration filter | Input | Filter by integration type | BRD 6.2.3 |
| Age indicator | Badge | Time since message entered DLQ; highlight entries nearing 24-hour auto-purge | BRD 6.2.3 |
| Retry count | Badge | Number of previous retry attempts per message | BRD 6.2.3 |
| Action | Navigates To | Requires Role |
|---|
| Retry message | Same screen (message re-enqueued, status updates) | ADMIN+ |
| Batch retry | Same screen (selected messages re-enqueued) | ADMIN+ |
| Discard message | Confirmation dialog, then same screen | ADMIN+ |
| View source entity | Navigates to relevant entity screen (product, order, etc.) | ADMIN+ |
This section documents the POS terminal experience — the screens and navigation flows specific to the sales register context within the Nexus POS web application (ADR-052). While individual screen specs are in G.4-G.9 by module, this section covers POS navigation, hardware integration, offline behavior, keyboard shortcuts, and screen transition flows.
The Nexus POS terminal uses a sidebar-primary layout optimized for fixed-position retail terminals. When a CASHIER logs in, the app opens directly to the Sales Terminal with a transaction-focused sidebar. MANAGER and OWNER roles see an expanded navigation with access to administrative sections (reports, inventory, setup, integrations) in addition to the POS sidebar.
The POS screen is divided into three zones:
| Zone | Position | Width | Content |
|---|
| Sidebar | Left | 64px (collapsed) / 240px (expanded) | Primary navigation icons/labels |
| Content Area | Center | Remaining | Active screen content |
| Status Bar | Top | Full width, 48px | Connection indicator, location name, clock, user avatar |
| Icon | Label | Route | Description | Register Profile |
|---|
| Cart | Sales | /pos/sales | Active sale screen with product grid, cart panel, and payment | FULL_POS, MOBILE |
| Search | Lookup | /pos/lookup | Product search by barcode, SKU, or name — shows price, stock, location availability | FULL_POS, MOBILE |
| Users | Customers | /pos/customers | Customer search, attach to sale, view purchase history, loyalty balance | FULL_POS |
| Box | Inventory | /pos/inventory | Quick stock check, count participation, adjustment requests | FULL_POS |
| Clock | Time Clock | /pos/timeclock | Clock-in/clock-out for current user | FULL_POS, MOBILE |
| DollarSign | Drawer | /pos/drawer | Cash drawer operations: open, drop, X-Report, Z-Report | FULL_POS |
| FileText | History | /pos/history | Today’s transaction history for this register — reprint receipts, view details | FULL_POS |
| Settings | Settings | /pos/settings | Register-local settings (receipt format, display brightness) | FULL_POS |
The sidebar collapses to icon-only mode on smaller displays (< 1280px) and can be toggled via the hamburger menu icon at the top.
Since Nexus POS is a single web app (ADR-052), the navigation adapts based on the logged-in user’s role:
| Role | Default Screen on Login | Sidebar Sections Visible | Hardware Actions | Authentication |
|---|
| CASHIER | Sales Terminal | Sales, Lookup, Customers, Inventory (count only), Time Clock, Drawer, History | Print receipt, open drawer, scan barcode | PIN-based login (4-6 digit numeric PIN via POST /auth/pin-login) |
| MANAGER | Dashboard | All CASHIER sections + Sales Reports, Catalog, Inventory (full), Setup (partial) | Same as CASHIER (when at register) | Email + password or PIN |
| OWNER | Dashboard | All sections including Setup (full), Integrations | Same as CASHIER (when at register) | Email + password |
| BUYER | Catalog | Catalog, Inventory (POs, vendors, reorder) | None (back-office role) | Email + password |
| AUDITOR | Inventory | Inventory (counts), Audit Log | None (back-office role) | Email + password |
When a MANAGER or OWNER navigates to the Sales Terminal, the POS sidebar replaces the admin navigation, providing the same transaction-focused experience as a CASHIER.
At the top of the Sales screen, a persistent quick-access toolbar provides one-tap shortcuts for the most common mid-sale actions:
| Button | Action | Shortcut |
|---|
| New Sale | Clear cart and start a new transaction | F1 |
| Customer | Open customer search overlay, attach to current sale | F2 |
| Price Check | Open price check dialog (scan or type barcode) | F3 |
| Park Sale | Park current cart (save for later retrieval) | F4 |
| Retrieve | Retrieve a previously parked sale | F5 |
| Void | Void the current transaction (requires Manager role) | F8 |
The Nexus POS web application integrates with retail peripherals via web-compatible protocols (WebUSB, Star WebPRNT, Stripe Terminal JS SDK) and standard network interfaces. All hardware interactions are abstracted behind a HardwareService interface so that the React UI layer never directly communicates with physical devices.
| Attribute | Value |
|---|
| Protocol | USB HID (keyboard wedge mode) |
| Supported Devices | Any USB barcode scanner that emits keyboard events (Zebra DS2208, Honeywell Voyager, Symbol LS2208) |
| Connection | USB wired — plug and play, no driver required |
| Data Format | Barcode string terminated by Enter key (configurable: CR, LF, or CR+LF) |
| Integration Method | Global keyboard event listener in React — detects rapid keystroke sequences (< 50ms between characters) as scanner input vs. manual typing |
Focus Management: The barcode scanner input is captured globally regardless of which UI element has focus. When a scan is detected on the Sales screen, the system automatically performs a product lookup (API or product_cache) and adds the item to the cart. On non-Sales screens (e.g., Inventory Lookup), the scan triggers a product search instead.
Scan Detection Logic: The POS uses a timing-based heuristic to distinguish scanner input from keyboard typing:
- Characters arriving within 50ms of each other are buffered as a scan sequence
- The sequence is finalized when an Enter key is received or 200ms elapses after the last character
- Sequences shorter than 3 characters are ignored (likely accidental keypresses)
| Attribute | Value |
|---|
| Protocol | ESC/POS (Epson Standard Code for Point of Sale) |
| Supported Devices | Epson TM-T88VI, Star TSP143IV, Star mC-Print3 |
| Connection | USB or network (TCP/IP port 9100) |
| Paper Width | 80mm (default), 58mm (compact) |
| Integration Method | Star WebPRNT SDK (HTTP/HTTPS to network printers) or WebUSB API for USB-connected printers. ESC/POS byte stream generated in the browser via receipt-printer-encoder library. |
Receipt Content: Receipts are composed in the React layer as a structured receipt object (store name, items, totals, payment breakdown, barcode) and serialized to ESC/POS commands by the browser-side print service. Offline sales include an “OFFLINE” watermark below the store header.
Receipt Reprint: Receipts for today’s transactions can be reprinted from the History screen. The system stores the receipt data (not the rendered ESC/POS bytes) so reprints reflect the original sale data.
| Attribute | Value |
|---|
| Protocol | DK port trigger (RJ-12 cable from receipt printer) |
| Supported Devices | Any cash drawer with DK port (APG Vasario, Star CD3-1616) |
| Connection | Connected to receipt printer’s DK port — drawer opens when printer sends the open command |
| Integration Method | ESC/POS drawer kick pulse (0x1B 0x70 0x00) sent via the same Star WebPRNT / WebUSB channel used for receipt printing. Cash drawers connect to the printer’s DK port (kick-out cable). |
Business Rules: The cash drawer opens automatically at the end of a cash sale. Manual drawer open requires the cash_drawer_operations feature toggle (enabled for STAFF, MANAGER, OWNER by default). All drawer open events are logged in the audit trail with user ID, timestamp, and reason (sale_complete, manual_open, cash_drop, drawer_count).
| Attribute | Value |
|---|
| Protocol | Semi-integrated (SAQ-A compliant) |
| Supported Devices | Verifone P400, Ingenico Lane/3000, PAX A80 |
| Connection | Network (TCP/IP) — POS sends amount, terminal handles card interaction |
| PCI Scope | SAQ-A: No card data touches the POS system. The payment terminal handles all card reads, PIN entry, and encryption. POS receives only authorization codes and masked card numbers (last 4 digits). |
| Integration Method | Stripe Terminal JS SDK (or equivalent vendor SDK) sends amount to terminal via the browser. Terminal returns authorization result. |
Payment Flow: POS sends { amount, currency, transactionType } to the payment terminal. The terminal displays amount, processes card tap/insert/swipe, communicates with the payment processor, and returns { approved, authCode, maskedPan, cardBrand } to the POS. If the terminal is unreachable, the POS shows “Payment terminal offline — use cash or try again.”
Offline Limitation: Card payments are blocked offline (see G.10.3). Only cash payments are accepted during OFFLINE mode because the payment terminal requires network connectivity to reach the payment processor.
| Attribute | Value |
|---|
| Protocol | USB HID (WebUSB API) or network-connected readers (HTTP/TCP) |
| Supported Devices | Zebra FX9600 (fixed reader, dock door, network), Zebra RFD40 (USB sled) |
| Connection | USB (WebUSB) or Ethernet (fixed readers via REST/LLRP gateway) |
| Use Case | Web POS RFID operations: tag lookup, tag void, tag status check. Bulk scanning is handled by the Raptag mobile app (G.11). |
| Integration Method | WebUSB API for USB-connected readers; HTTP REST calls for network-attached readers via RFID gateway service |
Scope: RFID readers connected to the web POS are used for individual tag operations only (e.g., looking up a tag during a count discrepancy investigation, voiding a damaged tag). Bulk inventory counting uses the Raptag mobile app with handheld readers.
The Nexus POS operates in an online-first architecture (ADR-048). All reads and writes go through the Central API via React Query during normal operation. When connectivity is lost, the POS falls back to a thin 2-table SQLite WASM database (sql.js or wa-sqlite backed by OPFS) for sales continuity.
The connection monitor uses three detection layers (Socket.io events, HTTP health ping every 5s, navigator.onLine API) to determine the current state:
| State | Trigger | UI Indicator | Data Reads | Data Writes |
|---|
| ONLINE | WebSocket connected + health ping OK | Green dot + “Connected” | React Query → Central API | POST → Central API |
| DEGRADED | WebSocket dropped, health ping intermittent | Yellow dot + “Unstable” | Try API (2s timeout) → fallback to SQLite product_cache | POST → API + local backup copy in sales_queue |
| OFFLINE | 3 consecutive health pings fail (~15s) | Red dot + banner: “Working offline. N sales queued. Prices may be outdated.” | SQLite product_cache only | SQLite sales_queue (append-only, FIFO) |
SYNCING (recovery sub-state): When connectivity restores, the monitor enters SYNCING — yellow dot with “Syncing 2/3…” progress text. The sales_queue is flushed oldest-first. On completion, the state transitions to ONLINE.
| Operation | Details |
|---|
| New sale (cash only) | Product prices from product_cache. Sale written to sales_queue. Receipt printed with “OFFLINE” watermark. |
| Return with receipt | Original receipt data available locally. Return queued for sync. |
| Price check | From product_cache. Stale warning shown if cache > 60 minutes old. |
| Park sale | Cart state saved to local storage. |
| Retrieve parked sale | Parked carts retrieved from local storage. |
| Operation | Reason |
|---|
| Card payment | Payment terminal requires network to reach processor |
| Customer create/lookup | Requires uniqueness check against Central API |
| Credit limit check / on-account payment | Risk of exceeding balance without real-time verification |
| Gift card activation / reload / redeem / balance | Risk of double-activation or stale balance |
| Multi-store inventory lookup | Requires network to query other locations |
| Transfer request / reservation create | Requires coordination with other locations |
| Inventory adjustment / receiving | Requires server-side validation and approval workflow |
When a user attempts a blocked operation offline, the POS shows a modal: “This feature requires an internet connection. Please try again when connected.” The blocked action button is visually disabled (grayed out) with a “requires connection” tooltip.
The fallback database runs in the browser via SQLite WASM (sql.js or wa-sqlite), with persistence to the Origin Private File System (OPFS) for durability across page reloads and browser restarts.
| Table | Purpose | Size Estimate |
|---|
| product_cache | Read-only product data (id, sku, barcode, name, price, cost, tax_code, variants). Pre-warmed on startup. Updated via WebSocket push events. | ~5MB for 10,000 SKUs |
| sales_queue | Append-only offline transactions. Each row contains full sale data as JSON (line items, payments, totals). UUID sale_id for idempotent sync. | ~1KB per sale |
The product_cache includes a last_refreshed timestamp. If the cache is older than 60 minutes during offline mode, the POS shows a subtle warning banner: “Product data may be outdated.”
When the sales_queue flushes on reconnection, the Central API compares each line item’s unit_price (from the stale product_cache) against the current server price:
| Scenario | Server Action | Manager Review |
|---|
| Price match | Accept sale normally | None |
| Price changed | Accept sale at current server price; log discrepancy (sold_price, current_price, difference) | Review flagged transactions in Nexus POS (MANAGER+ dashboard); decide if customer credit is warranted |
| Item out of stock | Record sale; flag negative inventory | Approve negative balance or adjust |
| Customer deleted | Reassign to “Walk-in Customer” | Informational |
| Promotion expired | Apply current (non-promotional) price | Review flagged transactions |
Discrepancies appear in the Nexus POS manager dashboard under “Price Discrepancies” with [Issue Credit] and [Dismiss] actions per transaction.
The POS terminal supports function key shortcuts for rapid operation. These are active whenever the POS application has focus, regardless of which screen is displayed.
| Key | Action | Context | Required Role |
|---|
| F1 | New Sale | Any screen — navigates to Sales, clears cart | ALL |
| F2 | Customer Lookup | Sales screen — opens customer search overlay | ALL |
| F3 | Price Check | Any screen — opens price check dialog (scan or type barcode) | ALL |
| F4 | Park Sale | Sales screen — saves current cart for later retrieval | ALL |
| F5 | Retrieve Parked Sale | Sales screen — opens list of parked sales | ALL |
| F6 | Inventory Lookup | Any screen — opens stock level search by barcode or SKU | ALL |
| F7 | Transaction History | Any screen — opens today’s register transaction list | ALL |
| F8 | Void Transaction | Sales screen — voids the current or last transaction | MANAGER, OWNER |
| F9 | Apply Discount | Sales screen — opens discount dialog (line-item or cart-level) | ALL (amount limits apply) |
| F10 | Open Cash Drawer | Sales screen — manual drawer open | ALL (requires cash_drawer_operations toggle) |
| F11 | Manager Override | Any screen — prompts for manager PIN to authorize restricted actions | MANAGER, OWNER |
| F12 | Lock Terminal | Any screen — locks the POS to the PIN entry screen (preserves current sale) | ALL |
Barcode scans are intercepted globally via a keyboard event listener. The scan detection algorithm distinguishes rapid scanner input (< 50ms between keystrokes) from manual typing:
- Sales screen: Scan adds item to cart (or increments quantity if already in cart)
- Lookup screen: Scan populates the search field and triggers product detail display
- Inventory screen: Scan shows stock levels across all locations for the scanned product
- Any other screen: Scan opens a floating product info tooltip (price, stock, image)
The Sales screen supports a configurable grid of quick-key buttons for high-frequency items that lack barcodes (e.g., gift wrapping, alterations, miscellaneous charges). Quick keys are configured under Settings > Registers > Quick Keys (OWNER role) and synced to the POS terminal via WebSocket.
| Attribute | Value |
|---|
| Grid size | 4x5 (20 buttons, configurable) |
| Button content | Product name + price, color-coded by category |
| Location scope | Per-register (different registers can have different quick-key layouts) |
When a restricted action is attempted by a STAFF user (e.g., void, price override beyond discount limit), the system prompts for a manager PIN:
- Modal appears: “Manager authorization required for [action name]”
- Manager enters their PIN on the numeric keypad
- System validates PIN against users with MANAGER or OWNER role at this tenant
- If valid, the action proceeds under the manager’s authority (logged as
authorized_by in the audit trail)
- If invalid, the action is denied with “Invalid manager PIN”
The F11 shortcut opens this same override prompt pre-emptively, allowing a manager to authorize before the restricted action is attempted.
Login → Terminal → Cart → Payment → Receipt
=========================================================
[PIN Entry]
│
▼
[Sales Screen] ◄──────────────────────────────────────┐
│ │
│ scan/search │
▼ │
[Product Added to Cart] │
│ │
│ (repeat for each item) │
│ │
▼ │
[Cart Review] │
│ ├── [Apply Discount] (F9) │
│ ├── [Attach Customer] (F2) │
│ └── [Park Sale] (F4) ──► [Parked Sales List] │
│ │
│ [Pay] button │
▼ │
[Payment Dialog] │
│ ├── Cash: enter tendered amount │
│ ├── Card: send to payment terminal │
│ ├── Gift Card: scan/enter card number │
│ ├── On Account: select customer account │
│ └── Split: combine multiple payment methods │
│ │
│ all payments applied │
▼ │
[Receipt Printed] │
│ ├── Print receipt (ESC/POS) │
│ ├── Email receipt (if customer attached) │
│ └── Cash drawer opens (if cash payment) │
│ │
└──────────────── [New Sale] (F1) ─────────────────┘
Terminal → Return Lookup → Item Selection → Refund → Receipt
=========================================================
[Sales Screen]
│
│ [Returns] button or navigate to History
▼
[Return Lookup]
│ ├── Scan receipt barcode
│ ├── Enter sale number manually
│ └── Search by date + register
│
│ original sale found
▼
[Original Sale Details]
│ ├── View all line items from original sale
│ ├── Check return eligibility per item
│ └── Items already returned are grayed out
│
│ select items to return
▼
[Return Item Selection]
│ ├── Select quantity per item (up to original qty)
│ ├── Select reason code (defective, wrong_size, etc.)
│ └── Select return action: refund or exchange
│
│ [Process Return] button
▼
[Refund Method]
│ ├── Original payment method (default)
│ ├── Store credit
│ └── Cash (if manager authorized)
│
│ refund applied
▼
[Return Receipt Printed]
│ ├── Print return receipt
│ ├── Inventory restocked (if return_to_stock)
│ └── Customer loyalty points adjusted
│
└──── back to [Sales Screen]
Open Drawer → X-Report → Z-Report → Close
=========================================================
[Start of Day]
│
│ Manager navigates to Drawer screen
▼
[Open Drawer]
│ ├── Enter starting cash amount (counted bills/coins)
│ ├── System records opening_balance
│ └── Drawer status: OPEN
│
│ (normal sales throughout the day)
│
▼
[Mid-Day: X-Report] (non-destructive read)
│ ├── View running totals: cash, card, gift card
│ ├── View transaction count by payment method
│ ├── Expected cash = opening_balance + cash_in - cash_out
│ └── Does NOT reset counters
│
│ (optional: cash drop)
▼
[Cash Drop] (if drawer has excess cash)
│ ├── Enter drop amount
│ ├── System records cash_drop event
│ ├── Expected cash reduced by drop amount
│ └── Manager signature/PIN required
│
│ (end of day)
▼
[Z-Report / Close Drawer]
│ ├── Enter counted cash amount (actual physical count)
│ ├── System calculates variance (counted - expected)
│ ├── Display variance: $0.00 = green, < $5 = yellow, > $5 = red
│ ├── Print Z-Report (end-of-day summary)
│ ├── Drawer status: CLOSED
│ └── Register locked until next opening
│
└──── [Drawer Closed — Register Locked]
BRD Section: 4.6.8 (RFID Counting Subsystem) + 5.16 (RFID Configuration) | Appendix F: Section F.10A (6 services) | Tech: React Native + Expo (ADR-047)
This section provides full screen specifications for the Nexus Raptag mobile RFID counting application. Unlike the Nexus POS web app, Raptag is a separate React Native app deployed to iOS and Android via Expo (ADR-047).
Cross-Reference: See Ch 05, Section 4.6.8 for RFID counting business rules. See Ch 08, Domain 16 (RFID) for table schemas. See Appendix F, Section F.10A for RFID service breakdown.
| Attribute | Value |
|---|
| Screen ID | SCR-R01 |
| Product(s) | Raptag |
| BRD Section(s) | 5.5 |
| Database Tables | users (R), tenants (R), roles (R), user_locations (R) |
| State Machine(s) | – |
| Appendix F Services | auth.login.service |
| User Roles | ALL |
| Offline Capable | Yes (cached credentials for returning users) |
| Route | /login |
The Login screen authenticates Raptag operators against the Central API using email and password credentials. Unlike the POS terminal (which uses numeric PIN entry for speed), Raptag uses standard email/password authentication because operators log in once per session rather than switching users frequently. Returning users can authenticate offline using cached credential hashes stored in the device’s secure storage.
| Element | Type | Description | Business Rule |
|---|
| Tenant Selector | Dropdown | Select tenant (shown only if user belongs to multiple tenants) | Pre-populated from last login; stored in AsyncStorage |
| Email Field | Text Input | User’s login email address | Validated against users.email with users.is_active = true |
| Password Field | Secure Input | Password with show/hide toggle | Verified against users.password_hash (bcrypt) |
| Remember Me | Toggle | Cache credentials for offline re-authentication | Stores bcrypt hash in device secure storage (Expo SecureStore) |
| Login Button | Primary Button | Submit credentials to POST /auth/login | Disabled until both fields non-empty; shows spinner during request |
| Server URL | Settings Link | Configure Central API endpoint (first-time setup only) | Stored in AsyncStorage; hidden after initial configuration |
| Offline Badge | Info Banner | “Offline mode — using cached credentials” shown when device is disconnected | Only appears if cached credentials exist and device has no connectivity |
| Action | Navigates To | Requires Role |
|---|
| Successful login (online) | SCR-R02 Home Dashboard | ALL |
| Successful login (offline, cached) | SCR-R02 Home Dashboard (limited features) | ALL |
| Failed login (wrong credentials) | Stay on SCR-R01 with error message | – |
| Account locked | Stay on SCR-R01 with “Account locked” message | – |
| Attribute | Value |
|---|
| Screen ID | SCR-R02 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8 |
| Database Tables | rfid_scan_sessions (R), session_operators (R), rfid_config (R), devices (R) |
| State Machine(s) | RFID Session (7.11) |
| Appendix F Services | rfid.scan.command.service, rfid.config.crud.service |
| User Roles | ALL |
| Offline Capable | Partial (shows locally cached session data; cannot fetch new sessions) |
| Route | /home |
The Home Dashboard is the primary landing screen after login. It displays the operator’s active session (if any), a list of available sessions at their assigned location, recent session history, and device/reader status. It serves as the central hub from which operators join existing sessions or managers create new ones.
| Element | Type | Description | Business Rule |
|---|
| Active Session Card | Highlight Card | Shows current session if operator is participating (session name, type, section assignment, tag count, elapsed time) | Only one active session per operator at a time (enforced by session_operators unique constraint) |
| Available Sessions List | Scrollable List | Sessions at operator’s location with status in_progress that they haven’t joined yet | Filtered by rfid_scan_sessions.location_id matching operator’s assigned location |
| New Session Button | FAB (Floating Action Button) | Create a new counting session | Requires MANAGER or OWNER role; opens SCR-R03 |
| Reader Status Indicator | Status Badge | Shows connected RFID reader model and battery level | Green = connected, Yellow = low battery (< 20%), Red = disconnected |
| Recent Sessions | Card List | Last 5 completed sessions with variance summary | Tapping opens session summary (SCR-R06, read-only) |
| Pending Uploads | Warning Badge | Count of sessions with un-synced scan data | Shows “3 sessions pending upload” with upload button → SCR-R07 |
| Location Name | Header Text | Current location name (from user_locations.is_primary) | Operator cannot change location from Raptag; set in Nexus POS (OWNER > Setup > Locations) |
| Action | Navigates To | Requires Role |
|---|
| Tap “Active Session” card | SCR-R04 Scanning Interface (resume scanning) | ALL |
| Tap “New Session” FAB | SCR-R03 Join / Start Session | MANAGER, OWNER |
| Tap available session → “Join” | SCR-R05 Section Assignment | ALL |
| Tap “Pending Uploads” | SCR-R07 Chunked Upload / Sync | ALL |
| Tap recent session card | SCR-R06 Session Summary (read-only) | ALL |
| Tap reader status | SCR-R08 Device Pairing | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R03 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8, 5.16 |
| Database Tables | rfid_scan_sessions (W), session_operators (W), locations (R), rfid_config (R) |
| State Machine(s) | RFID Session (7.11): [*] → in_progress |
| Appendix F Services | rfid.scan.command.service, rfid.config.crud.service |
| User Roles | MANAGER, OWNER (create); ALL (join) |
| Offline Capable | Yes (session created locally in SQLite, synced later) |
| Route | /session/new |
This screen allows managers to create new RFID counting sessions and operators to join existing sessions. When creating a session, the manager selects the count type, location, and assigns sections to operators. When joining, the operator selects their assigned section and confirms their reader device.
| Element | Type | Description | Business Rule |
|---|
| Session Type Selector | Segmented Control | full_inventory, cycle_count, spot_check, find_item | See BRD Section 5.16.4 for type definitions |
| Location Display | Read-only Text | Pre-filled with operator’s primary location | Sessions are location-scoped; cannot count across locations |
| Section List | Editable List | Manager defines sections (e.g., “Men’s Tops”, “Women’s Bottoms”, “Accessories”) | Free-text section names; at least one section required |
| Operator Assignment | Multi-select | Assign operators to sections from a list of active users at the location | Max 10 operators per session; each operator assigned exactly one section |
| Session Name | Text Input | Optional friendly name (e.g., “Q1 Full Count - March 2026”) | Auto-generated as {session_type}-{location_code}-{date} if left blank |
| Expected Count | Number Input | Optional expected tag count for variance calculation | If provided, used to calculate variance % on SCR-R06 |
| Start Session Button | Primary Button | Creates session and transitions to scanning | Writes to rfid_scan_sessions (status: in_progress) and session_operators |
| Join Existing Panel | Card | Shows session details for joining (session name, type, available sections) | Operator selects their section and taps “Join” |
| Action | Navigates To | Requires Role |
|---|
| Tap “Start Session” (create mode) | SCR-R04 Scanning Interface | MANAGER, OWNER |
| Tap “Join Session” (join mode) | SCR-R05 Section Assignment → SCR-R04 | ALL |
| Cancel | SCR-R02 Home Dashboard | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R04 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8, 5.16 |
| Database Tables | rfid_scan_events (W, local SQLite), rfid_tags (R, cached), rfid_tag_mappings (R, cached) |
| State Machine(s) | RFID Session (7.11): in_progress |
| Appendix F Services | rfid.scan.command.service, rfid.tag.crud.service |
| User Roles | ALL |
| Offline Capable | Yes (fully offline — all scan data stored in local SQLite) |
| Route | /session/:id/scan |
The Scanning Interface is the primary operational screen where operators perform RFID tag reads using the connected Zebra reader. It displays real-time scan progress including tag count, RSSI signal strength, section progress, and a live-updating list of detected EPCs. All scan data is written to local SQLite with 30-second auto-save checkpoints for crash recovery.
| Element | Type | Description | Business Rule |
|---|
| Start/Stop Scan Toggle | Large Button | Toggle RFID reader on/off (green = scanning, red = stopped) | Reader controlled via Zebra RFID SDK native bridge |
| Tag Counter | Large Numeric Display | “347 / 500” format showing found tags vs expected count | Expected count from session creation (SCR-R03) or total active tags at location |
| RSSI Signal Indicator | Vertical Bar / Arc | Real-time signal strength of current reads (-30 dBm = strong, -70 dBm = threshold) | Tags below min_rssi_threshold (-70 dBm default) are filtered as phantom reads |
| Section Progress Bar | Horizontal Progress | Percentage of expected tags found in operator’s assigned section | Color-coded: green (> 95%), yellow (80-95%), red (< 80%) |
| EPC List | Scrollable List | Live-updating list of scanned EPCs with SKU name, variant, and read count | Sorted by most-recent-first; matched tags show product info from rfid_tag_mappings cache |
| Unknown Tags Badge | Warning Count | Count of EPCs not found in rfid_tag_mappings (unmatched) | Displayed as “12 unknown” badge; could indicate tags from other tenants or unregistered tags |
| Battery Indicator | Icon + Percentage | Device battery level and reader battery level | Below 15%: triggers auto-save and warning “Low battery — save your progress” |
| Auto-Save Indicator | Subtle Text | “Last saved: 12s ago” timestamp | 30-second SQLite checkpoint interval (configurable via rfid_config.auto_save_interval_seconds) |
| Elapsed Time | Timer | Session duration counter (HH:MM:SS) | Auto-expires after session_timeout_minutes (default: 480 min / 8 hours) |
┌─────────────────────────────────┐
│ ◄ Session Men's Tops ■ ■ │ <- Back, Section name, Battery icons
│ 12:34:21 │ <- Elapsed time
├─────────────────────────────────┤
│ │
│ ┌───────────┐ │
│ │ │ │
│ │ 347 │ │ <- Tag count (large)
│ │ ─── ─── │ │
│ │ 500 │ │ <- Expected count
│ │ │ │
│ └───────────┘ │
│ │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░ 69% │ <- Section progress bar
│ │
│ RSSI: ████████░░ -42 dBm │ <- Signal strength
│ │
├─────────────────────────────────┤
│ Scanned Tags 12 unk │ <- Unknown tag count
├─────────────────────────────────┤
│ ▸ 3034F8A2C1E9B7D0 NXJ-1078 │
│ Blue Hoodie / M ×3 -38 │
│ ▸ 3034F8A2C1E9B7D1 NXJ-1078 │
│ Blue Hoodie / L ×2 -45 │
│ ▸ 3034F8A2C1E9B7D2 NXJ-1079 │
│ Black Tee / S ×1 -52 │
│ ▸ 3034F8A2C1E9B7D3 ??? unkn │
│ Unknown tag ×1 -61 │
│ ▸ 3034F8A2C1E9B7D4 NXJ-1080 │
│ White Polo / XL ×1 -44 │
│ │
│ (scrollable) │
├─────────────────────────────────┤
│ Auto-saved 12s ago │
│ │
│ ┌─────────────────────────────┐│
│ │ ■ STOP SCANNING ││ <- Large toggle button (red)
│ └─────────────────────────────┘│
└─────────────────────────────────┘
| Action | Navigates To | Requires Role |
|---|
| Tap “Stop Scanning” → “Complete Section” | SCR-R05 Section Assignment & Progress | ALL |
| Tap “Stop Scanning” → “End Session” (manager) | SCR-R06 Session Summary | MANAGER, OWNER |
| App backgrounded / battery critical | Stay on SCR-R04 (auto-save triggered immediately) | ALL |
| App crash / force close | SCR-R04 with recovery dialog on relaunch (“Resume session?”) | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R05 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8 |
| Database Tables | session_operators (R/W), rfid_scan_sessions (R), rfid_scan_events (R, local) |
| State Machine(s) | RFID Session (7.11): in_progress |
| Appendix F Services | rfid.scan.command.service |
| User Roles | ALL (view); MANAGER, OWNER (reassign sections) |
| Offline Capable | Partial (shows local progress; section reassignment requires connectivity) |
| Route | /session/:id/sections |
The Section Assignment & Progress screen shows the overall progress of a multi-operator counting session. Each operator’s assigned section is displayed with their individual tag count, progress percentage, and connection status. Managers can reassign sections or add/remove operators from this screen.
| Element | Type | Description | Business Rule |
|---|
| Session Header | Info Card | Session name, type, location, total tags found, elapsed time | Aggregates counts from all operators |
| Operator Section Cards | Card List | One card per operator showing: name, section, tag count, progress %, last activity timestamp | Progress % = operator’s tags / (expected / num_sections) |
| My Section Highlight | Visual Emphasis | Current user’s section card is highlighted with a colored border | Allows quick identification of own section |
| Operator Status | Badge per Card | “Scanning” (green pulse), “Paused” (yellow), “Completed” (checkmark), “Disconnected” (red) | Based on last activity timestamp; disconnected if no scan events > 5 minutes |
| Add Operator Button | Icon Button | Add a new operator to the session (manager only) | Max 10 operators per session |
| Remove Operator Button | Icon Button | Remove an operator from the session (manager only) | Already-uploaded data preserved; session_operators.left_at set |
| Reassign Section | Edit Button | Change an operator’s assigned section (manager only) | Updates session_operators.assigned_section |
| Resume Scanning Button | Primary Button | Return to scanning interface for current user’s section | Navigates to SCR-R04 |
| Action | Navigates To | Requires Role |
|---|
| Tap “Resume Scanning” | SCR-R04 Scanning Interface | ALL |
| Tap “Complete Session” | SCR-R06 Session Summary | MANAGER, OWNER |
| Tap “Add Operator” | Operator selection modal (inline) | MANAGER, OWNER |
| Back button | SCR-R02 Home Dashboard | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R06 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8 |
| Database Tables | rfid_scan_sessions (R/W), rfid_scan_events (R), session_operators (R), rfid_tags (R) |
| State Machine(s) | RFID Session (7.11): in_progress → completed or in_progress → cancelled |
| Appendix F Services | rfid.scan.command.service, rfid.inventory-reconciliation.service |
| User Roles | ALL (view); MANAGER, OWNER (approve/reject) |
| Offline Capable | Partial (shows local counts; variance calculation requires server data) |
| Route | /session/:id/summary |
The Session Summary displays the final results of an RFID counting session, including total tags scanned, expected count, variance analysis, and per-section breakdowns. Managers use this screen to review results and decide whether to approve the count, request a recount, or cancel the session. Variance is color-coded by severity threshold.
| Element | Type | Description | Business Rule |
|---|
| Session Info Header | Info Card | Session number, type, location, start/end time, duration, operator count | Read from rfid_scan_sessions |
| Total Count Summary | Large Stats | Found: 4,832 / Expected: 5,000 / Variance: -168 (-3.36%) | Variance = found - expected; negative = missing tags |
| Variance Severity | Color-Coded Banner | Green (0%), Yellow (1-2%), Orange (3-5%), Red (>5%) | Thresholds from rfid_config variance settings (see BRD Section 5.16.4) |
| Per-Section Breakdown | Table/Cards | Each section with operator name, tags found, expected, variance, duration | Grouped by session_operators.assigned_section |
| Unknown Tags List | Expandable Section | EPCs not found in rfid_tags table — potential unregistered or foreign tags | Count shown as “23 unknown tags” with expandable detail list |
| Missing Tags List | Expandable Section | Expected tags (active in rfid_tags at this location) not found during scan | Helps identify potentially lost or misplaced inventory |
| Upload Status | Badge | “Pending upload” or “Uploaded” with timestamp | Shows whether scan data has been synced to server |
| Approve Button | Primary Button | Mark session as completed and accept the count | MANAGER/OWNER only; writes rfid_scan_sessions.status = 'completed', sets completed_by and completed_at |
| Recount Button | Secondary Button | Keep session open for additional scanning passes | Returns to SCR-R05 Section Assignment |
| Cancel Button | Destructive Button | Cancel the session entirely | MANAGER/OWNER only; sets rfid_scan_sessions.status = 'cancelled'; scan data preserved for audit |
| Action | Navigates To | Requires Role |
|---|
| Tap “Approve” | SCR-R07 Chunked Upload (if not already uploaded) → SCR-R02 Home | MANAGER, OWNER |
| Tap “Recount” | SCR-R05 Section Assignment (session stays in_progress) | MANAGER, OWNER |
| Tap “Cancel Session” | SCR-R02 Home Dashboard (after confirmation dialog) | MANAGER, OWNER |
| Back button | SCR-R02 Home Dashboard | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R07 |
| Product(s) | Raptag |
| BRD Section(s) | 4.6.8 |
| Database Tables | rfid_scan_events (R, local SQLite → W, server PostgreSQL), rfid_scan_sessions (W) |
| State Machine(s) | RFID Session (7.11): in_progress → uploaded |
| Appendix F Services | rfid.scan.command.service, rfid.inventory-reconciliation.service |
| User Roles | ALL |
| Offline Capable | No (requires connectivity to upload) |
| Route | /session/:id/sync |
The Chunked Upload screen manages the transfer of locally-stored RFID scan data from the mobile device to the Central API. Scan events are uploaded in chunks of 5,000 events each, with progress tracking, retry logic for failed chunks, and idempotency guarantees (UNIQUE constraint on session_id + epc prevents duplicate processing on retries).
| Element | Type | Description | Business Rule |
|---|
| Session Upload Card | Info Card | Session name, total events to upload, chunk count | Total events / 5,000 = number of chunks (rounded up) |
| Upload Progress Bar | Determinate Progress | “Chunk 3 of 7 — 15,000 / 35,000 events” | Each chunk = POST to /api/rfid/sessions/:id/upload with 5,000 events |
| Upload Speed | Stats Text | “~2,400 events/sec” throughput indicator | Calculated from chunk upload time |
| Chunk Status List | Scrollable List | Per-chunk status: pending, uploading, completed, failed | Failed chunks show error message and retry button |
| Retry Failed Button | Warning Button | Retry all failed chunks | Idempotent: server uses UNIQUE(session_id, epc) with UPSERT logic; safe to re-send |
| Connection Status | Indicator | Current connectivity state | Upload pauses automatically if connectivity drops; resumes on reconnection |
| Server Processing | Status Text | “Server merging operator data…” shown after all chunks uploaded | Server-side dedup (keeps highest RSSI per EPC) and variance calculation |
| Upload Complete Summary | Success Card | “35,000 events uploaded. 4,832 unique tags. Server processing complete.” | Shown after server acknowledges all chunks and completes merge |
| Cancel Upload Button | Text Button | Cancel remaining upload (already-uploaded chunks are preserved) | Partial uploads are safe; session stays in_progress for retry later |
| Action | Navigates To | Requires Role |
|---|
| Upload complete | SCR-R06 Session Summary (with server-calculated variance) | ALL |
| Cancel upload | SCR-R02 Home Dashboard (session marked as “pending upload”) | ALL |
| All sessions synced (from pending uploads) | SCR-R02 Home Dashboard with cleared “Pending Uploads” badge | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-R08 |
| Product(s) | Raptag |
| BRD Section(s) | 5.16 |
| Database Tables | devices (R/W), rfid_config (R) |
| State Machine(s) | – |
| Appendix F Services | rfid.config.crud.service |
| User Roles | ALL (view); MANAGER, ADMIN, OWNER (pair/unpair) |
| Offline Capable | Partial (shows previously paired devices; new pairing requires connectivity) |
| Route | /devices |
The Device Pairing screen manages the connection between the Raptag mobile app and Zebra RFID readers. Operators pair their phone with a reader using Bluetooth discovery or a 6-character claim code generated in Nexus POS (Settings > RFID > Devices). Once paired, the reader appears on the Home Dashboard status indicator and is available for scanning sessions.
| Element | Type | Description | Business Rule |
|---|
| Paired Device Card | Info Card | Currently paired reader: model (MC3390R / RFD40), serial number, connection type, battery level, firmware version | One reader per device at a time |
| Connection Status | Status Badge | “Connected” (green), “Disconnected” (red), “Searching…” (yellow pulse) | Based on Bluetooth/WiFi connection state to the reader |
| Claim Code Entry | Text Input | 6-character alphanumeric code for initial reader registration | Code generated in Nexus POS > Settings > RFID > Devices (OWNER); valid for 24 hours; one-time use |
| Bluetooth Discovery | Button + List | Scan for nearby Bluetooth RFID readers | Shows discoverable Zebra devices with model and signal strength |
| Reader Details | Expandable Section | Serial number, firmware version, last seen, assigned location, read range | From devices table joined with reader registration data |
| Unpair Button | Destructive Text Button | Disconnect and unpair the current reader | Requires MANAGER role; clears device association |
| Test Read Button | Secondary Button | Fire a single RFID read to verify reader is working | Reads one tag and displays EPC + RSSI; confirms hardware connection |
| Supported Models Info | Collapsible Section | List of supported reader models with specs (MC3390R, RFD40, FX9600) | Reference information; not interactive |
| Action | Navigates To | Requires Role |
|---|
| Successful pairing | SCR-R02 Home Dashboard (reader status updated) | MANAGER, ADMIN, OWNER |
| Tap “Test Read” | Stay on SCR-R08 (inline result display) | ALL |
| Unpair device | Stay on SCR-R08 (device card cleared) | MANAGER, ADMIN, OWNER |
| Back button | SCR-R02 Home Dashboard | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-X03 |
| Product(s) | All Roles |
| BRD Section(s) | 1.16 |
| Database Tables | – (connection state is client-side only) |
| State Machine(s) | Offline Mode (7.12): ONLINE / DEGRADED / OFFLINE |
| Appendix F Services | system.connection-state.service |
| User Roles | ALL |
| Offline Capable | N/A (this component IS the offline indicator) |
The Offline Mode Indicator is a persistent banner component displayed at the top of all Nexus POS screens (all roles). It communicates the current connectivity state to the user using the 3-state model from ADR-048 (ONLINE / DEGRADED / OFFLINE). The banner is minimal when online, becomes more prominent during degraded connectivity, and displays critical information (queue count, staleness warning) when fully offline.
ONLINE (green — minimal, auto-hides after 3 seconds):
┌──────────────────────────────────────────────┐
│ ● Connected │
└──────────────────────────────────────────────┘
DEGRADED (yellow — persistent, subtle):
┌──────────────────────────────────────────────┐
│ ● Limited connectivity — some features │
│ unavailable │
└──────────────────────────────────────────────┘
OFFLINE (red — persistent, prominent):
┌──────────────────────────────────────────────┐
│ ● Offline mode — sales will sync when │
│ connected. 3 sales queued. │
│ Prices may be outdated (last sync: 47m) │
└──────────────────────────────────────────────┘
SYNCING (yellow — persistent, with progress):
┌──────────────────────────────────────────────┐
│ ● Syncing... 2/3 sales uploaded │
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░ 67% │
└──────────────────────────────────────────────┘
| Element | Type | Description | Business Rule |
|---|
| Status Dot | Colored Circle | Green (ONLINE), Yellow (DEGRADED/SYNCING), Red (OFFLINE) | Driven by ConnectionMonitor 3-state model |
| Status Text | Label | State-specific message (see wireframe above) | ONLINE message auto-hides after 3 seconds; DEGRADED and OFFLINE persist |
| Queue Count | Dynamic Text | “N sales queued” — count of pending entries in sales_queue | Only shown in OFFLINE state; updated as new offline sales are created |
| Staleness Warning | Subtle Text | “Prices may be outdated (last sync: Xm)” | Shown when product_cache.last_refreshed > 60 minutes old |
| Sync Progress | Progress Bar + Text | “Syncing… 2/3 sales uploaded” with determinate progress bar | Shown during SYNCING sub-state; transitions to ONLINE when queue is empty |
| Action | Navigates To | Requires Role |
|---|
| Tap banner (OFFLINE state) | Show detail modal: list of queued sales with timestamps | ALL |
| Tap banner (SYNCING state) | Show detail modal: per-sale sync progress with success/error status | ALL |
| Connection restores | Banner auto-transitions: OFFLINE → SYNCING → ONLINE | – |
These screens appear across all products and are not tied to a single BRD module.
| Attribute | Value |
|---|
| Screen ID | SCR-X01 |
| Product(s) | All Roles |
| BRD Section(s) | 5.5 |
| Database Tables | tenant_users (R), tenants (R), roles (R), role_permissions (R) |
| State Machine(s) | — |
| Appendix F Services | auth.login.service, auth.token.service |
| User Roles | ALL |
| Offline Capable | Yes (cached credentials for POS terminal PIN login and Raptag; standard email/password login requires online) |
| Route | /login |
The login screen is the entry point for both products. Users authenticate with email/password (standard login) or PIN (POS quick-switch for cashiers). On POS and Raptag, cached credentials allow offline login for previously authenticated users. The screen adapts its layout based on the deployment context (web browser for Nexus POS, React Native mobile for Raptag).
| Element | Type | Description | Business Rule |
|---|
| Email Field | Input | User email address | BRD 5.5 — required |
| Password Field | Input | Masked password entry | BRD 5.5 — Argon2id hashing |
| PIN Entry (POS only) | Input | 4-6 digit numeric PIN for quick-switch | BRD 5.5 — BCrypt hashing |
| Tenant Selector | Dropdown | Select tenant (multi-tenant users only) | BRD 5.5 — row-level isolation |
| Remember Me | Checkbox | Cache credentials for offline login | ADR-048 |
| Offline Indicator | Banner | Shows connection state if DEGRADED/OFFLINE | ADR-048 |
| Forgot Password | Link | Trigger password reset email | BRD 5.5 |
| Action | Navigates To | Requires Role |
|---|
| Login (POS) | SCR-M01-01 Sales Terminal | CASHIER+ |
| Login (standard) | Dashboard (role-appropriate home) | MANAGER+ |
| Login (Raptag) | SCR-R02 Home Dashboard | AUDITOR+ |
| Switch User (POS PIN) | SCR-M01-01 Sales Terminal (different user) | CASHIER+ |
| Forgot Password | Password reset email flow | ALL |
| Attribute | Value |
|---|
| Screen ID | SCR-X02 |
| Product(s) | All |
| BRD Section(s) | — |
| Database Tables | — |
| State Machine(s) | — |
| Appendix F Services | — |
| User Roles | ALL |
| Offline Capable | Yes (static pages bundled with app) |
| Route | /error/403, /error/404, /error/500 |
Standard error pages displayed when a user encounters an authorization failure (403), navigates to a non-existent route (404), or the server returns an unhandled error (500). These pages are statically bundled with each application and work offline. Each provides a clear error message, suggested actions, and a link to navigate back to a known-good state.
| Element | Type | Description | Business Rule |
|---|
| Error Code | Heading | Large display of 403, 404, or 500 | — |
| Error Message | Text | Human-readable explanation (e.g., “Page not found”) | — |
| Suggested Actions | Text | “Check the URL” / “Go back” / “Contact support” | — |
| Back to Home | Button | Navigate to dashboard | — |
| Report Issue | Link | Opens support/feedback form | — |
| Action | Navigates To | Requires Role |
|---|
| Back to Home | Dashboard (role-appropriate home) | ALL |
| Go Back | Previous page (browser history) | ALL |
| Report Issue | Support form / feedback modal | ALL |
Note: Full specification for SCR-X03 is provided in G.11 (Raptag section) as it was written by Agent A5 with the complete 3-state + SYNCING wireframe. See G.11 for the detailed specification including the ASCII wireframe showing all 4 states (ONLINE, DEGRADED, OFFLINE, SYNCING).
| Attribute | Value |
|---|
| Screen ID | SCR-X03 |
| Product(s) | All Roles |
| BRD Section(s) | 1.16, ADR-048 |
| Full Specification | See G.11 (Agent A5 output) |
These diagrams show the primary user workflows across screens. Screen IDs reference the detailed specifications in G.4-G.12.
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCR-X01 │ │ SCR-M01-01 │ │ SCR-M01-02 │ │ SCR-M01-04 │ │ SCR-M01-09 │
│ Login │───►│ Sales │───►│ Cart Panel │───►│ Payment / │───►│ Receipt │
│ │ │ Terminal │ │ & Line Items │ │ Checkout │ │ Print │
└──────────┘ └──────┬───────┘ └──────────────┘ └──────┬───────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ SCR-M02-01 │ │ SCR-M01-03 │
│ Customer │ │ Discount │
│ Lookup │ │ Modal │
└──────────────┘ └──────────────┘
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCR-M01 │ │ SCR-M01-14 │ │ Item │ │ Refund │ │ SCR-M01-09 │
│ -01 │───►│ Return │───►│ Selection │───►│ Method │───►│ Receipt │
│ Terminal │ │ Processing │ │ (within │ │ Selection │ │ Print │
│ │ │ (Receipt │ │ SCR-M01-14) │ │ (within │ │ │
│ │ │ Lookup) │ │ │ │ SCR-M01-14) │ │ │
└──────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ SCR-M01-15 │
│ Exchange │
│ (optional) │
└──────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCR-M01-10 │ │ Sales Day │ │ SCR-M01-10 │ │ SCR-M01-10 │
│ Cash Drawer │───►│ (Multiple │───►│ X-Report │───►│ Z-Report │
│ Open │ │ sales via │ │ (Mid-day │ │ (End-of-day │
│ (Starting $) │ │ SCR-M01-01) │ │ read-only) │ │ close out) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCR-M04-04 │ │ SCR-M04-05 │ │ SCR-M04-07 │ │ SCR-M04-08 │
│ PO Create / │───►│ PO Approval │───►│ Receiving & │───►│ Receiving │
│ Edit │ │ / Track │ │ Inspection │ │ Variance │
│ │ │ │ │ │ │ (if needed) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
▲
│
┌──────────────┐
│ SCR-M04-06 │
│ PO Templates │
│ (optional) │
└──────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ SCR-M04-09 │ │ SCR-M04-10 │ │ Count Entry: │ │ SCR-M04-13 │
│ Stock Count │───►│ Count Freeze │───►│ SCR-M04-11 (Scanner) │───►│ Count │
│ Session │ │ Manager │ │ SCR-M04-12 (RFID) │ │ Results │
│ (Create) │ │ │ │ SCR-R04 (Raptag) │ │ Review │
└──────────────┘ └──────────────┘ └──────────────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ SCR-M04-14 │
│ Count │
│ Approval │
└──────────────┘
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ SCR-R01 │ │ SCR-R02 │ │ SCR-R03 │ │ SCR-R04 │ │ SCR-R06 │ │ SCR-R07 │
│ Login │───►│ Home │───►│ Join / │───►│ Scanning │───►│ Session │───►│ Chunked │
│ │ │ Dashboard│ │ Start │ │ Interface│ │ Summary │ │ Upload │
│ │ │ │ │ Session │ │ │ │ │ │ / Sync │
└──────────┘ └──────────┘ └──────────┘ └────┬─────┘ └──────────┘ └──────────┘
│
▼
┌──────────┐
│ SCR-R05 │
│ Section │
│ Progress │
└──────────┘
┌──────────────────────────────────────────────────────────────────────────────────┐
│ SCR-M05-01 Onboarding Wizard │
│ │
│ Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 │
│ Company → Locations → Tax → Payment → Receipt → Users → Registers │
│ Profile Setup Config Setup Template & Roles Setup │
│ │
│ Step 8 Step 9 Step 10 Step 11 Step 12 Step 13 │
│ Product → Inventory → Category → Integration → Printer → Go-Live │
│ Import Sync Setup Setup Setup Checklist │
└──────────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ SCR-M06-01 │ │ Provider │ │ SCR-M06-03 │ │ SCR-M06-10 │
│ Integration │───►│ Setup: │───►│ Sync Config │───►│ Inventory │
│ Hub │ │ SCR-M06-02 │ │ (rules, │ │ Sync │
│ Dashboard │ │ SCR-M06-05 │ │ buffers) │ │ Dashboard │
│ │ │ SCR-M06-07 │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ SCR-M06-11 │
│ Health │
│ Monitor │
└──────────────┘
| Category | Count |
|---|
| Module 1: Sales | 22 |
| Module 2: Customers | 10 |
| Module 3: Catalog | 18 |
| Module 4: Inventory | 23 |
| Module 5: Setup & Config | 22 |
| Module 6: Integrations | 12 |
| Raptag Mobile | 8 |
| Cross-Cutting | 3 |
| Total | 118 |
| Product | Screens | Notes |
|---|
| Nexus POS (Web App) | 107 | All roles access the same web app; visibility controlled by role-based routing |
| Nexus Raptag (Mobile) | 8 | Separate React Native app (ADR-047) |
| Cross-Cutting (All Products) | 3 | Login, Error Pages, Offline Indicator |
| Total | 118 | |
| Minimum Role | Screen Count | Notes |
|---|
| All Roles | 16 | Customer list/profile, product search, inventory list, receiving, stock count, login, etc. |
| CASHIER+ | 21 | Sales terminal, cart, payment, receipts, drawer, clock-in, scanner count |
| MANAGER+ | 35 | Reports, catalog management, inventory management, user management |
| OWNER | 32 | Setup, integrations, configuration, onboarding, RFID config |
| BUYER+ | 6 | Seasons, media manager, PO create, PO templates |
| Offline Status | Screen Count | Notes |
|---|
| Yes (full offline) | 14 | Includes Sales Terminal, Product Search, Receipt, Login, Raptag Scanning |
| Degraded | 3 | Payment (cash only), Raptag Upload (queued), SCR-X03 indicator |
| No (online required) | 101 | All management/config screens, most features beyond basic sales |
| Role | Screens Accessible | Primary Modules |
|---|
| OWNER | 118 (all) | Setup (sole access to 8 screens), all others |
| MANAGER | ~95 | Sales, Inventory, Customers, Setup (partial), Integrations |
| CASHIER | ~25 | Sales (primary), basic Customer, basic Inventory |
| BUYER | ~20 | Catalog (primary), Inventory (POs, vendors, reorder) |
| AUDITOR | ~15 | Inventory (counts), Raptag (all), Audit Log |
| BRD Module | Total BRD Sections | Screens Mapped | Coverage |
|---|
| Module 1: Sales (1.1-1.20) | 20 | 22 | 100% |
| Module 2: Customers (2.1-2.8) | 8 | 10 | 100% |
| Module 3: Catalog (3.1-3.15) | 15 | 18 | 100% |
| Module 4: Inventory (4.1-4.19) | 19 | 23 | 100% |
| Module 5: Setup (5.1-5.21) | 21 | 22 | 100% |
| Module 6: Integrations (6.1-6.13) | 13 | 12 | 100% |
| Module 7: State Machines (7.1-7.16) | 16 | Referenced in screens | 100% |
| State Machine | BRD Section | Referenced By Screens |
|---|
| 7.1 Order States | 7.1 | SCR-M01-01, SCR-M01-02, SCR-M01-04, SCR-M01-07 |
| 7.2 Payment States | 7.2 | SCR-M01-04, SCR-M01-05, SCR-M01-06 |
| 7.3 Layaway States | 7.3 | SCR-M01-05 |
| 7.4 Return States | 7.4 | SCR-M01-14, SCR-M01-15 |
| 7.5 PO States | 7.5 | SCR-M04-04, SCR-M04-05, SCR-M04-07 |
| 7.6 Transfer States | 7.6 | SCR-M04-17 |
| 7.7 Count Session States | 7.7 | SCR-M04-09, SCR-M04-10, SCR-M04-13, SCR-M04-14 |
| 7.8 Adjustment States | 7.8 | SCR-M04-15, SCR-M04-16 |
| 7.9 RMA States | 7.9 | SCR-M04-21 |
| 7.10 Reservation States | 7.10 | SCR-M04-23 |
| 7.11 Gift Card States | 7.11 | SCR-M01-08 |
| 7.12 Connectivity States | 7.12 | SCR-X03 |
| 7.13 Integration Sync States | 7.13 | SCR-M06-10, SCR-M06-11 |
| 7.14 Integration Connection States | 7.14 | SCR-M06-01, SCR-M06-02, SCR-M06-05, SCR-M06-07 |
| 7.15 Special Order States | 7.15 | SCR-M01-16 |
| 7.16 Onboarding States | 7.16 | SCR-M05-01 |
| # | Screen ID | Screen Name | Section |
|---|
| 1 | SCR-M01-01 | Sales Terminal / Item Entry | G.4.1 |
| 2 | SCR-M01-04 | Payment / Checkout | G.4.4 |
| 3 | SCR-M01-10 | Cash Drawer Z-Report | G.4.10 |
| 4 | SCR-M01-14 | Return Processing | G.4.14 |
| 5 | SCR-M02-02 | Customer Profile / Detail | G.5.2 |
| 6 | SCR-M03-02 | Product Detail / Edit | G.6.2 |
| 7 | SCR-M04-01 | Inventory Dashboard | G.7.1 |
| 8 | SCR-M04-04 | PO Create / Edit | G.7.4 |
| 9 | SCR-M04-09 | Stock Count Session | G.7.9 |
| 10 | SCR-M05-01 | Onboarding Wizard (13 Steps) | G.8.1 |
| 11 | SCR-M06-01 | Integration Hub Dashboard | G.9.1 |
| 12 | SCR-R04 | Scanning Interface | G.11.4 |
| 13 | SCR-X03 | Offline Mode Indicator | G.11.9 |
| Attribute | Value |
|---|
| Version | 7.0.0 |
| Created | March 1, 2026 |
| Updated | March 2, 2026 |
| Author | Claude Code UI/UX Team |
| Status | Active |
| Appendix | G |
| Total Screens | 118 |
| ASCII Wireframes | 13 |
| BRD Version | 20.0 |
| Version | Date | Changes |
|---|
| 7.0.0 | 2026-03-02 | Unified web app pivot: removed Tauri/desktop references, “Nexus Admin” product eliminated. Nexus POS is now a single React web app (ADR-052). Product(s) field changed from POS/Admin/Both to role-based values (All Roles, CASHIER+, MANAGER+, OWNER, BUYER+, Raptag). G.2 rewritten for 2 products. G.10 POS vs Admin navigation comparison replaced with role-based navigation visibility table. G.10.2 hardware integration updated: Tauri Rust commands replaced with Star WebPRNT, WebUSB, Stripe Terminal JS SDK. G.10.3 SQLite fallback updated to SQLite WASM (sql.js/wa-sqlite + OPFS). G.14 statistics rewritten with role-based screen distribution. All 118 screen entries updated. |
| 6.4.0 | 2026-03-01 | Initial release: 118 screens cataloged (7 modules + Raptag + cross-cutting). 13 ASCII wireframes. Full BRD traceability. |
This appendix is part of the POS Blueprint Book. All content is self-contained.