The POS Platform Blueprint

A Complete Guide to Building an Enterprise Multi-Tenant Point of Sale System

Version: 5.0.0 Created: December 29, 2025 Updated: February 25, 2026 Target Platform: /volume1/docker/pos-platform/

╔═══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║                    ████████╗██╗  ██╗███████╗                                  ║
║                    ╚══██╔══╝██║  ██║██╔════╝                                  ║
║                       ██║   ███████║█████╗                                    ║
║                       ██║   ██╔══██║██╔══╝                                    ║
║                       ██║   ██║  ██║███████╗                                  ║
║                       ╚═╝   ╚═╝  ╚═╝╚══════╝                                  ║
║                                                                               ║
║           ██████╗  ██████╗ ███████╗    ██████╗ ██╗     ██╗   ██╗███████╗     ║
║           ██╔══██╗██╔═══██╗██╔════╝    ██╔══██╗██║     ██║   ██║██╔════╝     ║
║           ██████╔╝██║   ██║███████╗    ██████╔╝██║     ██║   ██║█████╗       ║
║           ██╔═══╝ ██║   ██║╚════██║    ██╔══██╗██║     ██║   ██║██╔══╝       ║
║           ██║     ╚██████╔╝███████║    ██████╔╝███████╗╚██████╔╝███████╗     ║
║           ╚═╝      ╚═════╝ ╚══════╝    ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝     ║
║                                                                               ║
║                        ██████╗ ██████╗ ██╗███╗   ██╗████████╗                ║
║                        ██╔══██╗██╔══██╗██║████╗  ██║╚══██╔══╝                ║
║                        ██████╔╝██████╔╝██║██╔██╗ ██║   ██║                   ║
║                        ██╔═══╝ ██╔══██╗██║██║╚██╗██║   ██║                   ║
║                        ██║     ██║  ██║██║██║ ╚████║   ██║                   ║
║                        ╚═╝     ╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝   ╚═╝                   ║
║                                                                               ║
║                    Enterprise Multi-Tenant Point of Sale                      ║
║                          Architecture & Implementation                        ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

How to Use This Book

This Blueprint is a self-contained guide for building a production-grade, multi-tenant POS system using Claude Code’s multi-agent orchestration. Every diagram, code sample, database schema, and implementation detail is included directly in these pages.

Reading Order

Claude Code Commands

Throughout this book, you’ll see commands like:

/dev-team implement tenant middleware

These are Claude Code multi-agent commands. See Chapter 29: Claude Code Reference for the complete command guide.

Table of Contents

Front Matter

• 00-BOOK-INDEX.md – You are here
• 01-PREFACE.md - Why this book exists
• BLUEPRINT-INSTRUCTIONS.md - How to maintain this blueprint

Part I: Foundation (Chapter 01)

What this book is and how to use it

• Chapter 01: Blueprint Purpose

Part II: Architecture (Chapters 02-05)

System design, quality attributes, and key decisions

• Chapter 02: Architecture Decision Records
• Chapter 03: Architecture Characteristics
• Chapter 04: Architecture Styles Analysis
• Chapter 05: Architecture Components (BRD v20.0)

Note: In v3.0.0, standalone architecture chapters were consolidated into enriched Characteristics and Styles chapters. In v4.0.0, the full BRD v20.0 was integrated. In v5.0.0, Foundation chapters 02-04 were removed and all chapters renumbered.

Part III: Database (Chapters 06-09)

Complete data layer specification

• Chapter 06: Database Strategy
• Chapter 07: Schema Design
• Chapter 08: Entity Specifications
• Chapter 09: Indexes & Performance

Part IV: Backend (Chapters 10-13)

API and service layer implementation

• Chapter 10: API Design
• Chapter 11: Service Layer
• Chapter 12: Security & Authentication
• Chapter 13: Integration Patterns

Part V: Frontend (Chapters 14-17)

User interface specifications

• Chapter 14: POS Client Application
• Chapter 15: Admin Portal
• Chapter 16: Mobile (Raptag)
• Chapter 17: UI Component Library

Part VI: Implementation Guide (Chapters 18-23)

Step-by-step building instructions

• Chapter 18: Development Environment
• Chapter 19: Implementation Roadmap
• Chapter 20: Phase 1 - Foundation
• Chapter 21: Phase 2 - Core Operations
• Chapter 22: Phase 3 - Supporting Systems
• Chapter 23: Phase 4 - Production Ready

Part VII: Operations (Chapters 24-28)

Deployment and ongoing maintenance

• Chapter 24: Deployment Guide
• Chapter 25: Monitoring & Alerting
• Chapter 26: Security Compliance
• Chapter 27: Disaster Recovery
• Chapter 28: Tenant Lifecycle

Part VIII: Reference (Chapters 29-32)

Quick lookup resources

• Chapter 29: Claude Code Command Reference
• Chapter 30: Glossary
• Chapter 31: Checklists
• Chapter 32: Troubleshooting

Appendices

• Appendix A: Complete API Reference
• Appendix B: Database ERD
• Appendix C: Domain Events Catalog
• Appendix D: UI Mockups
• Appendix E: Code Templates
• Appendix F: BRD-to-Code Module Mapping

Book Statistics

How to Print This Book

Option 1: Markdown to PDF (Recommended)

Use Pandoc to compile all chapters into a single PDF:

# Install Pandoc (if not installed)
# macOS: brew install pandoc
# Ubuntu: apt install pandoc texlive-xetex

# Navigate to Blueprint folder
cd /volume1/docker/planning/000-POS-Learning/00-Blue-Print

# Compile to PDF
pandoc \
  00-BOOK-INDEX.md \
  01-PREFACE.md \
  Part-I-Foundation/*.md \
  Part-II-Architecture/*.md \
  Part-III-Database/*.md \
  Part-IV-Backend/*.md \
  Part-V-Frontend/*.md \
  Part-VI-Implementation/*.md \
  Part-VII-Operations/*.md \
  Part-VIII-Reference/*.md \
  Appendices/*.md \
  -o POS-Blueprint-Book.pdf \
  --toc \
  --toc-depth=3 \
  --pdf-engine=xelatex \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V monofont="DejaVu Sans Mono"

Option 2: VS Code Extension

1. Install “Markdown PDF” extension in VS Code
2. Open each chapter
3. Right-click > “Markdown PDF: Export (pdf)”
4. Combine PDFs using any PDF merger

Option 3: Web-Based

Use online tools like:

• Dillinger.io - Paste markdown, export as PDF
• GitHub - Each .md file renders nicely for printing
• Grip - Local GitHub-style markdown preview

Option 4: Build Script (Automated)

#!/bin/bash
# save as: build-book.sh

BOOK_DIR="/volume1/docker/planning/000-POS-Learning/00-Blue-Print"
OUTPUT="$BOOK_DIR/POS-Blueprint-Book.pdf"

# Collect all markdown files in order
FILES=(
  "$BOOK_DIR/00-BOOK-INDEX.md"
  "$BOOK_DIR/01-PREFACE.md"
)

# Add Part I-VIII
for part in Part-I-Foundation Part-II-Architecture Part-III-Database \
            Part-IV-Backend Part-V-Frontend Part-VI-Implementation \
            Part-VII-Operations Part-VIII-Reference Appendices; do
  for file in "$BOOK_DIR/$part"/*.md; do
    [ -f "$file" ] && FILES+=("$file")
  done
done

# Build PDF
pandoc "${FILES[@]}" -o "$OUTPUT" --toc --toc-depth=3

echo "Book compiled: $OUTPUT"

Estimated Print Size

Version History

Contributors

Blueprint Maintenance

How to Update This Blueprint

See BLUEPRINT-INSTRUCTIONS.md for complete maintenance procedures.

Quick Reference:

CRITICAL: When adding or removing chapters/appendices, you MUST update:

1. This file (00-BOOK-INDEX.md)
2. mdbook-src/src/SUMMARY.md
3. Copy updated index to mdbook-src/src/00-BOOK-INDEX.md

Live Site

URL: https://pos-blueprint.pages.dev/

Thoughts & Recommendations

Current Status (as of 2026-02-22)

The blueprint is comprehensive and production-ready for Phase 3 implementation. Key observations:

Strengths

• Complete database schema (51 tables across 13 domains)
• Full API specification (75+ endpoints with request/response examples)
• Multi-tenant architecture designed from day one
• Offline-first design with conflict resolution strategies
• 4-phase implementation roadmap with Claude Code commands
• Consolidated architecture chapters with expert panel review and full implementation details

Areas for Future Enhancement

Implementation Notes

1. Start with Phase 1 - Foundation is critical; don’t skip tenant isolation
2. Use the code templates - Appendix E has copy-paste ready patterns
3. Follow the ADRs - Chapter 05 documents why decisions were made
4. Test offline early - Don’t leave offline mode for the end
5. Schema provisioning - Use the SQL functions in Chapter 10

Open Questions

• Payment processor final selection (Stripe vs Square vs both?)
• RFID hardware vendor confirmation (Zebra confirmed?)
• First pilot store selection for Phase 3 testing
• Data retention policy for audit compliance

Change Log

“Build it right the first time. This Blueprint is your guide.”

Preface

Why This Book Exists

In late 2025, we embarked on a journey to replace an aging QuickBooks Point of Sale system with a modern, multi-tenant platform. What started as a simple migration project evolved into something much more ambitious: a comprehensive Blueprint for building enterprise-grade retail software.

This book captures everything we learned—the architecture decisions, the database designs, the implementation patterns, and the operational procedures. It’s not a theoretical exercise; it’s a practical guide born from real retail operations across five store locations.

The Three-Phase Philosophy

We adopted a deliberate three-phase approach:

╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║   PHASE 1: LEARN                    PHASE 2: DESIGN                      ║
║   ─────────────                     ──────────────                       ║
║   Build Stanly (bridge to QB)       Clean room architecture              ║
║   Build Raptag (RFID system)        Domain models without legacy         ║
║   Test with real stores             Database schema for scale            ║
║   Document every discovery          API specifications                   ║
║                                                                           ║
║                          ↓                                               ║
║                                                                           ║
║                    PHASE 3: BUILD                                        ║
║                    ──────────────                                        ║
║                    Fresh POS system from scratch                         ║
║                    Using learnings, not legacy code                      ║
║                    Multi-tenant from day one                             ║
║                    Production-grade quality                              ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

The critical insight: We don’t evolve legacy systems into production. We learn from them, then build fresh. This book is the culmination of Phase 2—the complete design that enables Phase 3.

What Makes This Blueprint Different

1. Self-Contained

Every diagram, code sample, and SQL statement is included directly in these pages. You won’t find “see external documentation” or “refer to file X.” Everything you need is here.

2. Production-Grade

This isn’t a prototype specification. The database schema has 51 tables. The API has 75+ endpoints. The architecture handles offline operations, multi-tenancy, and PCI-DSS compliance. We designed for the edge cases.

3. Claude Code Native

This Blueprint is designed to be built using Claude Code’s multi-agent orchestration. Every chapter includes the exact commands to implement each section. The book and the tool work together.

4. Battle-Tested Patterns

The patterns in this book come from real retail operations—from handling offline sales during network outages to reconciling inventory across multiple locations. These aren’t theoretical; they’re proven.

Who Should Read This Book

How to Use This Book

If Starting Fresh

Read sequentially from Part I through Part VI. This gives you the full context before implementation.

If Joining Mid-Project

1. Read Part I (Foundation) for context
2. Read the relevant Part for your work area
3. Use Part VIII (Reference) for quick lookups

If Looking Up Specific Information

Jump directly to:

• Glossary (Chapter 30) for term definitions
• API Reference (Appendix A) for endpoint details
• Checklists (Chapter 31) for procedures
• Troubleshooting (Chapter 32) for problem-solving

The Technology Stack

This Blueprint specifies a complete technology stack:

┌─────────────────────────────────────────────────────────────────────────┐
│                         TECHNOLOGY STACK                                │
│                                                                         │
│   BACKEND                          FRONTEND                             │
│   ───────                          ────────                             │
│   ASP.NET Core 8                   Blazor Server (Admin Portal)        │
│   Entity Framework Core 8          .NET MAUI (POS Client)              │
│   PostgreSQL 16                    .NET MAUI (Raptag Mobile)           │
│   SignalR (Real-time)              SQLite (Offline Storage)            │
│                                                                         │
│   INFRASTRUCTURE                   INTEGRATIONS                         │
│   ──────────────                   ────────────                         │
│   Docker + Docker Compose          Shopify (E-commerce)                │
│   Prometheus + Grafana             Stripe/Square (Payments)            │
│   Redis (Caching - optional)       Zebra (RFID Printers)               │
│   Tailscale (VPN Mesh)                                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Conventions Used

Code Samples

// C# code appears in blocks like this
public class OrderService : IOrderService
{
    // Implementation
}

SQL Statements

-- SQL code appears in blocks like this
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid()
);

Claude Commands

# Claude Code commands appear like this
/dev-team implement OrderService with event sourcing

Important Notes

Note: Important information appears in blockquotes like this.

Warning: Critical warnings that could cause issues.

Diagrams

ASCII diagrams are used throughout for portability:

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Client  │────►│   API   │────►│Database │
└─────────┘     └─────────┘     └─────────┘

Acknowledgments

This Blueprint was created through collaboration between:

• Business stakeholders who defined the requirements
• Store employees who provided real-world feedback
• The Stanly project which taught us what works (and what doesn’t)
• The Raptag project which proved mobile RFID feasibility
• Claude Code agents who helped design, implement, and review

A Note on Quality

We set a goal: this system should be Grade A production quality. That means:

• Availability: 99.9% uptime (less than 9 hours downtime per year)
• Performance: Sub-2-second transaction completion
• Security: PCI-DSS compliant, zero card data storage
• Reliability: Works offline, syncs when connected
• Scalability: Multi-tenant from day one

Every design decision in this book was made with these targets in mind.

Let’s Build

You’re holding the complete Blueprint. The architecture is designed. The database is specified. The APIs are defined. The UI is wireframed. The operations procedures are documented.

All that’s left is to build it.

Turn the page and let’s begin.

December 2025

Document Information

Chapter 01: Blueprint Purpose

1.1 What This Book Is

The POS Platform Blueprint is the complete architecture and implementation guide for building an enterprise multi-tenant retail Point of Sale system. It is the single source of truth for every design decision, database schema, API contract, deployment procedure, and implementation pattern needed to build the platform from scratch.

This book is self-contained. Every diagram, code sample, and specification lives within these chapters. There are no external dependencies or unresolved references. A development team should be able to build the entire system using only this document.

1.2 Who Uses This Book

This Blueprint is designed for Claude Code teams and agents during the coding and development phase. It serves as the foundation plan that AI-assisted development teams follow when implementing the POS platform.

1.3 What the POS Platform Does

The POS Platform is a unified commerce solution for small-to-mid-size retailers operating both online and brick-and-mortar stores. It replaces legacy point-of-sale systems with a modern, multi-tenant SaaS platform.

Core Capabilities

Key Architecture Decisions

• Event-Driven Modular Monolith (Central API) + Microkernel (POS Client)
• PostgreSQL with Row-Level Security for tenant isolation
• Offline-first with SQLite local DB, sync queue, and CRDTs for conflict resolution
• ASP.NET Core 8.0 backend, Blazor web frontend, .NET MAUI mobile
• PostgreSQL LISTEN/NOTIFY for v1.0 events (Kafka deferred to v2.0)

1.4 How to Use This Book

Structure: 32 Chapters, 8 Parts, 6 Appendices

Appendices A-F provide supplementary reference: API specs, ERD, domain events, UI mockups, code templates, and BRD-to-code module mapping.

Reading Guide

Starting a new implementation? Read Parts I-II first for context, then jump to the relevant Part for your work area.

Implementing a specific module? Start with Ch 05 (Architecture Components / BRD) to find your module’s requirements, then check the corresponding backend (Part IV) and frontend (Part V) chapters.

Setting up infrastructure? Go directly to Part VI (Implementation) for dev environment and phased rollout, then Part VII (Operations) for deployment and monitoring.

Looking up a specific pattern? Use Ch 30 (Glossary) for terminology, Ch 31 (Checklists) for process guides, or Ch 32 (Troubleshooting) for common issues.

1.5 Key Mega-References

Two chapters serve as the primary implementation references and contain the bulk of the technical detail:

Chapter 04: Architecture Styles Analysis (~5,000 lines)

The architectural backbone of the system. Key sections include:

Chapter 05: Architecture Components / BRD v20.0 (~19,900 lines)

The complete Business Requirements Document with 7 modules and 113 decisions:

Authority rule: When the BRD (Ch 05) conflicts with any other chapter, the BRD wins.

1.6 Conventions Used in This Book

• Section numbering: All chapters use ## X.Y Title format (e.g., ## 1.1 What This Book Is)
• Cross-references: Point to chapter numbers and filenames (e.g., “See Chapter 04”)
• Code samples: Complete, copy-paste ready; file paths included as comments
• Document footer: Every chapter ends with a standardized Document Information table
• Dual-file sync: Every chapter exists in both the master directory and mdbook-src/src/ for web publishing

1.7 Summary

This Blueprint Book is the complete specification for the POS Platform. It is designed to be consumed by Claude Code agents and development teams who will implement the system. Start with the architecture chapters (Part II) for the big picture, then drill into the specific Part relevant to your current task.

Next Chapter: Chapter 02: Architecture Decision Records

Document Information

This chapter is part of the POS Blueprint Book. All content is self-contained.

Chapter 02: Architecture Decision Records

Documenting Key Technical Decisions

This chapter documents the major architectural decisions for the POS Platform using Architecture Decision Records (ADRs). Each ADR captures the context, decision, and consequences of a significant technical choice.

What is an ADR?

Architecture Decision Records provide a structured way to document important technical decisions:

ADR Structure
=============

+------------------------------------------------------------------+
|  ADR-XXX: [Title]                                                 |
+------------------------------------------------------------------+
|  Status: [proposed | accepted | deprecated | superseded]         |
|  Date: YYYY-MM-DD                                                 |
|  Deciders: [who made the decision]                               |
+------------------------------------------------------------------+
|                                                                   |
|  CONTEXT                                                          |
|  - What is the issue?                                            |
|  - What forces are at play?                                      |
|  - What constraints exist?                                       |
|                                                                   |
|  DECISION                                                         |
|  - What is the change?                                           |
|  - What did we choose?                                           |
|                                                                   |
|  CONSEQUENCES                                                     |
|  - What are the positive outcomes?                               |
|  - What are the negative outcomes?                               |
|  - What risks are introduced?                                    |
|                                                                   |
+------------------------------------------------------------------+

ADR-001: Schema-Per-Tenant Multi-Tenancy

Note: This ADR was superseded by the Row-Level Isolation with PostgreSQL RLS decision documented in Chapter 04, Section L.10A.4. The original decision is preserved here for historical context.

+==================================================================+
|  ADR-001: Schema-Per-Tenant Multi-Tenancy                        |
+==================================================================+
|  Status: SUPERSEDED (by Row-Level Isolation with RLS, Ch 04      |
|          Section L.10A.4)                                         |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
We are building a multi-tenant POS platform that will serve multiple
independent retail businesses. Each tenant needs:

1. Strong data isolation for security and compliance
2. Easy backup and restore of individual tenant data
3. Ability to scale individual tenants independently
4. Simple data model without tenant_id on every table
5. Compliance with SOC 2 and potential HIPAA requirements

We evaluated three multi-tenancy strategies:

  Strategy A: Shared Tables (Row-Level)
  - All tenants share tables
  - tenant_id column on every table
  - WHERE tenant_id = ? on every query

  Strategy B: Separate Databases
  - Each tenant gets own database
  - Complete isolation
  - High connection overhead

  Strategy C: Schema-Per-Tenant
  - Single database, separate schemas
  - SET search_path per request
  - Logical isolation, shared infrastructure

DECISION
--------
We will use SCHEMA-PER-TENANT multi-tenancy (Strategy C).

Each tenant gets a dedicated PostgreSQL schema:
  - shared schema: Platform-wide data (tenants, plans, features)
  - tenant_xxx schema: All tenant-specific tables

The tenant is resolved from the subdomain (e.g., nexus.pos-platform.com)
and the database search_path is set accordingly.

CONSEQUENCES
------------
Positive:
  + Strong logical isolation between tenants
  + No tenant_id needed on every table (cleaner data model)
  + Easy per-tenant backup: pg_dump -n tenant_xxx
  + Easy per-tenant restore without affecting other tenants
  + Single connection pool serves all tenants
  + Simpler queries (no WHERE tenant_id = ?)
  + Compliance-friendly for audits and data requests

Negative:
  - Migrations must be applied to all tenant schemas
  - Cross-tenant queries require explicit schema references
  - PostgreSQL has soft limit (~10,000 schemas per database)
  - Slight complexity in tenant provisioning

Risks:
  - Must ensure search_path is ALWAYS set correctly
  - Schema migration failures could leave tenants inconsistent
  - Need robust tenant provisioning automation

Mitigations:
  - Middleware validates and sets search_path on every request
  - Migration runner applies changes atomically per tenant
  - Tenant provisioning is scripted and tested

ADR-002: Offline-First POS Architecture

+==================================================================+
|  ADR-002: Offline-First POS Architecture                         |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
POS terminals operate in retail environments where network
connectivity is unreliable:

1. Internet outages occur (ISP issues, weather, accidents)
2. WiFi can be congested during peak shopping hours
3. Store networks may have maintenance windows
4. Rural locations may have poor connectivity

A traditional online-required POS would:
- Block sales during outages (lost revenue)
- Show errors during slow connections (poor UX)
- Require manual workarounds (paper receipts)

Business requirements:
- Sales must NEVER be blocked by network issues
- Receipts must print immediately
- Data must eventually sync to central system
- Inventory should be reasonably accurate

DECISION
--------
We will implement OFFLINE-FIRST architecture for POS clients.

Key design elements:
1. Local SQLite database on each POS terminal
2. All operations work against local database first
3. Event queue for pending changes
4. Background sync when connectivity available
5. Conflict resolution for concurrent changes

Data flow:
  User Action -> Local DB -> Event Queue -> [Background] -> Central API

CONSEQUENCES
------------
Positive:
  + Sales never blocked by network issues
  + Instant response time (local operations)
  + Resilient to any connectivity problem
  + Business continues regardless of server status
  + Better user experience for cashiers

Negative:
  - Data is eventually consistent (not immediate)
  - Inventory counts may drift until sync
  - More complex architecture
  - Conflict resolution logic required
  - Local storage management needed

Risks:
  - Data loss if local device fails before sync
  - Inventory overselling possible during outages
  - Conflict resolution edge cases

Mitigations:
  - Aggressive sync when online (every 30 seconds)
  - Local database backup to secondary storage
  - Conservative inventory thresholds
  - Clear offline indicator in UI
  - Deterministic conflict resolution rules

ADR-003: Event Sourcing for Sales Domain

+==================================================================+
|  ADR-003: Event Sourcing for Sales Domain                        |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
The Sales domain has specific requirements that traditional CRUD
does not adequately address:

1. Complete audit trail required (PCI-DSS compliance)
2. Need to answer "what happened?" not just "what is?"
3. Offline clients need conflict-free merge capability
4. Historical analysis (sales trends, patterns)
5. Debugging production issues by replaying events

Traditional CRUD limitations:
- Only stores current state
- Updates overwrite history
- Hard to reconstruct past states
- Audit logs separate from data model

DECISION
--------
We will use EVENT SOURCING for the Sales aggregate.

Implementation:
1. Append-only event store in PostgreSQL
2. Events are the source of truth
3. Read models (projections) for queries
4. Snapshots for performance on long streams

Events captured:
- SaleCreated, SaleLineItemAdded, PaymentReceived, SaleCompleted
- SaleVoided, RefundProcessed
- All inventory changes (InventorySold, InventoryAdjusted)

NOT event-sourced (traditional CRUD):
- Products (read-heavy, infrequent changes)
- Employees (HR data, simple lifecycle)
- Locations (configuration data)

CONSEQUENCES
------------
Positive:
  + Complete audit trail built into data model
  + Temporal queries ("inventory on Dec 15 at 3pm")
  + Offline sync via event merge (append-only = no conflicts)
  + Debugging by event replay
  + Analytics on event streams
  + Natural fit for CQRS pattern

Negative:
  - More complex than CRUD
  - Requires event versioning strategy
  - Projections must be rebuilt if logic changes
  - Storage grows over time (mitigated by snapshots)
  - Learning curve for developers

Risks:
  - Event schema evolution complexity
  - Projection bugs cause stale read models
  - Performance without proper snapshotting

Mitigations:
  - Event versioning from day one
  - Automated projection rebuild process
  - Snapshot every 100 events
  - Clear documentation and training

ADR-004: JWT + PIN Authentication

+==================================================================+
|  ADR-004: JWT + PIN Authentication                               |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team, Security Team                       |
+==================================================================+

CONTEXT
-------
POS systems have unique authentication requirements:

1. API access needs secure, stateless authentication
2. Cashiers need quick clock-in at physical terminals
3. Sensitive actions need additional verification
4. Multiple employees may share a terminal
5. Terminals may be offline

Requirements:
- Strong authentication for API/Admin access
- Fast authentication for cashiers (< 2 seconds)
- Manager override capability
- Works offline for cashier PIN

Industry standards:
- JWT is standard for API authentication
- PINs are standard for POS quick access
- Password + MFA for admin portal access

DECISION
--------
We will implement a HYBRID authentication system:

1. JWT for API Authentication
   - Admin portal uses email + password + optional MFA
   - Issues JWT token (15 min access, 7 day refresh)
   - Standard Bearer token in Authorization header

2. PIN for POS Terminal Access
   - 4-6 digit PIN per employee
   - Stored as bcrypt hash in database
   - Used for: clock-in, sale attribution, drawer access

3. Manager Override
   - Sensitive actions require manager PIN
   - Void, large discount, price override
   - Manager enters their PIN to authorize

4. Offline PIN Validation
   - Employee records with PIN hashes cached locally
   - Validated against local cache when offline
   - Sync employee changes when online

CONSEQUENCES
------------
Positive:
  + Secure API access with industry-standard JWT
  + Fast cashier workflow with PIN
  + Manager oversight on sensitive operations
  + Works offline for POS operations
  + Clear audit trail (who did what)

Negative:
  - Two authentication systems to maintain
  - PIN is less secure than password (brute force)
  - Local PIN cache could be extracted
  - Token refresh complexity

Risks:
  - PIN guessing attacks
  - Stolen JWT tokens
  - Stale employee cache (terminated employee)

Mitigations:
  - Rate limiting on PIN attempts (3 failures = lockout)
  - Short JWT expiry (15 minutes)
  - Aggressive employee sync (every 5 minutes)
  - PIN attempt logging and alerting
  - Secure local storage encryption

ADR-005: PostgreSQL as Primary Database

+==================================================================+
|  ADR-005: PostgreSQL as Primary Database                         |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
We need a database that supports:

1. Schema-per-tenant multi-tenancy
2. JSONB for flexible event storage
3. Strong ACID guarantees for financial data
4. Good performance at scale
5. Mature ecosystem and tooling

Options considered:
- PostgreSQL: Schema support, JSONB, mature
- MySQL: Popular, but weaker schema support
- SQL Server: Good, but licensing costs
- MongoDB: Document store, no ACID, no schemas
- CockroachDB: Distributed, but complexity

DECISION
--------
We will use POSTGRESQL 16 as the primary database.

Justifications:
1. Native Row-Level Security (RLS) for multi-tenancy isolation
   (Originally: schema support; updated per ADR-001 supersession)
2. Excellent JSONB for event storage
3. Strong ACID for financial transactions
4. Proven at scale (Instagram, Uber, etc.)
5. Rich extension ecosystem (PostGIS, etc.)
6. Open source, no licensing costs
7. Excellent tooling (pgAdmin, pg_dump)

CONSEQUENCES
------------
Positive:
  + Native RLS for multi-tenant data isolation (see ADR-001 supersession)
  + JSONB enables flexible event data
  + Strong consistency guarantees
  + Mature, well-documented
  + No licensing costs
  + Excellent community support

Negative:
  - Single point of failure without replication
  - Requires PostgreSQL expertise
  - Not as horizontally scalable as NoSQL
  - Schema migrations need coordination

Mitigations:
  - Streaming replication for HA
  - Regular backups with pg_dump
  - Team training on PostgreSQL
  - Migration automation tooling

ADR-006: ASP.NET Core for Central API

+==================================================================+
|  ADR-006: ASP.NET Core for Central API                           |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2025-12-29                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
We need a backend framework that supports:

1. High-performance API serving
2. Strong typing for complex domain
3. Entity Framework for database access
4. SignalR for real-time features
5. Docker deployment
6. Team expertise alignment

Options considered:
- ASP.NET Core (C#): Performance, typing, EF Core
- Node.js (Express): Fast dev, but weak typing
- Go (Gin): Performance, but less ecosystem
- Python (FastAPI): ML integration, but slower
- Java (Spring): Enterprise, but verbose

Team context:
- Existing .NET experience from Bridge project
- C# used for MAUI mobile app
- Entity Framework expertise available

DECISION
--------
We will use ASP.NET CORE 8.0 for the Central API.

Justifications:
1. Exceptional performance (near Go levels)
2. Strong typing catches bugs at compile time
3. Entity Framework Core for PostgreSQL
4. Built-in SignalR for real-time
5. Excellent Docker support
6. Team already proficient in C#
7. Same language as POS client and mobile app

CONSEQUENCES
------------
Positive:
  + High performance for API workloads
  + Strong typing reduces runtime errors
  + Seamless EF Core integration
  + Built-in dependency injection
  + Excellent tooling (Visual Studio, Rider)
  + C# across entire stack (API, Client, Mobile)

Negative:
  - Larger runtime than Go or Rust
  - Windows-centric tooling (though Linux deployment)
  - C# developers cost more than Node.js

Mitigations:
  - Alpine-based Docker images minimize size
  - Use VS Code or Rider on Mac/Linux
  - Leverage existing team expertise

ADR Index

Future ADRs (Planned)

ADR-013: RFID Configuration Embedded in Tenant Admin Portal

+==================================================================+
|  ADR-013: RFID Configuration Embedded in Tenant Admin Portal     |
+==================================================================+
|  Status: ACCEPTED                                                 |
|  Date: 2026-01-01                                                |
|  Deciders: Architecture Team                                      |
+==================================================================+

CONTEXT
-------
RapOS includes RFID inventory capabilities via the Raptag mobile app.
The question arose: where should RFID configuration (device management,
printer setup, tag encoding settings, templates) be managed?

We evaluated three options:

  Option A: Embed in Tenant Admin Portal (app.rapos.com)
  - RFID settings as feature-flagged section in existing portal
  - Uses existing authentication, permissions, navigation
  - Shared context with products, locations, users

  Option B: Separate RFID Portal (rfid.rapos.com)
  - Dedicated portal just for RFID configuration
  - 4th portal in the architecture
  - Independent scaling and development

  Option C: Hybrid Approach
  - Basic settings in Tenant Admin
  - Advanced configuration in separate portal
  - Users navigate between portals

Research was conducted on major RFID vendors:
- SML Clarity: Single platform, modular components
- Checkpoint HALO/ItemOptix: Unified SaaS platform
- Avery Dennison atma.io: Role-based dashboards in one platform
- Impinj ItemSense: Single Management Console

Key finding: NO major RFID vendor uses separate portals for RFID
configuration. All embed RFID features within unified platforms.

DECISION
--------
We will EMBED RFID configuration in the Tenant Admin Portal (Option A).

Implementation:
- Settings > RFID section (feature-flagged)
- Devices tab: Claim codes, device list, release
- Printers tab: IP configuration, test connectivity
- Tag Configuration tab: EPC prefix (read-only), variance thresholds
- Templates tab: Label template library

Mobile app downloads configuration from central API on startup.
No RFID configuration in the mobile app itself.

CONSEQUENCES
------------
Positive:
  + Matches industry pattern (SML, Checkpoint, Avery Dennison)
  + Single login/URL for all tenant management
  + Shared context with products, locations, users
  + Lower development cost (one portal, not two)
  + Progressive disclosure manages complexity
  + Same permissions system applies to RFID

Negative:
  - Could become bloated if RFID features grow significantly
  - Enterprise customers might want dedicated RFID admin
  - Feature flags add slight complexity

Risks:
  - Tenant Admin may feel "cluttered" with many features
  - RFID power users may want more dedicated experience

Mitigations:
  - Use progressive disclosure (collapse advanced settings)
  - Role-based visibility (hide RFID from non-RFID users)
  - Monitor feedback; re-evaluate if enterprise demand grows
  - Feature-flagged sections can be extracted later if needed

Re-evaluation Triggers:
  - Multiple enterprise customers (100+ stores) request separation
  - RFID feature count exceeds 20+ configuration screens
  - Evidence that RFID admins are different people than Tenant admins

How to Propose a New ADR

ADR Proposal Process
====================

1. Copy the ADR template
2. Fill in Context, Decision, Consequences
3. Set Status to "proposed"
4. Submit for architecture review
5. Discuss in architecture meeting
6. Update based on feedback
7. Set Status to "accepted" when approved
8. Add to ADR Index

MADR Template (Markdown Any Decision Records)

We use the MADR (Markdown Any Decision Records) format, which is more comprehensive than the basic ADR format and better suited for complex architectural decisions.

Full MADR Template

# ADR-XXX: [Short Title of Solved Problem and Solution]

## Status

[proposed | accepted | deprecated | superseded by ADR-YYY]

## Date

YYYY-MM-DD

## Decision-Makers

- [Name/Role 1]
- [Name/Role 2]

## Technical Story

[Link to ticket/issue: JIRA-123, GitHub Issue #456]

## Context and Problem Statement

[Describe the context and problem statement, e.g., in free form
using two to three sentences or in the form of an illustrative
story. You may want to articulate the problem in form of a question.]

## Decision Drivers

* [Driver 1, e.g., a force, facing concern, …]
* [Driver 2, e.g., a force, facing concern, …]
* [Driver 3, e.g., a force, facing concern, …]

## Considered Options

1. [Option 1]
2. [Option 2]
3. [Option 3]
4. [Option 4]

## Decision Outcome

**Chosen Option**: "[Option X]"

### Justification

[Justification for why this option was chosen. Reference the
decision drivers and explain how this option best addresses them.]

### Positive Consequences

* [e.g., improvement of quality attribute satisfaction, follow-up
  decisions required, …]
* …

### Negative Consequences

* [e.g., compromising quality attribute, follow-up decisions required,
  technical debt introduced, …]
* …

## Pros and Cons of the Options

### [Option 1]

[Example: Schema-per-tenant multi-tenancy]

**Pros:**
* Good, because [argument a]
* Good, because [argument b]

**Cons:**
* Bad, because [argument c]
* Bad, because [argument d]

### [Option 2]

[Example: Row-level multi-tenancy]

**Pros:**
* Good, because [argument a]
* Good, because [argument b]

**Cons:**
* Bad, because [argument c]

### [Option 3]

[Example: Database-per-tenant]

**Pros:**
* Good, because [argument a]

**Cons:**
* Bad, because [argument b]
* Bad, because [argument c]

## Links

* [Link type] [Link to ADR] <!-- example: Refined by ADR-007 -->
* [Link type] [Link to external resource]
* Supersedes ADR-XXX
* Related to ADR-YYY

## Notes

[Any additional notes, discussion points, or future considerations]

MADR Example: Kafka Selection

# ADR-014: Apache Kafka for Event Streaming

## Status

accepted

## Date

2026-01-15

## Decision-Makers

- Architecture Team
- Infrastructure Team

## Technical Story

ARCH-456: Select event streaming platform for POS event sourcing

## Context and Problem Statement

Our POS platform uses event sourcing for the Sales and Inventory
domains. We need an event streaming platform that supports:
- Event replay for new consumers
- Durable storage for audit compliance
- High throughput during peak retail periods (Black Friday)
- Multi-datacenter replication for disaster recovery

Which event streaming platform should we use?

## Decision Drivers

* Replayability - New analytics services must process historical events
* Durability - Events must survive broker failures (PCI compliance)
* Throughput - Handle 10,000+ events/second during peak
* Ecosystem - Good client libraries for .NET
* Operations - Team can manage without dedicated staff

## Considered Options

1. Apache Kafka
2. RabbitMQ with Shovel plugin
3. Amazon Kinesis
4. Redis Streams
5. PostgreSQL LISTEN/NOTIFY

## Decision Outcome

**Chosen Option**: "Apache Kafka (with KRaft mode)"

### Justification

Kafka is the only option that provides true event replayability with
configurable retention. New consumers can start from the beginning
of the log and process all historical events. This is critical for:
- Adding new analytics modules
- Rebuilding projections after bugs
- Audit investigations

KRaft mode eliminates ZooKeeper dependency, simplifying operations.

### Positive Consequences

* Complete replayability for compliance and analytics
* Proven at massive scale (LinkedIn, Uber)
* Strong .NET client (Confluent.Kafka)
* Schema Registry for event versioning

### Negative Consequences

* More complex than RabbitMQ
* Requires understanding of partitioning
* Higher resource usage than simpler queues

## Pros and Cons of the Options

### Apache Kafka

**Pros:**
* Good, because events are retained for configurable duration
* Good, because consumers can replay from any offset
* Good, because it handles 100K+ messages/second
* Good, because KRaft mode simplifies deployment

**Cons:**
* Bad, because it requires more operational knowledge
* Bad, because partition management adds complexity

### RabbitMQ with Shovel

**Pros:**
* Good, because it's simpler to operate
* Good, because team has existing experience

**Cons:**
* Bad, because messages are deleted after consumption
* Bad, because replay requires external archival

### Amazon Kinesis

**Pros:**
* Good, because it's fully managed
* Good, because it has replay capability

**Cons:**
* Bad, because of vendor lock-in
* Bad, because pricing is complex at scale

### Redis Streams

**Pros:**
* Good, because it's simple
* Good, because it's low latency

**Cons:**
* Bad, because durability is limited
* Bad, because it's not designed for long-term storage

### PostgreSQL LISTEN/NOTIFY

**Pros:**
* Good, because no additional infrastructure

**Cons:**
* Bad, because it doesn't scale
* Bad, because messages are ephemeral

## Links

* Refined by ADR-015 (Schema Registry Selection)
* Related to ADR-003 (Event Sourcing for Sales Domain)
* [Kafka Documentation](https://kafka.apache.org/documentation/)

## Notes

Evaluated during Q1 2026 architecture review. Confluent Cloud was
considered but rejected due to cost; self-hosted Kafka preferred.

**UPDATE (v3.0.0)**: Kafka is **deferred to v2.0**. Per the Architecture
Styles analysis (Chapter 04, Section L.4A.2),
v1.0 uses PostgreSQL event tables with LISTEN/NOTIFY for event notification
and Transactional Outbox for guaranteed delivery. This ADR remains valid
for v2.0 planning when scale justifies the Kafka operational overhead.

ADR Tooling & Automation

Recommended Tools

ADR Tools CLI

# Install adr-tools
brew install adr-tools  # macOS
# or
sudo apt install adr-tools  # Ubuntu

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use Kafka for Event Streaming"
# Creates: docs/adr/0014-use-kafka-for-event-streaming.md

# Supersede an ADR
adr new -s 3 "Replace Event Sourcing with Outbox Pattern"
# Creates new ADR that supersedes ADR-003

# List all ADRs
adr list

# Generate ADR index
adr generate toc > docs/adr/README.md

Log4brains Integration

Log4brains generates a searchable documentation website from ADRs:

# Install Log4brains
npm install -g log4brains

# Initialize in project
log4brains init

# Start preview server
log4brains preview

# Build static site
log4brains build

# Deploy to GitHub Pages
log4brains build --basePath /pos-platform-adr

# .github/workflows/adr-docs.yml

name: ADR Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/adr/**'

jobs:
  build-adr-site:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for dates

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Log4brains
        run: npm install -g log4brains

      - name: Build ADR site
        run: log4brains build --basePath /pos-platform-adr

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .log4brains/out

ADR Linting

# .github/workflows/adr-lint.yml

name: ADR Lint

on:
  pull_request:
    paths:
      - 'docs/adr/**'

jobs:
  lint-adr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate ADR Format
        run: |
          for file in docs/adr/*.md; do
            # Check required sections
            if ! grep -q "## Status" "$file"; then
              echo "ERROR: $file missing Status section"
              exit 1
            fi
            if ! grep -q "## Context" "$file" && ! grep -q "## Context and Problem Statement" "$file"; then
              echo "ERROR: $file missing Context section"
              exit 1
            fi
            if ! grep -q "## Decision" "$file" && ! grep -q "## Decision Outcome" "$file"; then
              echo "ERROR: $file missing Decision section"
              exit 1
            fi
          done
          echo "All ADRs pass validation"

      - name: Check ADR Numbering
        run: |
          # Ensure sequential numbering
          expected=1
          for file in docs/adr/[0-9]*.md; do
            num=$(basename "$file" | grep -o '^[0-9]*')
            if [ "$num" != "$expected" ]; then
              echo "WARNING: Expected ADR-$expected, found ADR-$num"
            fi
            expected=$((expected + 1))
          done

ADR Review Checklist

# ADR Review Checklist

Before accepting an ADR, verify:

## Structure
- [ ] Uses MADR template
- [ ] Has clear title
- [ ] Status is set correctly
- [ ] Date is current
- [ ] Decision-makers are listed

## Content Quality
- [ ] Context clearly explains the problem
- [ ] Decision drivers are explicit
- [ ] At least 3 options were considered
- [ ] Pros/cons are documented for each option
- [ ] Chosen option justification references drivers

## Completeness
- [ ] Positive consequences listed
- [ ] Negative consequences listed (be honest!)
- [ ] Risks identified
- [ ] Mitigations proposed for risks
- [ ] Links to related ADRs

## Traceability
- [ ] Linked to technical story/ticket
- [ ] References relevant documentation
- [ ] Supersedes/relates to other ADRs if applicable

## Approval
- [ ] Architecture team reviewed
- [ ] Security team reviewed (if applicable)
- [ ] Infrastructure team reviewed (if applicable)

ADR Template

Summary

These Architecture Decision Records capture the foundational technical decisions for the POS Platform:

These decisions form the architectural foundation upon which the rest of the system is built.

Document Information

Change Log

Next Chapter: Chapter 03: Architecture Characteristics

This chapter is part of the POS Blueprint Book. All content is self-contained.

Chapter 03: Architecture Characteristics

Purpose

This appendix documents the formal architecture characteristics analysis for the Nexus POS Platform. It identifies the driving quality attributes that shape architectural decisions and provides justification for each characteristic’s priority.

Source: Architecture Characteristics Worksheet v2.0 (Expert Panel-Reviewed) System/Project: Nexus - Omnichannel Retail POS (Multi-Tenant Cloud) Architect/Team: Cloud AI Architecture Agents Domain/Quantum: Retail / Inventory Management / Multi-Platform Integration Date Modified: February 19, 2026 Panel Review Score: 6.50/10 → Updated per 4-member expert panel recommendations

K.1 Top 9 Driving Characteristics

These are the primary quality attributes that drive architectural decisions. They are listed in priority order.

K.2 Characteristics with Definitions and Justifications

K.2.1 Availability (Rank 1)

Justification:

“Offline First” capability is non-negotiable. Physical stores must be able to process transactions even if internet connectivity fails.

Architectural Implications:

• Local SQLite database on POS terminals
• Event queue for offline transaction storage
• Automatic sync when connectivity restored
• Graceful degradation patterns

Offline-First Justification

Retail network reality makes offline-first a non-negotiable design constraint:

Retail Network Reality
======================

Internet Outage at 2pm on Black Friday?
  Traditional POS: "Network Error - Cannot Process Sale" (DISASTER)
  Offline-First POS: Works normally, syncs when online (BUSINESS CONTINUES)

Slow WiFi during holiday rush?
  Traditional POS: 5-second delay per sale (FRUSTRATED CUSTOMERS)
  Offline-First POS: Instant response, sync in background (HAPPY CUSTOMERS)

Server maintenance window?
  Traditional POS: Store closes or uses manual paper (LOST REVENUE)
  Offline-First POS: No impact to operations (FULL REVENUE)

The offline-first design is governed by five core principles (from Ch 04, Section L.10A.1):

Event Sourcing Enables Offline Sync

Event sourcing (Ch 04 Section L.4A) directly supports availability by enabling offline event queues. When the POS client is offline, all business operations (sales, payments, inventory adjustments) are captured as immutable events stored locally. When connectivity is restored, these events are synced to the central server and merged deterministically. Because events are append-only and each has a unique ID, offline sales never conflict – they simply merge into the central event stream. This makes event sourcing a foundational enabler of the offline-first architecture.

K.2.2 Interoperability (Rank 2)

Justification:

BRD v18.0 Module 6 defines integration with 6 provider families across fundamentally different protocols:

The system must maintain an Anti-Corruption Layer (ACL) per provider to prevent external schema changes from propagating into the core POS domain. BRD Section 6.2 mandates:

• Provider Abstraction: IIntegrationProvider interface with 5 standard methods per provider
• Circuit Breaker: 5 failures within 60 seconds triggers OPEN state; 30-second cooldown before HALF_OPEN
• Idempotency Framework: 24-hour deduplication windows with SHA-256 keying (Section 6.2.5)
• Transactional Outbox: Atomic inventory reservation + guaranteed event publication

Architectural Implications:

• Anti-Corruption Layer (ACL) per provider preventing external schema leakage
• Provider Abstraction pattern (IIntegrationProvider) for uniform integration interface
• Circuit breaker pattern (CLOSED → OPEN → HALF_OPEN state machine)
• Idempotency framework with configurable dedup windows
• Transactional Outbox for guaranteed event delivery
• Rate limiter per provider with adaptive throttling

K.2.3 Data Consistency (Rank 3)

Justification:

Critical for handling the “Inventory Sync” race conditions between physical shoppers and online orders to prevent overselling.

Architectural Implications:

• Event Sourcing for Sales and Inventory domains
• Eventual consistency model with conflict resolution
• Optimistic concurrency control
• Idempotent event handlers

Event Sourcing Justification

Traditional CRUD systems store only current state. Event sourcing stores every change as an immutable event, providing the full history needed for audit trails, temporal queries, and offline conflict resolution (from Ch 04 Section L.4A):

Traditional CRUD vs Event Sourcing
==================================

CRUD Approach:
+------------------+
| inventory_items  |
|------------------|
| sku: NXP001      |
| quantity: 45     |  <- Only current state
| updated_at: now  |
+------------------+

Event Sourcing Approach:
+------------------+
| events           |
|------------------|
| InventoryReceived: +100 @ 2025-01-01 09:00  |
| ItemSold: -2 @ 2025-01-01 10:15             |
| ItemSold: -1 @ 2025-01-01 11:30             |
| ItemSold: -3 @ 2025-01-01 14:22             |
| AdjustmentMade: -49 @ 2025-01-01 16:00      |  <- Caught discrepancy!
| ItemSold: -1 @ 2025-01-02 09:15             |
| Current State: 45 (sum of all events)       |
+------------------+

Benefits for Retail POS:

K.2.4 Security (Rank 4 - Elevated)

Justification:

BRD v18.0 elevates security from basic PCI-DSS to 5 concrete security sub-domains:

Architectural Implications:

• HashiCorp Vault (Docker container) for centralized credential management
• 6-gate Security Test Pyramid in CI/CD pipeline
• Wazuh/OSSEC agents on all POS terminals for File Integrity Monitoring
• Architecture conformance tests (ArchUnit/NetArchTest) enforcing module boundaries
• Pact contract tests against Shopify/Amazon/Google sandbox APIs
• Audit trail with INTEGRATION category for OAuth operations and webhook verification

POS Security Layers

The system implements a 5-layer defense-in-depth security model (from Ch 04 Section L.9A):

Security Layers
===============

+------------------------------------------------------------------+
|                        INTERNET                                   |
+---------------------------+--------------------------------------+
                            |
                            v
+---------------------------+--------------------------------------+
|                    TLS TERMINATION                                |
|                    (Let's Encrypt)                                |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    API GATEWAY                                    |
|  +-----------------------+  +-----------------------+             |
|  | Rate Limiting         |  | IP Whitelisting       |             |
|  | 100 req/min/client    |  | (Admin Portal only)   |             |
|  +-----------------------+  +-----------------------+             |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    AUTHENTICATION                                 |
|  +-----------------------+  +-----------------------+             |
|  | JWT Validation        |  | PIN Verification      |             |
|  | - Signature check     |  | - Employee clock-in   |             |
|  | - Expiry check        |  | - Sensitive actions   |             |
|  | - Tenant claim        |  +-----------------------+             |
|  +-----------------------+                                        |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    AUTHORIZATION                                  |
|  +-----------------------+  +-----------------------+             |
|  | Role-Based (RBAC)     |  | Permission Policies   |             |
|  | - Admin               |  | - can:create_sale     |             |
|  | - Manager             |  | - can:void_sale       |             |
|  | - Cashier             |  | - can:view_reports    |             |
|  +-----------------------+  +-----------------------+             |
+------------------------------------------------------------------+

Each layer provides independent protection: TLS encrypts data in transit, the API gateway enforces rate limits and IP restrictions, JWT authentication validates identity and tenant context, PIN verification secures sensitive in-store actions, and RBAC authorization controls access to specific operations.

Tenant Data Isolation as Security Evidence

Schema-per-tenant isolation (from Ch 04 Section L.10A.4) provides a strong security boundary. Unlike row-level tenancy where a missing WHERE tenant_id = ? clause could leak data across tenants, schema-per-tenant ensures that tenant data is physically separated at the PostgreSQL schema level. Even if application code has a bug, PostgreSQL’s search_path mechanism prevents cross-tenant data access:

-- Query from Tenant A's context (search_path = tenant_nexus)
SELECT * FROM products;
-- Returns only Nexus products

-- Even if someone tries:
SELECT * FROM tenant_acme.products;
-- ERROR: permission denied for schema tenant_acme

K.2.5 Compliance (Rank 5 - NEW)

Justification:

BRD v18.0 introduces non-negotiable compliance requirements from 3 external platforms plus existing regulatory frameworks:

Architectural Implications:

• Platform policy validation engine (“strictest-rule-wins” cross-platform validation per BRD Section 6.6)
• Automated compliance checking on product data before channel publication
• Credential rotation policies per platform requirement
• Audit trail for all external interactions with INTEGRATION event category
• Jurisdiction-aware configuration (geographic expansion design from ADR-BRD-006)

Tenant Isolation Compliance Benefits

Schema-per-tenant isolation (from Ch 04 Section L.10A.4) directly supports SOC 2, GDPR, and HIPAA compliance requirements:

SOC 2 / GDPR Compliance
=======================

Requirement: "Customer data must be logically separated"

With schema-per-tenant:
- Each customer's data in isolated schema
- No risk of WHERE clause forgetting tenant_id
- Clear audit trail per schema
- Easy data export for GDPR requests
- Simple data deletion for "right to be forgotten"

Per-tenant backup and restore is trivially achieved (pg_dump -n tenant_nexus), making data portability and right-to-erasure requests straightforward to fulfill. This isolation model ensures compliance without relying on application-level WHERE clause correctness.

K.2.6 Modifiability (Rank 6)

Justification:

Plugin architecture is needed for frequent hardware/tax updates without full system rewrites.

Architectural Implications:

• Microkernel (Plugin) architecture for POS Client
• Hardware abstraction layer
• Tax calculation plugins
• Payment processor adapters

K.2.7 Scalability (Rank 7)

Justification:

At some point the system must be able to grow to accommodate the number of new tenants.

Architectural Implications:

• Row-Level Isolation with PostgreSQL RLS (tenant_id + RLS policies)
• Horizontal scaling of stateless API layer
• Connection pooling per tenant
• Resource quotas and throttling

K.2.8 Configurability (Rank 8 - ELEVATED from implicit)

Justification:

BRD Module 5 spans 3,000+ lines of setup and configuration requirements. The system must support hierarchical configuration at multiple levels:

Key configuration complexity drivers:

• Safety Buffers: 4-level priority resolution (Product → Category → Channel → Global) with 3 calculation modes (FIXED, PERCENTAGE, MIN_RESERVE) per BRD Section 6.7.2
• Integration YAML: Section 6.12 defines 400+ lines of declarative integration configuration
• Feature Toggles: Per-tenant inventory sync strategy (Safe vs. Aggressive), channel enablement
• Tax Jurisdictions: Modular jurisdiction support with geographic expansion (ADR-BRD-006)

Architectural Implications:

• Hierarchical configuration resolution with 4-level priority
• YAML-driven integration rules (machine-readable, version-controlled)
• Per-tenant per-channel safety buffer settings
• Runtime configuration hot-reload without service restart
• Configuration validation engine preventing invalid combinations

K.2.9 Performance (Rank 9)

Justification:

Low latency scanning/checkout is required to prevent queues during high traffic.

Architectural Implications:

• Optimized database indexes
• Read replicas for query-heavy operations
• Caching strategies (Redis)
• Async processing for non-critical operations

Multi-Tenant Performance Considerations

Schema-per-tenant isolation (from Ch 04 Section L.10A.4) has specific performance implications for connection pooling and query execution:

Connection Pooling:

Connection Pool Strategy
========================

                    +------------------+
                    |  Connection Pool |
                    |  (PgBouncer)     |
                    +--------+---------+
                             |
        +--------------------+--------------------+
        |                    |                    |
        v                    v                    v
+-------+-------+   +--------+------+   +---------+-----+
| Connection 1  |   | Connection 2  |   | Connection 3  |
| search_path:  |   | search_path:  |   | search_path:  |
| tenant_nexus  |   | tenant_acme   |   | tenant_nexus  |
+---------------+   +---------------+   +---------------+

Note: search_path is set per-connection, not per-query.
Use transaction pooling mode in PgBouncer.

Query Performance:

Schema-per-tenant eliminates the need for a tenant_id column in every query, resulting in simpler and faster queries:

-- Index per schema (automatically namespaced)
CREATE INDEX idx_products_sku ON tenant_nexus.products(sku);
CREATE INDEX idx_products_sku ON tenant_acme.products(sku);

-- No tenant_id in WHERE clause needed
-- Simpler, faster queries:
SELECT * FROM products WHERE sku = 'NXP0001';
-- vs (row-level tenancy):
SELECT * FROM products WHERE tenant_id = ? AND sku = 'NXP0001';

This eliminates per-query tenant filtering overhead and allows PostgreSQL’s query planner to work with smaller, tenant-scoped indexes for better cache efficiency.

Tenant Performance Isolation

Schema-per-tenant provides natural performance isolation between tenants. A tenant with a large product catalog or high transaction volume does not degrade query performance for other tenants because each schema has its own table statistics, indexes, and can be independently vacuumed and reindexed:

-- Vacuum single tenant without affecting others
VACUUM ANALYZE tenant_nexus.products;
VACUUM ANALYZE tenant_nexus.sales;

-- Reindex single tenant
REINDEX SCHEMA tenant_nexus;

K.3 Implicit Characteristics

These characteristics are inherently required but not explicitly driving architectural decisions.

K.4 Others Considered

These characteristics were evaluated but not prioritized as driving characteristics:

K.5 Characteristic Trade-offs

Understanding trade-offs between characteristics is critical for making consistent architectural decisions.

Trade-off Matrix

+------------------+------------------+------------------+------------------+------------------+
|                  |   AVAILABILITY   |   CONSISTENCY    |    COMPLIANCE    |  CONFIGURABILITY |
+------------------+------------------+------------------+------------------+------------------+
| AVAILABILITY     |        -         |    TENSION       |   NEUTRAL        |   SUPPORTS       |
| (Offline-First)  |                  | (Eventual Sync)  |                  | (Local config)   |
+------------------+------------------+------------------+------------------+------------------+
| CONSISTENCY      |    TENSION       |        -         |   SUPPORTS       |   TENSION        |
| (Data Sync)      | (Offline Mode)   |                  | (Audit Trail)    | (Config changes) |
+------------------+------------------+------------------+------------------+------------------+
| COMPLIANCE       |   NEUTRAL        |   SUPPORTS       |        -         |   SUPPORTS       |
| (Regulations)    |                  | (Audit Trail)    |                  | (Jurisdiction)   |
+------------------+------------------+------------------+------------------+------------------+
| CONFIGURABILITY  |   SUPPORTS       |    TENSION       |   SUPPORTS       |        -         |
| (Multi-level)    | (Local config)   | (Config changes) | (Jurisdiction)   |                  |
+------------------+------------------+------------------+------------------+------------------+
| PERFORMANCE      |   SUPPORTS       |    TENSION       |    TENSION       |    TENSION       |
| (Low Latency)    | (Local Cache)    | (Sync Overhead)  | (Validation)     | (Resolution)     |
+------------------+------------------+------------------+------------------+------------------+
| SECURITY         |    TENSION       |   SUPPORTS       |   SUPPORTS       |   NEUTRAL        |
| (Deep Scans)     | (Scan Time)      | (Audit Trail)    | (PCI-DSS)        |                  |
+------------------+------------------+------------------+------------------+------------------+

Key Trade-off Decisions

K.6 Characteristic-to-Chapter Mapping

Quick reference for finding characteristic implementations in the blueprint:

K.7 Review Schedule

K.8 Non-Functional Requirements (NFRs)

This section defines measurable targets that validate the architecture characteristics. All NFRs are traceable to BRD requirements.

K.8.1 Performance Requirements

Performance Budget:

Total Checkout Time Budget: 500ms
├── Item Lookup:        100ms
├── Price Calculation:  100ms
├── Tax Calculation:     50ms
├── Payment Processing: 150ms (excluding terminal wait)
└── Receipt/Finalize:   100ms

K.8.2 Availability Requirements

Availability Tiers:

Cloud Services:     99.9% (allows ~8.76 hrs downtime/year)
POS Terminal:       99.99% (via offline-first design)
Database (Primary): 99.95% (with automatic failover)

K.8.3 Scalability Requirements

Scaling Strategy:

Stateless API Layer:  Horizontal scaling (Kubernetes HPA)
Database:            Vertical scaling + Read replicas + RLS per tenant
Event Stream:        PostgreSQL event tables (v1.0), Kafka partitioning (v2.0)
File Storage:        Object storage (S3-compatible)

K.8.4 Integration & Timeout Requirements

Integration Patterns:

Synchronous:   REST APIs with circuit breaker
Asynchronous:  Event-driven via PostgreSQL Events + LISTEN/NOTIFY (v1.0)
Webhooks:      Inbound (Shopify/Amazon) + Outbound with Transactional Outbox
File Transfer: SFTP/S3 for bulk imports

K.8.5 Data & Compliance Requirements

Data Classification:

Level 1 (Restricted):  Card data (prohibited storage)
Level 2 (Sensitive):   Customer PII, credentials
Level 3 (Internal):    Transaction data, inventory
Level 4 (Public):      Product catalog, store hours

K.8.6 Security Requirements

SAQ-A Compliance - Data Storage Rules:

STORED (Allowed):
   - Payment tokens
   - Approval codes
   - Masked card number (****1234)
   - Card brand (Visa, MC, etc.)
   - Terminal ID

PROHIBITED (Never store):
   - Full card number (PAN)
   - CVV/CVC
   - Track data
   - PIN block
   - EMV cryptogram (raw)

K.8.7 Integration Requirements (BRD v18.0)

Integration Performance Budget:

Shopify Webhook Processing: < 5s
├── Receive + Validate Signature:  100ms
├── Deserialize + Map to Domain:   200ms
├── Business Logic Processing:     2,000ms
├── Database Persistence:          500ms
└── Outbox Event Publication:      200ms
     (Buffer):                     2,000ms

Amazon SP-API Polling Cycle: < 2min
├── OAuth Token Refresh (if needed): 500ms
├── API Call (paginated):            5,000ms
├── Response Mapping:                1,000ms
├── Inventory Delta Calculation:     2,000ms
└── Database + Outbox:               1,500ms
     (Buffer):                       110,000ms

K.8.8 NFR Traceability Matrix

This matrix links NFRs to Architecture Characteristics:

NFR Validation Schedule

Document Information

Change Log

Next Chapter: Chapter 04: Architecture Styles Analysis

This chapter is part of the POS Blueprint Book. All content is self-contained.

Chapter 04: Architecture Styles Analysis

Purpose

This chapter documents the formal architecture styles evaluation for the Nexus POS Platform. It provides the decision rationale for selecting the primary architecture style and supporting patterns, updated per expert panel review against BRD v18.0.

Source: Architecture Styles Worksheet v2.0 (Expert Panel-Reviewed) Project: POS Platform (RapOS) - Implementation for Tenant “Nexus” Architect/Team: Cloud AI Architecture Agents Date: February 19, 2026 Panel Review Score: 6.50/10 → Updated per 4-member expert panel recommendations

L.1 Candidate Architecture Styles

Based on the identified driving characteristics (Availability, Interoperability, Data Consistency), the following architecture styles were evaluated.

L.1.1 Event-Driven Architecture (EDA)

v18.0 Update: BRD designs around PostgreSQL tables for idempotency_records and integration_dead_letters (not Kafka topics). Amazon SP-API polls every 2 minutes; Google Merchant batches 2x/day. Streaming infrastructure is not required at launch. PostgreSQL event tables with LISTEN/NOTIFY provide sufficient event notification for v1.0. Kafka adoption deferred to v2.0 when transaction volume or real-time analytics requirements justify the operational overhead (ZooKeeper/KRaft cluster management).

L.1.2 Microservices Architecture

L.1.3 Microkernel (Plugin) Architecture

L.1.4 Modular Monolith (Layered) Architecture

v18.0 Update — Extractable Integration Gateway: Module 6 (Integrations, 4,800+ lines) is designed as a logically separate module within the monolith with explicit boundary contracts: IIntegrationProvider interface, async messaging via Transactional Outbox, and dedicated error handling (ERR-6xxx range). This module can be extracted to a separate service when scale demands independent deployment, without changing the core POS modules. Circuit breaker isolation ensures external API failures (Amazon, Google, Shopify) cannot cascade to POS checkout operations.

L.1.5 Service-Based Architecture

L.1.6 Space-Based Architecture

L.1.7 Event Sourcing (Architecture Pattern)

L.1.8 Offline-First (Architecture Pattern)

L.1.9 Integration Patterns (BRD v18.0 Module 6)

BRD v18.0 Section 6.2 mandates 5 integration patterns that are architecturally significant. These were evaluated during the expert panel review and all selected.

Circuit Breaker State Machine:

┌──────────────────────────────────────────────────────────┐
│              CIRCUIT BREAKER STATE MACHINE                 │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────┐   5 failures   ┌──────────┐               │
│  │  CLOSED  │ ──────────────►│   OPEN   │               │
│  │ (Normal) │   in 60 sec    │ (Reject) │               │
│  └────┬─────┘                └────┬─────┘               │
│       ▲                           │                      │
│       │ success                   │ 30 sec cooldown      │
│       │                           ▼                      │
│       │                    ┌───────────┐                 │
│       └────────────────────│ HALF_OPEN │                 │
│                            │ (1 probe) │                 │
│          failure ──────────└───────────┘──► OPEN         │
│                                                           │
└──────────────────────────────────────────────────────────┘

L.2 Style Evaluation Matrix

Ratings: 1 (Poor) to 5 (Excellent)

Monolithic Styles

v18.0 Note: Modular Monolith Interoperability reduced from 4★ to 3★. Module 6 requires 6 provider families with different scaling needs — a monolith cannot independently scale individual providers. Mitigated by Extractable Integration Gateway design.

Distributed Styles

v18.0 Note: Service-Based Interoperability raised from 3★ to 4★. Coarse-grained services can independently deploy integration providers.

Patterns

L.3 Key Trade-off Analysis

Trade-off 1: Availability vs. Consistency

Trade-off 2: Complexity (Event Sourcing + PostgreSQL Events)

Trade-off 3: Deployment Simplicity (Modular Monolith)

L.4 Selected Architecture Strategy

Primary Declaration

Architecture Layer Mapping

L.4A CQRS & Event Sourcing Scope

The expert panel identified that CQRS and Event Sourcing scope was undefined. This section clarifies which modules use which patterns, per user decision.

State Machine Implementation: Database-driven pattern using a state column on the entity table plus a state_transitions reference table. This approach provides:

• State column: Each stateful entity (e.g., orders.status, returns.status) stores current state directly
• Transition table: state_transitions(from_state, to_state, event, guard_condition, action) defines allowed transitions per entity type
• Validation: Application layer validates transitions against the table before applying (preventing invalid state changes)
• Audit: Every transition logged with timestamp, actor, and triggering event
• Benefits: Declarative (non-code) transition rules, easy to modify without deployment, queryable transition history

Design Note: State machines are NOT implemented via Event Sourcing replay. The state column holds current truth; ES events record the history. This separation keeps state lookups O(1) while maintaining full audit trail.

Event Sourcing vs. Audit Log Relationship: Event Sourcing and the audit log serve separate concerns and are complementary:

• Event Sourcing (Modules 1, 4, 6): Domain events that represent business state changes. Used for: event replay (Sales), conflict resolution (Inventory), sync debugging (Integrations). Stored in event store tables.
• Audit Log: Cross-cutting compliance record of who did what and when. Captures: user identity, IP address, action performed, timestamp, before/after values. Stored in dedicated audit_log table.
• Relationship: ES events feed INTO the audit log (via event handlers) but the audit log also captures non-ES actions (e.g., login attempts, configuration changes, report generation). The audit log is the compliance artifact; ES is the domain modeling tool.

Event Sourcing Implementation Pattern:

┌──────────────────────────────────────────────────────────┐
│           EVENT SOURCING PATTERN (Sales Module)           │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  Command ──► Aggregate ──► Domain Events ──► Event Store  │
│                                      │                    │
│                                      ▼                    │
│                              Event Handlers               │
│                              ┌─────────────┐              │
│                              │ Read Model  │ (CQRS)       │
│                              │ Projections │              │
│                              └─────────────┘              │
│                              ┌─────────────┐              │
│                              │ Audit Log   │              │
│                              │ (Immutable) │              │
│                              └─────────────┘              │
│                              ┌─────────────┐              │
│                              │ Integration │              │
│                              │ Outbox      │              │
│                              └─────────────┘              │
│                                                           │
│  Queries ──► Read Model (Materialized View) ──► Response  │
│                                                           │
└──────────────────────────────────────────────────────────┘

L.4A.1 Event Store Implementation

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Event Store Schema (PostgreSQL)

The append-only event store is the source of truth:

-- Event Store Schema

CREATE TABLE events (
    id              BIGSERIAL PRIMARY KEY,
    event_id        UUID UNIQUE NOT NULL DEFAULT gen_random_uuid(),
    aggregate_type  VARCHAR(100) NOT NULL,     -- 'Sale', 'Inventory', 'Customer'
    aggregate_id    UUID NOT NULL,             -- The entity this event belongs to
    event_type      VARCHAR(100) NOT NULL,     -- 'SaleCreated', 'ItemAdded'
    event_data      JSONB NOT NULL,            -- Full event payload
    metadata        JSONB NOT NULL DEFAULT '{}', -- Correlation, causation IDs
    version         INTEGER NOT NULL,          -- Aggregate version (for optimistic concurrency)
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by      UUID,                      -- Employee who caused the event

    -- Optimistic concurrency: aggregate_id + version must be unique
    UNIQUE (aggregate_type, aggregate_id, version)
);

-- Indexes for common queries
CREATE INDEX idx_events_aggregate ON events (aggregate_type, aggregate_id);
CREATE INDEX idx_events_type ON events (event_type);
CREATE INDEX idx_events_created_at ON events USING BRIN (created_at);
CREATE INDEX idx_events_metadata ON events USING GIN (metadata);

-- Snapshots table (for performance on long event streams)
CREATE TABLE snapshots (
    id              BIGSERIAL PRIMARY KEY,
    aggregate_type  VARCHAR(100) NOT NULL,
    aggregate_id    UUID NOT NULL,
    version         INTEGER NOT NULL,
    state           JSONB NOT NULL,            -- Serialized aggregate state
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    UNIQUE (aggregate_type, aggregate_id)
);

-- Outbox table (for reliable event publishing)
CREATE TABLE event_outbox (
    id              BIGSERIAL PRIMARY KEY,
    event_id        UUID NOT NULL REFERENCES events(event_id),
    destination     VARCHAR(100) NOT NULL,     -- 'signalr', 'webhook', 'sync'
    status          VARCHAR(20) DEFAULT 'pending',
    attempts        INTEGER DEFAULT 0,
    last_error      TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    processed_at    TIMESTAMPTZ
);

Event Sourcing Architecture Diagram

Event Sourcing Architecture
===========================

+-------------------------------------------------------------------------+
|                              POS CLIENT                                  |
|                                                                          |
|   +------------------+    +-------------------+    +-----------------+   |
|   |  Command Handler |    |   Event Store     |    |   Projector     |   |
|   |                  |    |   (Local SQLite)  |    |   (Read Model)  |   |
|   |  CreateSale      |--->|                   |--->|                 |   |
|   |  VoidSale        |    | SaleCreated       |    | sale_summaries  |   |
|   |  AddPayment      |    | ItemAdded         |    | inventory_view  |   |
|   +------------------+    | PaymentReceived   |    +-----------------+   |
|                           +-------------------+                          |
|                                    |                                     |
+-------------------------------------------------------------------------+
                                     | Sync
                                     v
+-------------------------------------------------------------------------+
|                            CENTRAL API                                   |
|                                                                          |
|   +------------------+    +-------------------+    +-----------------+   |
|   |  Command Handler |    |   Event Store     |    |   Projector     |   |
|   |  (Validates)     |    |   (PostgreSQL)    |    |   (Read Model)  |   |
|   |                  |<---|                   |--->|                 |   |
|   |  Deduplication   |    | All tenant events |    | sales           |   |
|   |  Conflict Check  |    | Append-only       |    | inventory_items |   |
|   +------------------+    | Immutable         |    | customers       |   |
|                           +-------------------+    +-----------------+   |
+-------------------------------------------------------------------------+

CQRS Pattern

CQRS Pattern
============

                          +----------------------+
                          |     User Action      |
                          +----------+-----------+
                                     |
              +----------------------+----------------------+
              |                                             |
              v                                             v
    +-------------------+                        +-------------------+
    |     COMMAND       |                        |      QUERY        |
    |     (Write)       |                        |      (Read)       |
    +-------------------+                        +-------------------+
              |                                             |
              v                                             v
    +-------------------+                        +-------------------+
    | Command Handler   |                        | Query Handler     |
    | - Validate        |                        | - No validation   |
    | - Business rules  |                        | - Fast lookup     |
    | - Generate events |                        | - Denormalized    |
    +-------------------+                        +-------------------+
              |                                             ^
              v                                             |
    +-------------------+                        +-------------------+
    |   Event Store     |----------------------->|   Read Models     |
    |   (Append-only)   |     Projections       |   (Optimized)     |
    +-------------------+                        +-------------------+

Write Side (Commands)

// Commands - Express intent
public record CreateSaleCommand(
    Guid SaleId,
    Guid LocationId,
    Guid EmployeeId,
    Guid? CustomerId,
    List<SaleLineItemDto> LineItems
);

public record VoidSaleCommand(
    Guid SaleId,
    Guid EmployeeId,
    string Reason
);

public record AddPaymentCommand(
    Guid SaleId,
    string PaymentMethod,
    decimal Amount,
    string? Reference
);

Read Side (Queries)

// Queries - Request data
public record GetSaleByIdQuery(Guid SaleId);
public record GetDailySalesQuery(Guid LocationId, DateTime Date);
public record GetInventoryLevelQuery(string Sku, Guid LocationId);

// Read models - Optimized for queries
public class SaleSummaryView
{
    public Guid Id { get; set; }
    public string SaleNumber { get; set; }
    public string CustomerName { get; set; }  // Denormalized
    public string EmployeeName { get; set; }  // Denormalized
    public decimal Total { get; set; }
    public string Status { get; set; }
    public DateTime CreatedAt { get; set; }
}

L.4A.2 Event Streaming (Apache Kafka)

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Technology Selection

Why Kafka over alternatives?

Kafka Replayability

+------------------------------------------------------------------+
|                    KAFKA REPLAYABILITY                            |
+------------------------------------------------------------------+
|                                                                   |
|  Event Log (Immutable, Ordered):                                  |
|                                                                   |
|  Partition 0:  [E1] -> [E2] -> [E3] -> [E4] -> [E5] -> ...       |
|                         ^              ^                          |
|                         |              |                          |
|  Consumer Group A: ─────┘              |  (Processed up to E2)   |
|  Consumer Group B: ────────────────────┘  (Processed up to E4)   |
|                                                                   |
|  NEW Consumer Group C can start from E1 and replay ALL events!   |
|                                                                   |
+------------------------------------------------------------------+

Kafka Topics Architecture

POS Kafka Topics
================

┌────────────────────────────────────────────────────────────────┐
│                     TOPIC STRUCTURE                             │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  pos.events.sales         - All sale-related events            │
│  ├── Partition 0 (Location A)                                  │
│  ├── Partition 1 (Location B)                                  │
│  └── Partition N (Location N)                                  │
│                                                                 │
│  pos.events.inventory     - Inventory movements                │
│  ├── Partition 0-N (By SKU hash)                               │
│                                                                 │
│  pos.events.customers     - Customer activity                  │
│  ├── Partition 0-N (By customer hash)                          │
│                                                                 │
│  pos.sync.outbound        - Events to sync to external systems │
│  ├── Shopify, Amazon, etc.                                     │
│                                                                 │
│  pos.sync.inbound         - Events from external systems       │
│  ├── Online orders, inventory updates                          │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

Kafka Configuration (Docker Compose)

# docker-compose.kafka.yml

services:
  kafka:
    image: confluentinc/cp-kafka:7.5.0
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_LOG_RETENTION_HOURS: 168  # 7 days
      KAFKA_LOG_RETENTION_BYTES: 10737418240  # 10GB per partition
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: false
    ports:
      - "9092:9092"
    volumes:
      - kafka_data:/var/lib/kafka/data

  kafka-ui:
    image: provectuslabs/kafka-ui:latest
    environment:
      KAFKA_CLUSTERS_0_NAME: pos-cluster
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
    ports:
      - "8090:8080"

Event Publishing Pattern

// KafkaEventPublisher.cs

public class KafkaEventPublisher : IEventPublisher
{
    private readonly IProducer<string, string> _producer;
    private readonly ILogger<KafkaEventPublisher> _logger;

    public async Task PublishAsync<T>(T @event, CancellationToken ct = default)
        where T : IDomainEvent
    {
        var topic = GetTopicForEvent(@event);
        var key = GetPartitionKey(@event);  // e.g., LocationId for ordering

        var message = new Message<string, string>
        {
            Key = key,
            Value = JsonSerializer.Serialize(@event),
            Headers = new Headers
            {
                { "event-type", Encoding.UTF8.GetBytes(@event.GetType().Name) },
                { "correlation-id", Encoding.UTF8.GetBytes(@event.CorrelationId.ToString()) },
                { "tenant-id", Encoding.UTF8.GetBytes(@event.TenantId.ToString()) }
            }
        };

        var result = await _producer.ProduceAsync(topic, message, ct);

        _logger.LogDebug(
            "Published {EventType} to {Topic}:{Partition}@{Offset}",
            @event.GetType().Name,
            result.Topic,
            result.Partition.Value,
            result.Offset.Value
        );
    }

    private string GetTopicForEvent(IDomainEvent @event) => @event switch
    {
        SaleCreated or SaleCompleted or SaleVoided => "pos.events.sales",
        InventoryReceived or InventorySold => "pos.events.inventory",
        CustomerCreated or LoyaltyPointsEarned => "pos.events.customers",
        _ => "pos.events.general"
    };
}

Schema Registry & Event Versioning

Overview

As the POS platform evolves, event schemas will change. Schema Registry provides:

• Schema Validation: Prevent incompatible events from being published
• Schema Evolution: Safe migrations without breaking consumers
• Schema History: Version tracking for all event types

Schema Registry Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    SCHEMA REGISTRY FLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐     ┌──────────────────┐     ┌─────────────┐   │
│  │  Producer   │     │  Schema Registry │     │   Consumer  │   │
│  │  (POS API)  │     │   (Confluent)    │     │ (Analytics) │   │
│  └──────┬──────┘     └────────┬─────────┘     └──────┬──────┘   │
│         │                     │                      │          │
│    1. Register/Get Schema     │                      │          │
│         │ ─────────────────>  │                      │          │
│         │                     │                      │          │
│    2. Schema ID returned      │                      │          │
│         │ <─────────────────  │                      │          │
│         │                     │                      │          │
│    3. Publish event with      │                      │          │
│       schema ID prefix        │                      │          │
│         │ ─────────────────────────────────────────> │          │
│         │                     │                      │          │
│                               │  4. Consumer fetches │          │
│                               │     schema by ID     │          │
│                               │ <─────────────────── │          │
│                               │                      │          │
│                               │  5. Deserialize with │          │
│                               │     correct schema   │          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Avro Schema Definition (SaleCreated)

// schemas/sale-created.avsc
{
  "type": "record",
  "name": "SaleCreated",
  "namespace": "io.posplatform.events.sales",
  "doc": "Event fired when a new sale is initiated",
  "fields": [
    {
      "name": "eventId",
      "type": { "type": "string", "logicalType": "uuid" },
      "doc": "Unique event identifier"
    },
    {
      "name": "saleId",
      "type": { "type": "string", "logicalType": "uuid" },
      "doc": "Sale aggregate identifier"
    },
    {
      "name": "tenantId",
      "type": { "type": "string", "logicalType": "uuid" }
    },
    {
      "name": "locationId",
      "type": { "type": "string", "logicalType": "uuid" }
    },
    {
      "name": "employeeId",
      "type": { "type": "string", "logicalType": "uuid" }
    },
    {
      "name": "customerId",
      "type": ["null", { "type": "string", "logicalType": "uuid" }],
      "default": null,
      "doc": "Optional customer for loyalty"
    },
    {
      "name": "saleNumber",
      "type": "string"
    },
    {
      "name": "createdAt",
      "type": { "type": "long", "logicalType": "timestamp-millis" }
    },
    {
      "name": "metadata",
      "type": {
        "type": "map",
        "values": "string"
      },
      "default": {}
    }
  ]
}

Schema Evolution Rules (BACKWARD Compatibility)

Schema Evolution Example (v2)

// schemas/sale-created-v2.avsc (BACKWARD COMPATIBLE)
{
  "type": "record",
  "name": "SaleCreated",
  "namespace": "io.posplatform.events.sales",
  "fields": [
    // ... existing fields ...

    // NEW FIELD - Added with default value (BACKWARD COMPATIBLE)
    {
      "name": "channel",
      "type": "string",
      "default": "in_store",
      "doc": "Sales channel: in_store, online, mobile"
    },

    // NEW OPTIONAL FIELD (BACKWARD COMPATIBLE)
    {
      "name": "referralCode",
      "type": ["null", "string"],
      "default": null
    }
  ]
}

Producer Configuration with Schema Registry

// Infrastructure/Messaging/SchemaRegistryProducer.cs

using Confluent.Kafka;
using Confluent.SchemaRegistry;
using Confluent.SchemaRegistry.Serdes;

public class SchemaRegistryProducer<TKey, TValue> : IEventPublisher
    where TValue : ISpecificRecord
{
    private readonly IProducer<TKey, TValue> _producer;

    public SchemaRegistryProducer(
        string bootstrapServers,
        string schemaRegistryUrl)
    {
        var schemaRegistryConfig = new SchemaRegistryConfig
        {
            Url = schemaRegistryUrl
        };

        var schemaRegistry = new CachedSchemaRegistryClient(schemaRegistryConfig);

        var producerConfig = new ProducerConfig
        {
            BootstrapServers = bootstrapServers,
            Acks = Acks.All,  // Wait for all replicas
            EnableIdempotence = true
        };

        _producer = new ProducerBuilder<TKey, TValue>(producerConfig)
            .SetKeySerializer(new AvroSerializer<TKey>(schemaRegistry))
            .SetValueSerializer(new AvroSerializer<TValue>(schemaRegistry, new AvroSerializerConfig
            {
                // Fail if schema is not compatible
                AutoRegisterSchemas = false,
                SubjectNameStrategy = SubjectNameStrategy.TopicRecord
            }))
            .Build();
    }

    public async Task PublishAsync(
        string topic,
        TKey key,
        TValue value,
        CancellationToken ct = default)
    {
        var result = await _producer.ProduceAsync(topic, new Message<TKey, TValue>
        {
            Key = key,
            Value = value
        }, ct);

        _logger.LogDebug(
            "Published {EventType} to {Topic} with schema ID {SchemaId}",
            typeof(TValue).Name,
            result.Topic,
            result.Value
        );
    }
}

CI/CD Schema Validation

# .github/workflows/schema-validation.yml

name: Schema Validation

on:
  pull_request:
    paths:
      - 'schemas/**'

jobs:
  validate-schemas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start Schema Registry
        run: |
          docker compose -f docker/docker-compose.kafka.yml up -d schema-registry
          sleep 10

      - name: Test Schema Compatibility
        run: |
          for schema in schemas/*.avsc; do
            subject=$(basename "$schema" .avsc)-value
            echo "Testing compatibility for $subject"

            # Check if schema is BACKWARD compatible with existing
            curl -X POST \
              -H "Content-Type: application/vnd.schemaregistry.v1+json" \
              -d @"$schema" \
              "http://localhost:8081/compatibility/subjects/$subject/versions/latest" \
              | jq -e '.is_compatible == true' || exit 1
          done

      - name: Register Schemas (on merge to main)
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          for schema in schemas/*.avsc; do
            subject=$(basename "$schema" .avsc)-value
            curl -X POST \
              -H "Content-Type: application/vnd.schemaregistry.v1+json" \
              -d "{\"schema\": $(cat "$schema" | jq -Rs .)}" \
              "http://localhost:8081/subjects/$subject/versions"
          done

Docker Compose with Schema Registry

# docker/docker-compose.kafka.yml (updated)

services:
  schema-registry:
    image: confluentinc/cp-schema-registry:7.5.0
    container_name: pos-schema-registry
    depends_on:
      - kafka
    ports:
      - "8081:8081"
    environment:
      SCHEMA_REGISTRY_HOST_NAME: schema-registry
      SCHEMA_REGISTRY_KAFKASTORE_BOOTSTRAP_SERVERS: kafka:9092
      SCHEMA_REGISTRY_LISTENERS: http://0.0.0.0:8081
      # Enforce BACKWARD compatibility by default
      SCHEMA_REGISTRY_SCHEMA_COMPATIBILITY_LEVEL: BACKWARD

L.4A.3 Dead Letter Queue Pattern

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Overview

When event processing fails (malformed data, business rule violations, transient errors), messages go to a Dead Letter Queue for investigation and replay.

DLQ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       DLQ PATTERN                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐    │
│  │ pos.events.   │    │    Consumer   │    │   Handler     │    │
│  │    sales      │───>│    Group      │───>│   Logic       │    │
│  │  (Main Topic) │    │               │    │               │    │
│  └───────────────┘    └───────────────┘    └───────┬───────┘    │
│                                                     │            │
│                                             ┌───────┴───────┐    │
│                                             │   Success?    │    │
│                                             └───────┬───────┘    │
│                                        Yes ┌───────┴───────┐ No │
│                                            │               │     │
│                                            ▼               ▼     │
│                                      ┌──────────┐  ┌───────────┐ │
│                                      │  Commit  │  │  Retry    │ │
│                                      │  Offset  │  │  Logic    │ │
│                                      └──────────┘  └─────┬─────┘ │
│                                                          │       │
│                                                   ┌──────┴─────┐ │
│                                                   │ Max Retries│ │
│                                                   │  Exceeded? │ │
│                                                   └──────┬─────┘ │
│                                              No ┌────────┴──────┐│
│                                                 │               ││
│                                                 ▼               ▼│
│                                           ┌──────────┐  ┌────────┴──┐
│                                           │  Retry   │  │    DLQ    │
│                                           │  Topic   │  │   Topic   │
│                                           └──────────┘  └───────────┘
│                                                         pos.events.
│                                                         sales.dlq
└─────────────────────────────────────────────────────────────────┘

DLQ Consumer Implementation

// Infrastructure/Messaging/DlqAwareConsumer.cs

public class DlqAwareConsumer<TKey, TValue>
{
    private readonly IConsumer<TKey, TValue> _consumer;
    private readonly IProducer<string, DeadLetterMessage> _dlqProducer;
    private readonly ILogger _logger;

    private const int MAX_RETRIES = 3;
    private readonly TimeSpan[] _retryDelays = new[]
    {
        TimeSpan.FromSeconds(1),
        TimeSpan.FromSeconds(5),
        TimeSpan.FromSeconds(30)
    };

    public async Task ConsumeWithDlqAsync(
        string topic,
        Func<ConsumeResult<TKey, TValue>, Task> handler,
        CancellationToken ct)
    {
        _consumer.Subscribe(topic);

        while (!ct.IsCancellationRequested)
        {
            var result = _consumer.Consume(ct);
            var retryCount = GetRetryCount(result.Message.Headers);

            try
            {
                await handler(result);
                _consumer.Commit(result);
            }
            catch (TransientException ex) when (retryCount < MAX_RETRIES)
            {
                _logger.LogWarning(
                    ex,
                    "Transient error processing message. Retry {Retry}/{Max}",
                    retryCount + 1,
                    MAX_RETRIES
                );

                await Task.Delay(_retryDelays[retryCount], ct);
                await PublishToRetryTopicAsync(result, retryCount + 1);
                _consumer.Commit(result);
            }
            catch (Exception ex)
            {
                _logger.LogError(
                    ex,
                    "Failed to process message after {Retries} retries. Sending to DLQ.",
                    retryCount
                );

                await PublishToDlqAsync(result, ex, retryCount);
                _consumer.Commit(result);
            }
        }
    }

    private async Task PublishToDlqAsync(
        ConsumeResult<TKey, TValue> result,
        Exception exception,
        int retryCount)
    {
        var dlqMessage = new DeadLetterMessage
        {
            OriginalTopic = result.Topic,
            OriginalPartition = result.Partition.Value,
            OriginalOffset = result.Offset.Value,
            Key = result.Message.Key?.ToString(),
            Value = SerializeValue(result.Message.Value),
            Headers = ExtractHeaders(result.Message.Headers),
            ErrorType = exception.GetType().FullName,
            ErrorMessage = exception.Message,
            StackTrace = exception.StackTrace,
            RetryCount = retryCount,
            FirstFailedAt = GetFirstFailedAt(result.Message.Headers),
            LastFailedAt = DateTime.UtcNow,
            ConsumerGroup = _consumerGroup,
            ConsumerInstance = Environment.MachineName
        };

        var dlqTopic = $"{result.Topic}.dlq";
        await _dlqProducer.ProduceAsync(dlqTopic, new Message<string, DeadLetterMessage>
        {
            Key = result.Message.Key?.ToString(),
            Value = dlqMessage
        });
    }
}

DLQ Message Structure

// Domain/Events/DeadLetterMessage.cs

public record DeadLetterMessage
{
    /// <summary>Original Kafka topic</summary>
    public string OriginalTopic { get; init; }

    /// <summary>Original partition</summary>
    public int OriginalPartition { get; init; }

    /// <summary>Original offset</summary>
    public long OriginalOffset { get; init; }

    /// <summary>Original message key</summary>
    public string Key { get; init; }

    /// <summary>Original message value (base64 if binary)</summary>
    public string Value { get; init; }

    /// <summary>Original headers</summary>
    public Dictionary<string, string> Headers { get; init; }

    /// <summary>Error details</summary>
    public string ErrorType { get; init; }
    public string ErrorMessage { get; init; }
    public string StackTrace { get; init; }

    /// <summary>Processing metadata</summary>
    public int RetryCount { get; init; }
    public DateTime FirstFailedAt { get; init; }
    public DateTime LastFailedAt { get; init; }
    public string ConsumerGroup { get; init; }
    public string ConsumerInstance { get; init; }
}

DLQ Monitoring & Alerting

# prometheus/alerts/dlq-alerts.yml

groups:
  - name: kafka-dlq-alerts
    rules:
      - alert: DLQMessagesAccumulating
        expr: kafka_consumer_group_lag{topic=~".*\\.dlq"} > 100
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "DLQ has {{ $value }} unprocessed messages"
          description: "Topic {{ $labels.topic }} has accumulated messages"

      - alert: DLQCriticalBacklog
        expr: kafka_consumer_group_lag{topic=~".*\\.dlq"} > 1000
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "CRITICAL: DLQ backlog exceeds 1000 messages"
          runbook_url: "https://wiki.internal/runbooks/dlq-overflow"

DLQ Replay Tool

// Tools/DlqReplayService.cs

public class DlqReplayService
{
    public async Task ReplayMessagesAsync(
        string dlqTopic,
        DateTime? from = null,
        DateTime? to = null,
        Func<DeadLetterMessage, bool>? filter = null)
    {
        var consumer = CreateDlqConsumer(dlqTopic);
        var producer = CreateMainTopicProducer();

        var messages = await ReadDlqMessagesAsync(consumer, from, to);

        foreach (var dlqMessage in messages)
        {
            if (filter != null && !filter(dlqMessage))
            {
                _logger.LogDebug("Skipping message by filter: {Key}", dlqMessage.Key);
                continue;
            }

            _logger.LogInformation(
                "Replaying message from DLQ: Topic={Topic}, Offset={Offset}",
                dlqMessage.OriginalTopic,
                dlqMessage.OriginalOffset
            );

            // Publish back to original topic
            await producer.ProduceAsync(dlqMessage.OriginalTopic, new Message<string, string>
            {
                Key = dlqMessage.Key,
                Value = dlqMessage.Value,
                Headers = new Headers
                {
                    { "x-dlq-replay", Encoding.UTF8.GetBytes("true") },
                    { "x-dlq-original-offset", Encoding.UTF8.GetBytes(dlqMessage.OriginalOffset.ToString()) }
                }
            });
        }

        _logger.LogInformation("Replayed {Count} messages from DLQ", messages.Count);
    }
}

# CLI usage for DLQ replay
dotnet run --project tools/DlqReplay -- \
  --topic pos.events.sales.dlq \
  --from "2026-01-20T00:00:00Z" \
  --filter "ErrorType contains 'Transient'"

L.4A.4 Domain Events Catalog

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Sale Aggregate Events

Sale Events
===========

SaleCreated
+-----------------------+----------------------------------------+
| Field                 | Description                            |
+-----------------------+----------------------------------------+
| sale_id               | UUID of the new sale                   |
| sale_number           | Human-readable sale number             |
| location_id           | Where the sale occurred                |
| register_id           | Which register                         |
| employee_id           | Who created the sale                   |
| customer_id           | Customer (if any)                      |
| created_at            | Timestamp                              |
+-----------------------+----------------------------------------+

SaleLineItemAdded
+-----------------------+----------------------------------------+
| sale_id               | Parent sale                            |
| line_item_id          | UUID of the line item                  |
| product_id            | Product being sold                     |
| variant_id            | Variant (if any)                       |
| sku                   | SKU at time of sale                    |
| name                  | Product name at time of sale           |
| quantity              | Quantity sold                          |
| unit_price            | Price per unit                         |
| discount_amount       | Line discount                          |
| tax_amount            | Line tax                               |
+-----------------------+----------------------------------------+

SaleLineItemRemoved
+-----------------------+----------------------------------------+
| sale_id               | Parent sale                            |
| line_item_id          | UUID of removed item                   |
| reason                | Why removed                            |
+-----------------------+----------------------------------------+

PaymentReceived
+-----------------------+----------------------------------------+
| sale_id               | Parent sale                            |
| payment_id            | UUID of payment                        |
| payment_method        | cash, credit, debit, etc.              |
| amount                | Payment amount                         |
| reference             | Card last 4, check #, etc.             |
| auth_code             | Authorization code                     |
+-----------------------+----------------------------------------+

SaleCompleted
+-----------------------+----------------------------------------+
| sale_id               | The sale being completed               |
| subtotal              | Final subtotal                         |
| discount_total        | Total discounts                        |
| tax_total             | Total tax                              |
| total                 | Final total                            |
| completed_at          | Timestamp                              |
+-----------------------+----------------------------------------+

SaleVoided
+-----------------------+----------------------------------------+
| sale_id               | The voided sale                        |
| voided_by             | Employee who voided                    |
| reason                | Void reason                            |
| voided_at             | Timestamp                              |
+-----------------------+----------------------------------------+

Inventory Aggregate Events

Inventory Events
================

InventoryReceived
+-----------------------+----------------------------------------+
| location_id           | Where received                         |
| product_id            | Product                                |
| variant_id            | Variant (if any)                       |
| quantity              | Amount received                        |
| cost                  | Unit cost                              |
| reference             | PO number, transfer #                  |
| received_by           | Employee                               |
+-----------------------+----------------------------------------+

InventoryAdjusted
+-----------------------+----------------------------------------+
| location_id           | Location                               |
| product_id            | Product                                |
| variant_id            | Variant (if any)                       |
| quantity_change       | +/- amount                             |
| new_quantity          | New on-hand quantity                   |
| reason                | count, damage, theft, return           |
| adjusted_by           | Employee                               |
| notes                 | Additional context                     |
+-----------------------+----------------------------------------+

InventorySold
+-----------------------+----------------------------------------+
| location_id           | Where sold                             |
| product_id            | Product                                |
| variant_id            | Variant (if any)                       |
| quantity              | Amount sold (positive)                 |
| sale_id               | Related sale                           |
+-----------------------+----------------------------------------+

InventoryTransferred
+-----------------------+----------------------------------------+
| transfer_id           | Transfer document                      |
| from_location_id      | Source location                        |
| to_location_id        | Destination location                   |
| product_id            | Product                                |
| variant_id            | Variant (if any)                       |
| quantity              | Amount transferred                     |
| transferred_by        | Employee                               |
+-----------------------+----------------------------------------+

InventoryCounted
+-----------------------+----------------------------------------+
| location_id           | Location                               |
| product_id            | Product                                |
| variant_id            | Variant                                |
| expected_quantity     | System quantity before count           |
| actual_quantity       | Physical count                         |
| variance              | Difference                             |
| counted_by            | Employee                               |
| count_session_id      | Batch count session                    |
+-----------------------+----------------------------------------+

Customer Aggregate Events

Customer Events
===============

CustomerCreated
+-----------------------+----------------------------------------+
| customer_id           | New customer UUID                      |
| customer_number       | Human-readable ID                      |
| first_name            | First name                             |
| last_name             | Last name                              |
| email                 | Email address                          |
| phone                 | Phone number                           |
| created_by            | Employee                               |
+-----------------------+----------------------------------------+

CustomerUpdated
+-----------------------+----------------------------------------+
| customer_id           | Customer UUID                          |
| changes               | Map of field -> {old, new}             |
| updated_by            | Employee                               |
+-----------------------+----------------------------------------+

LoyaltyPointsEarned
+-----------------------+----------------------------------------+
| customer_id           | Customer                               |
| points                | Points earned                          |
| sale_id               | Related sale                           |
| new_balance           | Updated balance                        |
+-----------------------+----------------------------------------+

LoyaltyPointsRedeemed
+-----------------------+----------------------------------------+
| customer_id           | Customer                               |
| points                | Points redeemed                        |
| sale_id               | Related sale                           |
| new_balance           | Updated balance                        |
+-----------------------+----------------------------------------+

StoreCreditIssued
+-----------------------+----------------------------------------+
| customer_id           | Customer                               |
| credit_id             | Credit UUID                            |
| amount                | Credit amount                          |
| reason                | Why issued                             |
| issued_by             | Employee                               |
+-----------------------+----------------------------------------+

Employee Aggregate Events

Employee Events
===============

EmployeeClockIn
+-----------------------+----------------------------------------+
| employee_id           | Employee UUID                          |
| location_id           | Where clocking in                      |
| shift_id              | New shift UUID                         |
| clocked_in_at         | Timestamp                              |
+-----------------------+----------------------------------------+

EmployeeClockOut
+-----------------------+----------------------------------------+
| employee_id           | Employee UUID                          |
| shift_id              | Shift being closed                     |
| clocked_out_at        | Timestamp                              |
| break_minutes         | Total break time                       |
+-----------------------+----------------------------------------+

EmployeeBreakStarted
+-----------------------+----------------------------------------+
| employee_id           | Employee UUID                          |
| shift_id              | Current shift                          |
| started_at            | Break start time                       |
+-----------------------+----------------------------------------+

EmployeeBreakEnded
+-----------------------+----------------------------------------+
| employee_id           | Employee UUID                          |
| shift_id              | Current shift                          |
| ended_at              | Break end time                         |
| duration_minutes      | Break duration                         |
+-----------------------+----------------------------------------+

CashDrawer Aggregate Events

Cash Drawer Events
==================

DrawerOpened
+-----------------------+----------------------------------------+
| drawer_id             | Drawer UUID                            |
| register_id           | Register UUID                          |
| employee_id           | Who opened                             |
| opening_balance       | Starting cash amount                   |
| opened_at             | Timestamp                              |
+-----------------------+----------------------------------------+

DrawerCashDrop
+-----------------------+----------------------------------------+
| drawer_id             | Drawer UUID                            |
| amount                | Amount dropped to safe                 |
| employee_id           | Who dropped                            |
| dropped_at            | Timestamp                              |
+-----------------------+----------------------------------------+

DrawerPaidIn
+-----------------------+----------------------------------------+
| drawer_id             | Drawer UUID                            |
| amount                | Amount added                           |
| reason                | Why (petty cash, etc.)                 |
| employee_id           | Who added                              |
+-----------------------+----------------------------------------+

DrawerPaidOut
+-----------------------+----------------------------------------+
| drawer_id             | Drawer UUID                            |
| amount                | Amount removed                         |
| reason                | Why (vendor payment, etc.)             |
| employee_id           | Who removed                            |
+-----------------------+----------------------------------------+

DrawerClosed
+-----------------------+----------------------------------------+
| drawer_id             | Drawer UUID                            |
| employee_id           | Who closed                             |
| closing_balance       | Actual cash counted                    |
| expected_balance      | System calculated                      |
| variance              | Difference (over/short)                |
| closed_at             | Timestamp                              |
+-----------------------+----------------------------------------+

L.4A.5 Event Projection Patterns

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Projection Architecture
=======================

+-------------------+
|   Event Stream    |
|                   |
| SaleCreated       |
| ItemAdded         |
| ItemAdded         |
| PaymentReceived   |
| SaleCompleted     |
+--------+----------+
         |
         | Projector reads events
         v
+-------------------+     +-------------------+     +-------------------+
| Sale Projector    |     |Inventory Projector|     |Customer Projector |
|                   |     |                   |     |                   |
| - Build sale view |     | - Update stock    |     | - Update stats    |
| - Calculate totals|     | - Track movements |     | - Loyalty points  |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                         |
         v                         v                         v
+-------------------+     +-------------------+     +-------------------+
| sale_summaries    |     | inventory_levels  |     | customer_stats    |
| (Read Model)      |     | (Read Model)      |     | (Read Model)      |
+-------------------+     +-------------------+     +-------------------+

Sale Projector Implementation

// SaleProjector.cs

public class SaleProjector : IEventHandler
{
    private readonly IDbContextFactory<ReadModelDbContext> _dbFactory;

    public SaleProjector(IDbContextFactory<ReadModelDbContext> dbFactory)
    {
        _dbFactory = dbFactory;
    }

    public async Task HandleAsync(SaleCreated @event)
    {
        await using var db = await _dbFactory.CreateDbContextAsync();

        var view = new SaleSummaryView
        {
            Id = @event.SaleId,
            SaleNumber = @event.SaleNumber,
            LocationId = @event.LocationId,
            EmployeeId = @event.EmployeeId,
            CustomerId = @event.CustomerId,
            Status = "draft",
            Subtotal = 0,
            Total = 0,
            CreatedAt = @event.CreatedAt
        };

        db.SaleSummaries.Add(view);
        await db.SaveChangesAsync();
    }

    public async Task HandleAsync(SaleLineItemAdded @event)
    {
        await using var db = await _dbFactory.CreateDbContextAsync();

        var sale = await db.SaleSummaries.FindAsync(@event.SaleId);
        if (sale == null) return;

        var lineTotal = @event.Quantity * @event.UnitPrice - @event.DiscountAmount;
        sale.Subtotal += lineTotal;
        sale.ItemCount += @event.Quantity;

        await db.SaveChangesAsync();
    }

    public async Task HandleAsync(SaleCompleted @event)
    {
        await using var db = await _dbFactory.CreateDbContextAsync();

        var sale = await db.SaleSummaries.FindAsync(@event.SaleId);
        if (sale == null) return;

        sale.Status = "completed";
        sale.DiscountTotal = @event.DiscountTotal;
        sale.TaxTotal = @event.TaxTotal;
        sale.Total = @event.Total;
        sale.CompletedAt = @event.CompletedAt;

        await db.SaveChangesAsync();
    }

    public async Task HandleAsync(SaleVoided @event)
    {
        await using var db = await _dbFactory.CreateDbContextAsync();

        var sale = await db.SaleSummaries.FindAsync(@event.SaleId);
        if (sale == null) return;

        sale.Status = "voided";
        sale.VoidedAt = @event.VoidedAt;
        sale.VoidedBy = @event.VoidedBy;
        sale.VoidReason = @event.Reason;

        await db.SaveChangesAsync();
    }
}

L.4A.6 Temporal Queries

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

Event sourcing enables powerful temporal queries:

-- What was inventory on a specific date?
SELECT
    product_id,
    SUM(CASE
        WHEN event_type = 'InventoryReceived' THEN (event_data->>'quantity')::int
        WHEN event_type = 'InventorySold' THEN -(event_data->>'quantity')::int
        WHEN event_type = 'InventoryAdjusted' THEN (event_data->>'quantity_change')::int
        ELSE 0
    END) as quantity
FROM events
WHERE aggregate_type = 'Inventory'
  AND (event_data->>'location_id')::uuid = '...'
  AND created_at <= '2025-12-15 15:00:00'
GROUP BY product_id;

-- Sales trend for specific product
SELECT
    date_trunc('day', created_at) as date,
    SUM((event_data->>'quantity')::int) as units_sold
FROM events
WHERE event_type = 'InventorySold'
  AND (event_data->>'product_id')::uuid = '...'
  AND created_at >= NOW() - INTERVAL '30 days'
GROUP BY date_trunc('day', created_at)
ORDER BY date;

-- Audit trail for specific sale
SELECT
    event_type,
    event_data,
    created_at,
    created_by
FROM events
WHERE aggregate_type = 'Sale'
  AND aggregate_id = '...'
ORDER BY version;

L.4A.7 Snapshots for Performance

Detailed Implementation Reference (from former Event Sourcing & CQRS chapter, now consolidated here):

For aggregates with many events, snapshots prevent replaying the entire stream:

Snapshot Strategy
=================

Without Snapshots:
Event 1 -> Event 2 -> ... -> Event 5000 -> Current State
(Slow for aggregates with many events)

With Snapshots:
Event 1 -> ... -> Event 1000 -> [Snapshot @ v1000]
                                      |
                                      -> Event 1001 -> ... -> Event 1050 -> Current State
(Load snapshot, then only replay 50 events)

Snapshot Implementation

// AggregateRepository.cs

public class AggregateRepository<T> where T : AggregateRoot
{
    private readonly IEventStore _eventStore;
    private readonly ISnapshotStore _snapshotStore;
    private const int SNAPSHOT_THRESHOLD = 100;

    public async Task<T> LoadAsync(Guid id)
    {
        var aggregate = Activator.CreateInstance<T>();

        // 1. Try to load snapshot
        var snapshot = await _snapshotStore.GetAsync<T>(id);
        int fromVersion = 0;

        if (snapshot != null)
        {
            aggregate.RestoreFromSnapshot(snapshot.State);
            fromVersion = snapshot.Version;
        }

        // 2. Load events after snapshot
        var events = await _eventStore.GetEventsAsync(id, fromVersion);

        foreach (var @event in events)
        {
            aggregate.Apply(@event);
        }

        return aggregate;
    }

    public async Task SaveAsync(T aggregate)
    {
        var newEvents = aggregate.GetUncommittedEvents();

        // 1. Append events
        await _eventStore.AppendAsync(aggregate.Id, newEvents, aggregate.Version);

        // 2. Create snapshot if threshold reached
        if (aggregate.Version % SNAPSHOT_THRESHOLD == 0)
        {
            var snapshot = aggregate.CreateSnapshot();
            await _snapshotStore.SaveAsync(aggregate.Id, aggregate.Version, snapshot);
        }

        aggregate.ClearUncommittedEvents();
    }
}

L.4B Integration Architecture Patterns

BRD v18.0 Module 6 defines integration patterns that are architecturally significant. This section documents their implementation strategy.

Transactional Outbox Pattern

Guarantees atomic business data persistence + event publication without distributed transactions.

┌──────────────────────────────────────────────────────────┐
│             TRANSACTIONAL OUTBOX PATTERN                   │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  Application                    Outbox Relay              │
│  ┌─────────────────┐           ┌──────────────────┐      │
│  │ BEGIN TRANSACTION│           │ Poll outbox table│      │
│  │                  │           │ every 5 seconds  │      │
│  │ 1. Write to      │           └────────┬─────────┘      │
│  │    business table│                    │                │
│  │                  │                    ▼                │
│  │ 2. Write to      │           ┌──────────────────┐      │
│  │    outbox table  │           │ Publish event    │      │
│  │                  │           │ via LISTEN/NOTIFY│      │
│  │ COMMIT           │           └────────┬─────────┘      │
│  └─────────────────┘                    │                │
│                                          ▼                │
│                                 ┌──────────────────┐      │
│                                 │ Mark as published│      │
│                                 │ (idempotent)     │      │
│                                 └──────────────────┘      │
│                                                           │
└──────────────────────────────────────────────────────────┘

Provider Abstraction (Strategy Pattern)

┌──────────────────────────────────────────────────────────┐
│              PROVIDER ABSTRACTION PATTERN                  │
├──────────────────────────────────────────────────────────┤
│                                                           │
│              IIntegrationProvider                         │
│              ┌──────────────────┐                         │
│              │ + Connect()      │                         │
│              │ + SyncProducts() │                         │
│              │ + SyncInventory()│                         │
│              │ + ValidateData() │                         │
│              │ + HealthCheck()  │                         │
│              └────────┬─────────┘                         │
│                       │                                   │
│         ┌─────────────┼─────────────┐                    │
│         ▼             ▼             ▼                    │
│  ┌────────────┐┌────────────┐┌─────────────────┐        │
│  │  Shopify   ││  Amazon    ││  Google          │        │
│  │  Provider  ││  Provider  ││  Merchant        │        │
│  │            ││            ││  Provider        │        │
│  │ GraphQL    ││ REST/LWA   ││ REST/Service Acct│        │
│  │ 50pts/sec  ││ Burst+Tok  ││ Quota-based     │        │
│  │ Webhooks   ││ 2min Poll  ││ 2x/day Batch    │        │
│  └────────────┘└────────────┘└─────────────────┘        │
│                                                           │
└──────────────────────────────────────────────────────────┘

Safety Buffer Computation

Per BRD Section 6.7.2, channel-available quantity is calculated as:

Channel Available = POS Available - Safety Buffer

┌──────────────────────────────────────────────────────────┐
│            SAFETY BUFFER COMPUTATION                      │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  4-Level Priority Resolution:                            │
│  1. Product-Level Override (highest priority)            │
│  2. Category-Level Default                               │
│  3. Channel-Level Default                                │
│  4. Global Default (lowest priority)                     │
│                                                           │
│  3 Calculation Modes:                                    │
│  ┌──────────────────────────────────────────────────┐   │
│  │ FIXED:       Buffer = fixed_quantity              │   │
│  │ PERCENTAGE:  Buffer = pos_available * percentage  │   │
│  │ MIN_RESERVE: Buffer = pos_available - min_reserve │   │
│  └──────────────────────────────────────────────────┘   │
│                                                           │
│  Example (FIXED mode, buffer = 2):                       │
│  POS Available: 10 → Channel Available: 8                │
│                                                           │
│  Example (PERCENTAGE mode, 20%):                         │
│  POS Available: 10 → Buffer: 2 → Channel Available: 8   │
│                                                           │
└──────────────────────────────────────────────────────────┘

L.5 Architecture Documentation & Traceability

To ensure “soft architecture” matches the code and enables rapid root-cause analysis.

C4 Model Levels

+-------------------------------------------------------------------+
|                        C4 MODEL HIERARCHY                          |
+-------------------------------------------------------------------+
|                                                                    |
|  Level 1: System Context                                           |
|  +------------------+     +------------------+     +-------------+ |
|  |   POS Client     |<--->|   Central API    |<--->|   Shopify   | |
|  |   (Terminals)    |     |   (Cloud)        |     |   Amazon    | |
|  +------------------+     +------------------+     +-------------+ |
|                                                                    |
|  Level 2: Container Diagram                                        |
|  +------------------+     +------------------+     +-------------+ |
|  |   POS App        |     |   API Gateway    |     |   Kafka     | |
|  |   (SQLite)       |     |   Auth Service   |     |   Cluster   | |
|  +------------------+     |   Sales Module   |     +-------------+ |
|                           |   Inventory Mod  |     +-------------+ |
|                           +------------------+     |  PostgreSQL | |
|                                                    +-------------+ |
|                                                                    |
|  Level 3: Component Diagram (per module)                           |
|  Level 4: Code Diagram (class/sequence)                            |
|                                                                    |
+-------------------------------------------------------------------+

L.6 Quality Assurance (QA) & Testing Strategy

To ensure end-to-end reliability for financial transactions.

E2E (End-to-End) Testing

Example Test Flow:

1. Cashier authenticates with PIN
2. Scan barcode (NXJ1078)
3. Apply discount (if applicable)
4. Select payment method (Cash/Card)
5. Process payment
6. Print/email receipt
7. Verify inventory decremented
8. Verify event published to Kafka

Load Testing

Black Friday Scenario:

Concurrent Users: 500
Duration: 30 minutes
Target TPS: 1000 transactions/second
Acceptable Latency: p99 < 500ms

Code Management

L.7 Observability & Monitoring Strategy

Primary Pattern

Technology Stack (The “LGTM” Stack)

Instrumentation

L.8 Security & Compliance Strategy

Primary Pattern

6-Gate Security Test Pyramid

┌──────────────────────────────────────────────────────────┐
│             6-GATE SECURITY TEST PYRAMID                  │
├──────────────────────────────────────────────────────────┤
│                                                           │
│                      ┌─────────┐                         │
│                      │ Manual  │  Gate 6                  │
│                      │ Review  │  (Security-critical PRs) │
│                    ┌─┴─────────┴─┐                       │
│                    │  Contract   │  Gate 5                 │
│                    │  Tests      │  (Pact + Sandboxes)    │
│                  ┌─┴─────────────┴─┐                     │
│                  │  Architecture   │  Gate 4               │
│                  │  Conformance    │  (ArchUnit)          │
│                ┌─┴─────────────────┴─┐                   │
│                │  Secrets Detection  │  Gate 3             │
│                │  (GitLeaks)         │                    │
│              ┌─┴─────────────────────┴─┐                 │
│              │  SCA (Snyk + SBOM)      │  Gate 2          │
│            ┌─┴─────────────────────────┴─┐               │
│            │  SAST (SonarQube / CodeQL)  │  Gate 1        │
│            └─────────────────────────────┘               │
│                                                           │
└──────────────────────────────────────────────────────────┘

FIM (File Integrity Monitoring) - PCI Requirement

Credential Vault Architecture

Key Hierarchy:

Master Encryption Key (Vault auto-unseal)
└── Tenant-Specific Keys
    ├── tenant_nexus_key
    │   ├── Shopify OAuth tokens
    │   ├── Amazon LWA credentials
    │   ├── Google Service Account key
    │   ├── Payment processor tokens
    │   ├── SMTP credentials
    │   └── Webhook signing keys
    └── tenant_acme_key
        └── ... (same structure)

6 Credential Types:

Access Policy: Least privilege; application-role-based access. Integration services can only read their own provider credentials. Credential writes require admin role with MFA.

DevSecOps Pipeline

┌───────────────────────────────────────────────────────────────────┐
│                     DEVSECOPS PIPELINE (v2.0)                      │
├───────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Developer / Claude Code Agent                                     │
│       │                                                            │
│       ▼                                                            │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐                │
│  │ Pre-commit │──►│ Gate 1:    │──►│ Gate 2:    │                │
│  │ Hooks      │   │ SAST       │   │ SCA + SBOM │                │
│  └────────────┘   └────────────┘   └────────────┘                │
│                                          │                         │
│       ┌──────────────────────────────────┘                         │
│       ▼                                                            │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐                │
│  │ Gate 3:    │──►│ Gate 4:    │──►│ Gate 5:    │                │
│  │ Secrets    │   │ ArchUnit   │   │ Pact Tests │                │
│  └────────────┘   └────────────┘   └────────────┘                │
│                                          │                         │
│       ┌──────────────────────────────────┘                         │
│       ▼                                                            │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐                │
│  │ E2E Tests  │──►│ Gate 6:    │──►│ Deploy     │                │
│  │ (Cypress)  │   │ Manual     │   │ + Wazuh    │                │
│  └────────────┘   │ (if tagged)│   │ FIM        │                │
│                   └────────────┘   └────────────┘                │
│                                                                    │
└───────────────────────────────────────────────────────────────────┘

Offline Queue Security

POS terminals operating offline accumulate queued transactions that must be protected against tampering, interception, and replay attacks.

┌──────────────────────────────────────────────────────────┐
│              OFFLINE QUEUE SECURITY MODEL                  │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  Transaction Created (Offline)                            │
│       │                                                   │
│       ▼                                                   │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────┐  │
│  │ Serialize   │───►│ HMAC-SHA256  │───►│ AES-256    │  │
│  │ Transaction │    │ (Integrity)  │    │ Encrypt    │  │
│  └─────────────┘    └──────────────┘    └──────┬─────┘  │
│                                                 │        │
│                                                 ▼        │
│                                          ┌───────────┐   │
│                                          │  SQLite   │   │
│                                          │  Queue    │   │
│                                          └───────────┘   │
│                                                 │        │
│                     Network Restored            │        │
│                                                 ▼        │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────┐  │
│  │ Verify      │◄───│ Decrypt      │◄───│ Read from  │  │
│  │ HMAC + Seq  │    │ AES-256      │    │ Queue      │  │
│  └──────┬──────┘    └──────────────┘    └────────────┘  │
│         │                                                │
│         ▼                                                │
│  ┌─────────────┐                                        │
│  │ Sync to     │                                        │
│  │ Central API │                                        │
│  └─────────────┘                                        │
│                                                           │
└──────────────────────────────────────────────────────────┘

L.9 Diagrammatic Overview

System Architecture (Mermaid)

graph TD
    subgraph Client_Device ["POS Client"]
        UI[UI Layer]
        SL[Service Layer]
        DB_Local[(SQLite)]
        SL --> DB_Local
    end

    subgraph Cloud_Infrastructure ["Cloud Infrastructure"]
        LB[Load Balancer]
        subgraph Central_API ["Central API (Modular Monolith)"]
            Auth[Auth Module]
            Sales[Sales Module]
            Inv[Inventory Module]
        end
        subgraph Data_Layer ["Data Layer"]
            PG[(PostgreSQL)]
            Events[(PG Events)]
        end
    end

    subgraph DevOps_Pipeline ["DevSecOps & Traceability"]
        Git[GitHub - Semantic Ver]
        Struct[Structurizr - Docs]
        Sonar[SonarQube - SAST]
        Cypress[Cypress - E2E]
        Wazuh[Wazuh - FIM/PCI]
    end

    SL --> LB
    LB --> Auth
    Auth --> Sales
    Sales --> Events
    Sales --> PG

    Git --> Sonar
    Sonar --> Cypress
    Cypress --> Struct
    Wazuh -.-> Central_API
    Wazuh -.-> Client_Device

ASCII Version

+------------------------------------------------------------------+
|                    NEXUS POS ARCHITECTURE                         |
+------------------------------------------------------------------+
|                                                                   |
|  ┌─────────────────────────────────────────────────────────────┐ |
|  │                     POS CLIENT (STORE)                       │ |
|  │  ┌──────────┐    ┌──────────────┐    ┌──────────────────┐   │ |
|  │  │    UI    │───▶│ Service Layer│───▶│  SQLite (Local)  │   │ |
|  │  │  (MAUI)  │    │   (Plugins)  │    │  (Offline Data)  │   │ |
|  │  └──────────┘    └──────────────┘    └──────────────────┘   │ |
|  └──────────────────────────┬──────────────────────────────────┘ |
|                             │                                     |
|                             ▼ (Sync when online)                  |
|  ┌─────────────────────────────────────────────────────────────┐ |
|  │                   CLOUD INFRASTRUCTURE                       │ |
|  │                                                               │ |
|  │  ┌──────────────────────────────────────────────────────┐   │ |
|  │  │           CENTRAL API (Modular Monolith)              │   │ |
|  │  │  ┌────────┐  ┌────────┐  ┌──────────┐  ┌──────────┐  │   │ |
|  │  │  │  Auth  │  │ Sales  │  │Inventory │  │ Catalog  │  │   │ |
|  │  │  └────────┘  └────────┘  └──────────┘  └──────────┘  │   │ |
|  │  └──────────────────────┬───────────────────────────────┘   │ |
|  │                         │                                    │ |
|  │         ┌───────────────┼───────────────┐                   │ |
|  │         ▼               ▼               ▼                   │ |
|  │  ┌───────────┐   ┌───────────┐   ┌───────────────┐         │ |
|  │  │PostgreSQL │   │ HashiCorp │   │   External    │         │ |
|  │  │(Events +  │   │   Vault   │   │   Systems     │         │ |
|  │  │ State)    │   │(Secrets)  │   │(Shopify, etc.)│         │ |
|  │  └───────────┘   └───────────┘   └───────────────┘         │ |
|  └─────────────────────────────────────────────────────────────┘ |
|                                                                   |
+------------------------------------------------------------------+

L.9A System Architecture Reference

Detailed Implementation Reference (from former High-Level Architecture chapter, now consolidated here):

Complete System Architecture Diagram

+===========================================================================+
|                           CLOUD LAYER                                      |
|  +------------------+  +------------------+  +------------------+          |
|  |   Shopify API    |  | Payment Gateway  |  |   Tax Service    |          |
|  |  (E-commerce)    |  |  (Stripe/Square) |  |   (TaxJar)       |          |
|  +--------+---------+  +--------+---------+  +--------+---------+          |
|           |                     |                     |                    |
+===========|=====================|=====================|====================+
            |                     |                     |
            v                     v                     v
+===========================================================================+
|                         API GATEWAY LAYER                                  |
|  +---------------------------------------------------------------------+  |
|  |                      Kong / NGINX Gateway                            |  |
|  |  +-------------+  +-------------+  +-------------+  +-------------+  |  |
|  |  | Rate Limit  |  |    Auth     |  |   Routing   |  |   Logging   |  |  |
|  |  +-------------+  +-------------+  +-------------+  +-------------+  |  |
|  +---------------------------------------------------------------------+  |
+===========================================================================+
            |
            v
+===========================================================================+
|                       CENTRAL API LAYER                                    |
|                    (ASP.NET Core 8.0 / Node.js)                           |
|                                                                            |
|  +------------------+  +------------------+  +------------------+          |
|  |  Catalog Service |  |  Sales Service   |  |Inventory Service|          |
|  |                  |  |                  |  |                  |          |
|  | - Products       |  | - Transactions   |  | - Stock Levels   |          |
|  | - Categories     |  | - Receipts       |  | - Adjustments    |          |
|  | - Pricing        |  | - Refunds        |  | - Transfers      |          |
|  | - Variants       |  | - Layaways       |  | - Counts         |          |
|  +------------------+  +------------------+  +------------------+          |
|                                                                            |
|  +------------------+  +------------------+  +------------------+          |
|  |Customer Service  |  |Employee Service  |  |  Sync Service    |          |
|  |                  |  |                  |  |                  |          |
|  | - Profiles       |  | - Users          |  | - Shopify Sync   |          |
|  | - Loyalty        |  | - Roles          |  | - Offline Sync   |          |
|  | - History        |  | - Permissions    |  | - Event Queue    |          |
|  | - Credits        |  | - Shifts         |  | - Conflict Res   |          |
|  +------------------+  +------------------+  +------------------+          |
|                                                                            |
+===========================================================================+
            |
            v
+===========================================================================+
|                        DATA LAYER                                          |
|  +---------------------------------------------------------------------+  |
|  |                     PostgreSQL 16 Cluster                            |  |
|  |                                                                       |  |
|  |  +-----------------+  +-----------------+  +-----------------+        |  |
|  |  |  shared schema  |  | tenant_nexus    |  | tenant_acme     |        |  |
|  |  |  (platform)     |  | (Nexus Clothing)|  | (Acme Retail)   |        |  |
|  |  +-----------------+  +-----------------+  +-----------------+        |  |
|  |                                                                       |  |
|  +---------------------------------------------------------------------+  |
|  +------------------+  +------------------+                               |
|  |     Redis        |  |  Event Store     |                               |
|  |  (Cache/Queue)   |  |  (Append-Only)   |                               |
|  +------------------+  +------------------+                               |
+===========================================================================+

+===========================================================================+
|                      CLIENT APPLICATIONS                                   |
|                                                                            |
|  +------------------+  +------------------+  +------------------+          |
|  |    POS Client    |  |   Admin Portal   |  |  Raptag Mobile   |          |
|  |   (Desktop App)  |  |   (React SPA)    |  |  (.NET MAUI)     |          |
|  |                  |  |                  |  |                  |          |
|  | - Sales Terminal |  | - Dashboard      |  | - RFID Scanning  |          |
|  | - Offline Mode   |  | - Reports        |  | - Inventory      |          |
|  | - Local SQLite   |  | - Configuration  |  | - Quick Counts   |          |
|  | - Receipt Print  |  | - User Mgmt      |  | - Transfers      |          |
|  +------------------+  +------------------+  +------------------+          |
|                                                                            |
+===========================================================================+

Three-Tier Architecture Detail

Tier 1: Cloud Layer (External Services)

Cloud Integration Flow
======================

Shopify                Payment Gateway              Tax Service
   |                        |                           |
   | Products, Orders       | Authorization             | Rate Lookup
   | Inventory              | Capture                   | Calculation
   |                        | Refund                    |
   v                        v                           v
+----------------------------------------------------------------+
|                    Integration Adapters                         |
|  +---------------+  +------------------+  +------------------+  |
|  |ShopifyAdapter |  | PaymentAdapter   |  |  TaxAdapter      |  |
|  +---------------+  +------------------+  +------------------+  |
+----------------------------------------------------------------+
                              |
                              v
                    [Central API Services]

Tier 2: Central API Layer (Application Services)

API Gateway

Request Flow Through Gateway
============================

Client Request
      |
      v
+--------------------------------------------------+
|                  API GATEWAY                      |
|                                                   |
|  1. [Rate Limiting] -----> 100 req/min/client    |
|           |                                       |
|           v                                       |
|  2. [Authentication] ----> JWT Validation        |
|           |                                       |
|           v                                       |
|  3. [Tenant Resolution] -> Extract tenant_id     |
|           |                                       |
|           v                                       |
|  4. [Request Logging] ---> Correlation ID        |
|           |                                       |
|           v                                       |
|  5. [Route to Service] --> /api/v1/sales/*       |
|                                                   |
+--------------------------------------------------+
            |
            v
      Service Handler

Core Services

Tier 3: Data Layer (Persistence)

Data Layer Architecture
=======================

+------------------+     +------------------+     +------------------+
|   PostgreSQL     |     |      Redis       |     |   Event Store    |
|   (Primary DB)   |     |   (Cache/Queue)  |     | (Append-Only)    |
+------------------+     +------------------+     +------------------+
        |                        |                        |
        |                        |                        |
+-------v------------------------v------------------------v--------+
|                                                                   |
|   Schema: shared         Cache Keys           Events              |
|   +--------------+       +------------+       +-------------+     |
|   | tenants      |       | product:   |       | SaleCreated |     |
|   | plans        |       |   {id}     |       | ItemAdded   |     |
|   | features     |       | session:   |       | PaymentRcvd |     |
|   +--------------+       |   {token}  |       | StockAdj    |     |
|                          | inventory: |       +-------------+     |
|   Schema: tenant_xxx     |   {sku}    |                           |
|   +--------------+       +------------+                           |
|   | products     |                                                |
|   | sales        |                                                |
|   | inventory    |                                                |
|   | customers    |                                                |
|   +--------------+                                                |
|                                                                   |
+-------------------------------------------------------------------+

Client Applications

POS Client (Desktop)

POS Client Architecture
=======================

+-------------------------------------------------------------------+
|                      POS CLIENT (Electron/Tauri)                   |
|                                                                    |
|  +-----------------------+      +---------------------------+     |
|  |      UI Layer         |      |     Local Storage         |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  |  | Sales Screen   |   |      |  |   SQLite Database  |   |     |
|  |  +----------------+   |      |  |                    |   |     |
|  |  | Product Grid   |   |      |  | - products_cache   |   |     |
|  |  +----------------+   |      |  | - pending_sales    |   |     |
|  |  | Cart Panel     |   |      |  | - sync_queue       |   |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  |  | Payment Dialog |   |      |                           |     |
|  |  +----------------+   |      +---------------------------+     |
|  +-----------------------+                                        |
|                                                                    |
|  +-----------------------+      +---------------------------+     |
|  |    Service Layer      |      |    Hardware Layer         |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  |  | SaleService    |   |      |  | Receipt Printer    |   |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  |  | SyncService    |   |      |  | Barcode Scanner    |   |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  |  | OfflineService |   |      |  | Cash Drawer        |   |     |
|  |  +----------------+   |      |  +--------------------+   |     |
|  +-----------------------+      |  | Card Reader        |   |     |
|                                 |  +--------------------+   |     |
|                                 +---------------------------+     |
+-------------------------------------------------------------------+

Admin Portal (Web)

Admin Portal Architecture
=========================

+-------------------------------------------------------------------+
|                    ADMIN PORTAL (React SPA)                        |
|                                                                    |
|  +------------------------+    +---------------------------+      |
|  |     Navigation         |    |      Main Content         |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Dashboard        |  |    |  | Dashboard View      |  |      |
|  |  +------------------+  |    |  |   - KPIs            |  |      |
|  |  | Products         |  |    |  |   - Charts          |  |      |
|  |  +------------------+  |    |  |   - Alerts          |  |      |
|  |  | Sales            |  |    |  +---------------------+  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Inventory        |  |    |  | Product Manager     |  |      |
|  |  +------------------+  |    |  |   - CRUD            |  |      |
|  |  | Customers        |  |    |  |   - Bulk Import     |  |      |
|  |  +------------------+  |    |  |   - Sync Status     |  |      |
|  |  | Employees        |  |    |  +---------------------+  |      |
|  |  +------------------+  |    |                           |      |
|  |  | Reports          |  |    |                           |      |
|  |  +------------------+  |    |                           |      |
|  |  | Settings         |  |    |                           |      |
|  |  +------------------+  |    |                           |      |
|  +------------------------+    +---------------------------+      |
|                                                                    |
|  State Management: React Query + Context                           |
|  Routing: React Router                                             |
|  UI Framework: TailwindCSS                                         |
+-------------------------------------------------------------------+

Raptag Mobile (RFID)

Raptag Mobile Architecture
==========================

+-------------------------------------------------------------------+
|                   RAPTAG MOBILE (.NET MAUI)                        |
|                                                                    |
|  +------------------------+    +---------------------------+      |
|  |      RFID Layer        |    |       UI Layer            |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Zebra SDK        |  |    |  | Scan Screen         |  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Tag Parser       |  |    |  | Inventory Count     |  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Batch Processor  |  |    |  | Transfer Screen     |  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  +------------------------+    +---------------------------+      |
|                                                                    |
|  +------------------------+    +---------------------------+      |
|  |    Local Storage       |    |     API Client            |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | SQLite           |  |    |  | HTTP Client         |  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  |  | Scan Buffer      |  |    |  | Offline Queue       |  |      |
|  |  +------------------+  |    |  +---------------------+  |      |
|  +------------------------+    +---------------------------+      |
+-------------------------------------------------------------------+

Service Boundaries

Service Boundary Diagram
========================

+-------------------+      +-------------------+      +-------------------+
|  Catalog Service  |      |   Sales Service   |      |Inventory Service  |
|                   |      |                   |      |                   |
| OWNS:             |      | OWNS:             |      | OWNS:             |
| - products        |      | - sales           |      | - inventory_items |
| - categories      |      | - line_items      |      | - stock_levels    |
| - pricing_rules   |      | - payments        |      | - adjustments     |
| - product_variants|      | - refunds         |      | - transfers       |
| - product_images  |      | - holds           |      | - count_sessions  |
|                   |      |                   |      |                   |
| REFERENCES:       |      | REFERENCES:       |      | REFERENCES:       |
| (none)            |      | - product_id      |      | - product_id      |
|                   |      | - customer_id     |      | - location_id     |
|                   |      | - employee_id     |      |                   |
+-------------------+      +-------------------+      +-------------------+

+-------------------+      +-------------------+
| Customer Service  |      | Employee Service  |
|                   |      |                   |
| OWNS:             |      | OWNS:             |
| - customers       |      | - employees       |
| - loyalty_cards   |      | - roles           |
| - store_credits   |      | - permissions     |
| - addresses       |      | - shifts          |
|                   |      | - time_entries    |
| REFERENCES:       |      |                   |
| (none)            |      | REFERENCES:       |
|                   |      | - location_id     |
+-------------------+      +-------------------+

Technology Stack Summary

Deployment Topology

Production Deployment
=====================

                        +------------------+
                        |   Load Balancer  |
                        |   (HAProxy/ALB)  |
                        +--------+---------+
                                 |
          +----------------------+----------------------+
          |                      |                      |
+---------v--------+   +---------v--------+   +---------v--------+
|   API Server 1   |   |   API Server 2   |   |   API Server 3   |
|                  |   |                  |   |                  |
|  - Central API   |   |  - Central API   |   |  - Central API   |
|  - Stateless     |   |  - Stateless     |   |  - Stateless     |
+--------+---------+   +---------+--------+   +---------+--------+
         |                       |                      |
         +----------+------------+-----------+----------+
                    |                        |
          +---------v--------+     +---------v--------+
          |   PostgreSQL     |     |      Redis       |
          |   (Primary)      |     |   (Cluster)      |
          +--------+---------+     +------------------+
                   |
          +--------v---------+
          |   PostgreSQL     |
          |   (Replica)      |
          +------------------+

Store Locations (5 stores):
+----------------+   +----------------+   +----------------+
| GM Store       |   | HM Store       |   | LM Store       |
| +------------+ |   | +------------+ |   | +------------+ |
| |POS Client 1| |   | |POS Client 1| |   | |POS Client 1| |
| +------------+ |   | +------------+ |   | +------------+ |
| |POS Client 2| |   | +------------+ |   +----------------+
| +------------+ |   | |POS Client 2| |
+----------------+   | +------------+ |
                     +----------------+

Security Architecture

Security Layers
===============

+------------------------------------------------------------------+
|                        INTERNET                                   |
+---------------------------+--------------------------------------+
                            |
                            v
+---------------------------+--------------------------------------+
|                    TLS TERMINATION                                |
|                    (Let's Encrypt)                                |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    API GATEWAY                                    |
|  +-----------------------+  +-----------------------+             |
|  | Rate Limiting         |  | IP Whitelisting       |             |
|  | 100 req/min/client    |  | (Admin Portal only)   |             |
|  +-----------------------+  +-----------------------+             |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    AUTHENTICATION                                 |
|  +-----------------------+  +-----------------------+             |
|  | JWT Validation        |  | PIN Verification      |             |
|  | - Signature check     |  | - Employee clock-in   |             |
|  | - Expiry check        |  | - Sensitive actions   |             |
|  | - Tenant claim        |  +-----------------------+             |
|  +-----------------------+                                        |
+---------------------------+--------------------------------------+
                            |
                            v
+------------------------------------------------------------------+
|                    AUTHORIZATION                                  |
|  +-----------------------+  +-----------------------+             |
|  | Role-Based (RBAC)     |  | Permission Policies   |             |
|  | - Admin               |  | - can:create_sale     |             |
|  | - Manager             |  | - can:void_sale       |             |
|  | - Cashier             |  | - can:view_reports    |             |
|  +-----------------------+  +-----------------------+             |
+------------------------------------------------------------------+

L.9B Data Flow Reference

Detailed Implementation Reference (from former High-Level Architecture chapter, now consolidated here):

Pattern 1: Online Sale Flow

Online Sale Flow
================

[POS Client]                    [Central API]                   [Database]
     |                               |                               |
     | 1. POST /sales                |                               |
     |------------------------------>|                               |
     |                               | 2. Validate request           |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 3. Begin transaction          |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 4. Create sale record         |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 5. Decrement inventory        |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 6. Log sale event             |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 7. Commit transaction         |
     |                               |------------------------------>|
     |                               |                               |
     | 8. Return sale confirmation   |                               |
     |<------------------------------|                               |
     |                               |                               |
     | 9. Print receipt              |                               |
     |                               |                               |

Pattern 2: Offline Sale Flow

Offline Sale Flow
=================

[POS Client]                    [Local SQLite]                  [Sync Queue]
     |                               |                               |
     | 1. Create sale locally        |                               |
     |------------------------------>|                               |
     |                               | 2. Generate local UUID        |
     |                               |                               |
     | 3. Decrement local inventory  |                               |
     |------------------------------>|                               |
     |                               |                               |
     | 4. Queue for sync             |                               |
     |-------------------------------------------------------------->|
     |                               |                               |
     | 5. Print receipt              |                               |
     |                               |                               |

--- Later, when online ---

[Sync Service]                  [Central API]                   [Database]
     |                               |                               |
     | 1. Pop from queue             |                               |
     |                               |                               |
     | 2. POST /sync/sales           |                               |
     |------------------------------>|                               |
     |                               | 3. Validate (check for dupe)  |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 4. Insert with local UUID     |
     |                               |------------------------------>|
     |                               |                               |
     | 5. Mark synced                |                               |
     |<------------------------------|                               |

Pattern 3: Inventory Sync Flow

Inventory Sync from Shopify
===========================

[Shopify]                      [Webhook Handler]               [Inventory Svc]
     |                               |                               |
     | 1. inventory_levels/update    |                               |
     |------------------------------>|                               |
     |                               | 2. Validate webhook           |
     |                               |                               |
     |                               | 3. Parse inventory update     |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 4. Update stock level         |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 5. Log inventory event        |
     |                               |------------------------------>|
     |                               |                               |
     |                               | 6. Broadcast to POS clients   |
     |                               |------------------------------>|
     |                               |           (SignalR)           |

L.9C Domain Model Reference

Domain Model Overview (from former Domain Model chapter, now consolidated here): NOTE: Only bounded contexts, aggregates, and ER diagram included here. Detailed entity field definitions are in Part III Database chapters.

Bounded Contexts Overview

Domain Bounded Contexts
=======================

+------------------------------------------------------------------+
|                         POS PLATFORM                              |
|                                                                   |
|  +-------------+  +-------------+  +-------------+               |
|  |   CATALOG   |  |    SALES    |  | INVENTORY   |               |
|  |             |  |             |  |             |               |
|  | Products    |  | Sales       |  | StockLevels |               |
|  | Variants    |  | LineItems   |  | Adjustments |               |
|  | Categories  |  | Payments    |  | Transfers   |               |
|  | Pricing     |  | Refunds     |  | Counts      |               |
|  +-------------+  +-------------+  +-------------+               |
|                                                                   |
|  +-------------+  +-------------+  +-------------+               |
|  |  CUSTOMER   |  |  EMPLOYEE   |  |  LOCATION   |               |
|  |             |  |             |  |             |               |
|  | Customers   |  | Employees   |  | Locations   |               |
|  | Addresses   |  | Roles       |  | Registers   |               |
|  | Loyalty     |  | Permissions |  | Settings    |               |
|  | Credits     |  | Shifts      |  | TaxRates    |               |
|  +-------------+  +-------------+  +-------------+               |
|                                                                   |
+------------------------------------------------------------------+

Context Summary Table

Entity Relationship Diagram

Entity Relationships
====================

                                 +----------+
                                 | Category |
                                 +----+-----+
                                      |
                                      | 1:N
                                      v
+----------+     1:N      +----------+     1:N      +----------------+
| Location |<-------------| Product  |------------->| ProductVariant |
+----+-----+              +----+-----+              +-------+--------+
     |                         |                            |
     |                         |                            |
     | 1:N                     |                            |
     v                         |                            |
+----------+                   |                            |
| Register |                   v                            v
+----+-----+              +----------+              +----------------+
     |                    |Inventory |              |  Adjustment    |
     |                    |   Item   |              |     Item       |
     | 1:N                +----------+              +----------------+
     v
+----------+
|CashDrawer|
+----------+


+----------+     1:N      +----------+     1:N      +----------+
| Customer |------------->|   Sale   |------------->| LineItem |
+----+-----+              +----+-----+              +----------+
     |                         |
     |                         | 1:N
     | 1:N                     v
     v                    +----------+
+----------+              | Payment  |
|  Credit  |              +----------+
+----------+


+----------+     N:1      +----------+     1:N      +----------+
| Employee |------------->|   Role   |------------->|Permission|
+----+-----+              +----------+              +----------+
     |
     | 1:N
     v
+----------+
|  Shift   |
+----------+

Aggregate Boundaries

Each aggregate has a root entity and encapsulates related entities:

Aggregate Definitions
=====================

SALE Aggregate
+------------------------------------------+
| Sale (Root)                              |
|   +-- SaleLineItem[] (owned)             |
|   +-- Payment[] (owned)                  |
|   +-- Refund[] (reference: sale_id)      |
+------------------------------------------+

INVENTORY_ADJUSTMENT Aggregate
+------------------------------------------+
| InventoryAdjustment (Root)               |
|   +-- InventoryAdjustmentItem[] (owned)  |
+------------------------------------------+

INVENTORY_TRANSFER Aggregate
+------------------------------------------+
| InventoryTransfer (Root)                 |
|   +-- InventoryTransferItem[] (owned)    |
+------------------------------------------+

CUSTOMER Aggregate
+------------------------------------------+
| Customer (Root)                          |
|   +-- CustomerAddress[] (owned)          |
|   +-- StoreCredit[] (reference)          |
|   +-- LoyaltyTransaction[] (reference)   |
+------------------------------------------+

PRODUCT Aggregate
+------------------------------------------+
| Product (Root)                           |
|   +-- ProductVariant[] (owned)           |
+------------------------------------------+

L.10 Risks & Mitigations

L.10A Key Architecture Decisions (BRD-v12)

This section documents critical architecture decisions derived from BRD-v12 requirements analysis. Each decision follows the Architecture Decision Record (ADR) format.

L.10A.1 Offline Strategy Decision

Implementation Configuration:

offline_mode:
  max_queue_size: 100
  sync_interval_seconds: 30
  conflict_strategy: "server_wins_with_review"

  # Operations ALLOWED offline
  allowed_offline:
    - sale_new
    - return_with_receipt
    - price_check
    - parked_sale_create
    - parked_sale_retrieve

  # Operations BLOCKED offline (too risky)
  blocked_offline:
    - customer_create        # Requires uniqueness check
    - credit_limit_check     # Requires real-time balance
    - on_account_payment     # Risk of exceeding limit
    - multi_store_inventory  # Requires network
    - gift_card_activation   # Must register immediately
    - gift_card_reload       # Risk of double-load
    - transfer_request       # Requires other store
    - reservation_create     # Requires other store

Conflict Resolution Strategy:

┌─────────────────────────────────────────────────────────────┐
│                  OFFLINE SYNC WORKFLOW                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Network Lost         Network Restored      Conflict?        │
│       │                     │                   │            │
│       ▼                     ▼                   ▼            │
│  ┌─────────┐          ┌─────────┐         ┌─────────┐       │
│  │ Queue   │─────────►│  Sync   │────────►│ Review  │       │
│  │ Locally │          │ to API  │         │ Manager │       │
│  └─────────┘          └─────────┘         └─────────┘       │
│       │                     │                   │            │
│  Max 100 txns          30-second          Server wins       │
│                        interval            with flag        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

L.10A.1A POS Client Architecture

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

POS Client Architecture
=======================

+-----------------------------------------------------------------------+
|                           POS CLIENT                                   |
|                                                                        |
|  +------------------------+        +-------------------------------+  |
|  |      Presentation      |        |        Local Storage          |  |
|  |                        |        |                               |  |
|  |  +------------------+  |        |  +-------------------------+  |  |
|  |  |   Sales Screen   |  |        |  |      SQLite Database     |  |  |
|  |  +------------------+  |        |  |                         |  |  |
|  |  |  Product Grid    |  |        |  | +---------------------+ |  |  |
|  |  +------------------+  |        |  | | products_cache      | |  |  |
|  |  |   Cart Panel     |  |        |  | +---------------------+ |  |  |
|  |  +------------------+  |        |  | | pending_sales       | |  |  |
|  |  |  Payment Dialog  |  |        |  | +---------------------+ |  |  |
|  |  +------------------+  |        |  | | sync_queue          | |  |  |
|  |  |  Receipt Print   |  |        |  | +---------------------+ |  |  |
|  |  +------------------+  |        |  | | events (local)      | |  |  |
|  +------------------------+        |  | +---------------------+ |  |  |
|             |                      |  | | customer_cache      | |  |  |
|             v                      |  | +---------------------+ |  |  |
|  +------------------------+        |  +-------------------------+  |  |
|  |   Application Layer    |        |                               |  |
|  |                        |        +-------------------------------+  |
|  |  +------------------+  |                      ^                    |
|  |  |   SaleService    |------------------------>|                    |
|  |  +------------------+  |                      |                    |
|  |  | InventoryService |------------------------>|                    |
|  |  +------------------+  |                      |                    |
|  |  | CustomerService  |------------------------>|                    |
|  |  +------------------+  |                                           |
|  +------------------------+                                           |
|             |                                                         |
|             v                                                         |
|  +------------------------+        +-------------------------------+  |
|  |     Sync Service       |        |     Connection Monitor        |  |
|  |                        |        |                               |  |
|  |  - Queue Manager       |<------>|  - Ping Central API           |  |
|  |  - Conflict Resolver   |        |  - Track online/offline       |  |
|  |  - Retry Handler       |        |  - Trigger sync when online   |  |
|  |  - Batch Uploader      |        |                               |  |
|  +------------------------+        +-------------------------------+  |
|             |                                                         |
+-------------|----------------------------------------------------------+
              |
              v (when online)
+-----------------------------------------------------------------------+
|                          CENTRAL API                                   |
+-----------------------------------------------------------------------+

L.10A.1B Local Database Schema (SQLite)

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

-- SQLite Schema for POS Client

-- Product cache (synced from server)
CREATE TABLE products_cache (
    id              TEXT PRIMARY KEY,
    sku             TEXT UNIQUE NOT NULL,
    barcode         TEXT,
    name            TEXT NOT NULL,
    category_name   TEXT,
    price           REAL NOT NULL,
    cost            REAL,
    tax_code        TEXT,
    is_taxable      INTEGER DEFAULT 1,
    track_inventory INTEGER DEFAULT 1,
    image_url       TEXT,
    variants_json   TEXT,              -- JSON array of variants
    synced_at       TEXT NOT NULL,     -- When last synced from server
    created_at      TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_products_barcode ON products_cache(barcode);
CREATE INDEX idx_products_name ON products_cache(name);

-- Inventory cache (synced from server)
CREATE TABLE inventory_cache (
    product_id      TEXT NOT NULL,
    variant_id      TEXT,
    location_id     TEXT NOT NULL,
    quantity        INTEGER NOT NULL,
    synced_at       TEXT NOT NULL,
    PRIMARY KEY (product_id, variant_id, location_id)
);

-- Customer cache (synced from server)
CREATE TABLE customers_cache (
    id              TEXT PRIMARY KEY,
    customer_number TEXT UNIQUE,
    first_name      TEXT,
    last_name       TEXT,
    email           TEXT,
    phone           TEXT,
    loyalty_points  INTEGER DEFAULT 0,
    store_credit    REAL DEFAULT 0,
    synced_at       TEXT NOT NULL
);

-- Local sales (created offline, pending sync)
CREATE TABLE local_sales (
    id              TEXT PRIMARY KEY,
    sale_number     TEXT UNIQUE NOT NULL,
    location_id     TEXT NOT NULL,
    register_id     TEXT NOT NULL,
    employee_id     TEXT NOT NULL,
    customer_id     TEXT,
    status          TEXT DEFAULT 'completed',
    subtotal        REAL NOT NULL,
    discount_total  REAL DEFAULT 0,
    tax_total       REAL DEFAULT 0,
    total           REAL NOT NULL,
    line_items_json TEXT NOT NULL,     -- JSON array of line items
    payments_json   TEXT NOT NULL,     -- JSON array of payments
    created_at      TEXT DEFAULT (datetime('now')),
    synced_at       TEXT              -- NULL until synced
);

CREATE INDEX idx_local_sales_synced ON local_sales(synced_at);

-- Event queue (append-only, sync to server)
CREATE TABLE event_queue (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    event_id        TEXT UNIQUE NOT NULL,
    aggregate_type  TEXT NOT NULL,
    aggregate_id    TEXT NOT NULL,
    event_type      TEXT NOT NULL,
    event_data      TEXT NOT NULL,     -- JSON
    created_at      TEXT NOT NULL,
    created_by      TEXT,
    synced_at       TEXT,              -- NULL until synced
    sync_attempts   INTEGER DEFAULT 0,
    last_error      TEXT
);

CREATE INDEX idx_event_queue_pending ON event_queue(synced_at) WHERE synced_at IS NULL;

-- Sync metadata
CREATE TABLE sync_status (
    key             TEXT PRIMARY KEY,
    value           TEXT NOT NULL,
    updated_at      TEXT DEFAULT (datetime('now'))
);

-- Track what we've synced
INSERT INTO sync_status (key, value) VALUES
    ('last_product_sync', '1970-01-01T00:00:00Z'),
    ('last_inventory_sync', '1970-01-01T00:00:00Z'),
    ('last_customer_sync', '1970-01-01T00:00:00Z'),
    ('last_event_push', '1970-01-01T00:00:00Z');

L.10A.1C Sync Queue Design

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

Sync Queue Architecture
=======================

+-------------------+     +-------------------+     +-------------------+
|   Sale Created    |     |  Inventory Adj    |     | Customer Created  |
|   (Offline)       |     |  (Offline)        |     | (Offline)         |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                         |
         v                         v                         v
+-----------------------------------------------------------------------+
|                          SYNC QUEUE                                    |
|                                                                        |
|  Priority  | Type              | Status    | Retries | Last Error     |
|  ---------------------------------------------------------------      |
|  1         | SaleCreated       | pending   | 0       |                |
|  1         | PaymentReceived   | pending   | 0       |                |
|  2         | InventoryAdjusted | pending   | 0       |                |
|  3         | CustomerCreated   | failed    | 3       | Timeout        |
|  1         | SaleCompleted     | pending   | 0       |                |
|                                                                        |
|  Priority Legend:                                                      |
|  1 = Critical (sales, payments) - sync immediately                    |
|  2 = Important (inventory) - sync within minutes                      |
|  3 = Normal (customers) - sync when convenient                        |
+-----------------------------------------------------------------------+
              |
              | Sync Processor (runs when online)
              v
+-----------------------------------------------------------------------+
|                          CENTRAL API                                   |
|                                                                        |
|  POST /api/sync/events                                                |
|  [                                                                     |
|    { eventType: "SaleCreated", ... },                                 |
|    { eventType: "PaymentReceived", ... },                             |
|    ...                                                                 |
|  ]                                                                     |
|                                                                        |
|  Response: { synced: 5, conflicts: 0, errors: [] }                    |
+-----------------------------------------------------------------------+

Sync Priority Rules

L.10A.1D Conflict Resolution Strategies

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

Conflict Resolution Matrix
==========================

+------------------+---------------------+--------------------------------+
| Data Type        | Strategy            | Reasoning                      |
+------------------+---------------------+--------------------------------+
| Sales            | Append-Only         | Each sale is unique, no        |
|                  | (No Conflicts)      | conflicts possible             |
+------------------+---------------------+--------------------------------+
| Inventory        | Last-Write-Wins     | Central server is authority,   |
|                  | (Server Wins)       | client updates are suggestions |
+------------------+---------------------+--------------------------------+
| Customers        | Merge on Key        | Merge by email, combine        |
|                  | (Email = Key)       | non-conflicting fields         |
+------------------+---------------------+--------------------------------+
| Products         | Server Authority    | Product catalog managed        |
|                  | (Read-Only Client)  | centrally, client is cache     |
+------------------+---------------------+--------------------------------+
| Employees        | Server Authority    | HR data managed centrally      |
|                  | (Read-Only Client)  |                                |
+------------------+---------------------+--------------------------------+
| Settings         | Server Authority    | Config managed by admin        |
|                  | (Read-Only Client)  |                                |
+------------------+---------------------+--------------------------------+

Strategy 1: Append-Only (Sales)

Sale Conflict Resolution: None Required
========================================

Client A (Offline):                  Client B (Offline):
  Sale S-001 created @ 10:15           Sale S-002 created @ 10:16
  LineItem: Product X, Qty 2           LineItem: Product Y, Qty 1
  Payment: $50 cash                    Payment: $25 credit

When both sync:
  Server: Accepts S-001 (unique ID)
  Server: Accepts S-002 (unique ID)
  Result: Both sales recorded, no conflict

Strategy 2: Last-Write-Wins (Inventory)

Inventory Conflict Resolution: Server Authority
===============================================

Server State:
  Product X @ Location HQ: 100 units

Client A (Offline):                  Client B (Offline):
  Sells 5 units of Product X           Sells 3 units of Product X
  Local: 95 units                      Local: 97 units

When both sync:
  Server receives: "Sold 5 units" from A
  Server receives: "Sold 3 units" from B
  Server calculates: 100 - 5 - 3 = 92 units
  Server pushes new quantity to all clients

Result:
  All clients update to 92 units
  Individual decrements preserved
  No quantity lost or duplicated

Strategy 3: Merge on Key (Customers)

Customer Conflict Resolution: Merge
===================================

Server State:
  Customer email: john@example.com
  Name: John Doe
  Phone: (blank)
  Loyalty: 500 points

Client A (Offline):                  Client B (Offline):
  Updates phone to 555-1234            Updates loyalty to 600 points

When both sync:
  Server merges non-conflicting fields:
    Name: John Doe (unchanged)
    Phone: 555-1234 (from A)
    Loyalty: 600 points (from B)

If same field changed:
  Server uses timestamp to pick latest
  Or prompts admin for resolution

L.10A.1E Sync Processor Workflow

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

Sync Processor State Machine
============================

                    +-------------+
                    |    IDLE     |
                    +------+------+
                           |
                           | Connection detected
                           v
                    +-------------+
                    |   SYNCING   |
                    +------+------+
                           |
        +------------------+------------------+
        |                  |                  |
        v                  v                  v
+-------------+    +-------------+    +-------------+
| PUSH EVENTS |    | PULL DATA   |    |  COMPLETE   |
|             |    |             |    |             |
| - Sales     |    | - Products  |    | - Update    |
| - Payments  |    | - Inventory |    |   metadata  |
| - Inventory |    | - Customers |    | - Return    |
|   changes   |    | - Settings  |    |   to IDLE   |
+------+------+    +------+------+    +-------------+
       |                  |
       +------------------+
                |
                v
        +-------------+
        | HANDLE      |
        | CONFLICTS   |
        +------+------+
               |
               v
        +-------------+
        |  COMPLETE   |
        +-------------+

Sync Service Implementation

// SyncService.cs

public class SyncService : IHostedService
{
    private readonly ILocalDatabase _localDb;
    private readonly IApiClient _apiClient;
    private readonly IConnectionMonitor _connectionMonitor;
    private readonly IConflictResolver _conflictResolver;
    private readonly ILogger<SyncService> _logger;

    private Timer? _syncTimer;
    private bool _isSyncing = false;

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        _connectionMonitor.OnlineStatusChanged += HandleConnectionChange;

        // Check for pending sync every 30 seconds
        _syncTimer = new Timer(
            async _ => await TrySyncAsync(),
            null,
            TimeSpan.Zero,
            TimeSpan.FromSeconds(30)
        );
    }

    private async void HandleConnectionChange(object? sender, bool isOnline)
    {
        if (isOnline)
        {
            _logger.LogInformation("Connection restored, starting sync");
            await TrySyncAsync();
        }
    }

    private async Task TrySyncAsync()
    {
        if (_isSyncing) return;
        if (!_connectionMonitor.IsOnline) return;

        _isSyncing = true;
        try
        {
            // 1. Push local events to server
            await PushEventsAsync();

            // 2. Pull updated data from server
            await PullProductsAsync();
            await PullInventoryAsync();
            await PullCustomersAsync();

            // 3. Update sync timestamps
            await UpdateSyncMetadataAsync();

            _logger.LogInformation("Sync completed successfully");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Sync failed");
        }
        finally
        {
            _isSyncing = false;
        }
    }

    private async Task PushEventsAsync()
    {
        // Get pending events ordered by priority
        var pendingEvents = await _localDb.GetPendingEventsAsync();

        if (!pendingEvents.Any()) return;

        // Batch events (max 100 per request)
        var batches = pendingEvents.Chunk(100);

        foreach (var batch in batches)
        {
            try
            {
                var response = await _apiClient.PostEventsAsync(batch);

                // Mark synced events
                foreach (var evt in response.Synced)
                {
                    await _localDb.MarkEventSyncedAsync(evt.EventId);
                }

                // Handle conflicts
                foreach (var conflict in response.Conflicts)
                {
                    await _conflictResolver.ResolveAsync(conflict);
                }
            }
            catch (HttpRequestException)
            {
                // Network error, increment retry count
                foreach (var evt in batch)
                {
                    await _localDb.IncrementEventRetryAsync(evt.EventId);
                }
                throw;
            }
        }
    }

    private async Task PullProductsAsync()
    {
        var lastSync = await _localDb.GetSyncTimestampAsync("products");
        var products = await _apiClient.GetProductsUpdatedSinceAsync(lastSync);

        foreach (var product in products)
        {
            await _localDb.UpsertProductCacheAsync(product);
        }
    }

    private async Task PullInventoryAsync()
    {
        var locationId = await GetCurrentLocationIdAsync();
        var lastSync = await _localDb.GetSyncTimestampAsync("inventory");
        var inventory = await _apiClient.GetInventoryUpdatedSinceAsync(locationId, lastSync);

        foreach (var item in inventory)
        {
            // Apply server's quantity (server is authority)
            await _localDb.UpdateInventoryCacheAsync(item);
        }
    }
}

L.10A.1F Sale Creation Flow (Offline-Capable)

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

Offline Sale Flow
=================

1. Cashier scans items
   +----------------+
   | Local Lookup   |
   | products_cache |
   +----------------+
         |
         v
2. Add to cart (no network needed)
   +----------------+
   | In-Memory Cart |
   +----------------+
         |
         v
3. Customer pays
   +----------------+
   | Payment Dialog |
   | (card or cash) |
   +----------------+
         |
         v
4. Save sale locally
   +----------------+
   | local_sales    |
   | (SQLite)       |
   +----------------+
         |
         v
5. Queue sync events
   +----------------+
   | event_queue    |
   | SaleCreated    |
   | ItemAdded x N  |
   | PaymentRcvd    |
   | SaleCompleted  |
   +----------------+
         |
         v
6. Decrement local inventory
   +----------------+
   | inventory_cache|
   | (optimistic)   |
   +----------------+
         |
         v
7. Print receipt
   +----------------+
   | Receipt ready  |
   | (no waiting)   |
   +----------------+
         |
         v
8. Background sync (when online)
   +----------------+
   | SyncService    |
   | pushes events  |
   +----------------+

Sale Service Implementation

// SaleService.cs

public class SaleService
{
    private readonly ILocalDatabase _localDb;
    private readonly IEventQueue _eventQueue;
    private readonly IReceiptPrinter _printer;

    public async Task<Sale> CompleteSaleAsync(Cart cart, List<Payment> payments)
    {
        // 1. Generate local IDs
        var saleId = Guid.NewGuid();
        var saleNumber = GenerateSaleNumber();

        // 2. Create sale record
        var sale = new Sale
        {
            Id = saleId,
            SaleNumber = saleNumber,
            LocationId = GetCurrentLocationId(),
            RegisterId = GetCurrentRegisterId(),
            EmployeeId = GetCurrentEmployeeId(),
            CustomerId = cart.CustomerId,
            Status = "completed",
            Subtotal = cart.Subtotal,
            DiscountTotal = cart.DiscountTotal,
            TaxTotal = cart.TaxTotal,
            Total = cart.Total,
            LineItems = cart.Items.Select(MapToLineItem).ToList(),
            Payments = payments,
            CreatedAt = DateTime.UtcNow
        };

        // 3. Save to local database
        await _localDb.InsertSaleAsync(sale);

        // 4. Queue events for sync
        await _eventQueue.EnqueueAsync(new SaleCreated
        {
            SaleId = saleId,
            SaleNumber = saleNumber,
            LocationId = sale.LocationId,
            EmployeeId = sale.EmployeeId,
            CustomerId = sale.CustomerId,
            CreatedAt = sale.CreatedAt
        });

        foreach (var item in sale.LineItems)
        {
            await _eventQueue.EnqueueAsync(new SaleLineItemAdded
            {
                SaleId = saleId,
                LineItemId = item.Id,
                ProductId = item.ProductId,
                Sku = item.Sku,
                Name = item.Name,
                Quantity = item.Quantity,
                UnitPrice = item.UnitPrice
            });

            // 5. Decrement local inventory (optimistic)
            await _localDb.DecrementInventoryAsync(
                item.ProductId,
                item.VariantId,
                sale.LocationId,
                item.Quantity
            );
        }

        foreach (var payment in payments)
        {
            await _eventQueue.EnqueueAsync(new PaymentReceived
            {
                SaleId = saleId,
                PaymentId = payment.Id,
                PaymentMethod = payment.Method,
                Amount = payment.Amount
            });
        }

        await _eventQueue.EnqueueAsync(new SaleCompleted
        {
            SaleId = saleId,
            Total = sale.Total,
            CompletedAt = DateTime.UtcNow
        });

        // 6. Print receipt (async, don't wait)
        _ = _printer.PrintReceiptAsync(sale);

        return sale;
    }

    private string GenerateSaleNumber()
    {
        // Format: HQ-20251229-0001
        // Location-Date-Sequence
        var location = GetCurrentLocationCode();
        var date = DateTime.Now.ToString("yyyyMMdd");
        var sequence = GetNextLocalSequence();
        return $"{location}-{date}-{sequence:D4}";
    }
}

L.10A.1G Connection Monitor

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

// ConnectionMonitor.cs

public class ConnectionMonitor : IHostedService
{
    private readonly IApiClient _apiClient;
    private readonly ILogger<ConnectionMonitor> _logger;

    private Timer? _pingTimer;
    private bool _isOnline = false;

    public bool IsOnline => _isOnline;
    public event EventHandler<bool>? OnlineStatusChanged;

    public Task StartAsync(CancellationToken cancellationToken)
    {
        // Ping server every 10 seconds
        _pingTimer = new Timer(
            async _ => await CheckConnectionAsync(),
            null,
            TimeSpan.Zero,
            TimeSpan.FromSeconds(10)
        );

        return Task.CompletedTask;
    }

    private async Task CheckConnectionAsync()
    {
        var wasOnline = _isOnline;

        try
        {
            // Simple health check endpoint
            var response = await _apiClient.PingAsync();
            _isOnline = response.IsSuccessStatusCode;
        }
        catch
        {
            _isOnline = false;
        }

        if (_isOnline != wasOnline)
        {
            _logger.LogInformation(
                "Connection status changed: {Status}",
                _isOnline ? "ONLINE" : "OFFLINE"
            );

            OnlineStatusChanged?.Invoke(this, _isOnline);
        }
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _pingTimer?.Dispose();
        return Task.CompletedTask;
    }
}

Offline UI Indicator

Offline Indicator Design
========================

When ONLINE:
+-----------------------------------------------------------------------+
|  [=] NEXUS POS                                    [GM Store] [John D] |
|  Status: Connected                                                     |
+-----------------------------------------------------------------------+

When OFFLINE:
+-----------------------------------------------------------------------+
|  [=] NEXUS POS                          [!] OFFLINE MODE   [GM Store] |
|  +-----------------------------------------------------------------+  |
|  | Working offline. 5 sales pending sync.                          |  |
|  +-----------------------------------------------------------------+  |
+-----------------------------------------------------------------------+

When SYNCING:
+-----------------------------------------------------------------------+
|  [=] NEXUS POS                     [<->] Syncing... 3/5   [GM Store]  |
+-----------------------------------------------------------------------+

L.10A.1H CRDTs for Conflict-Free Synchronization

Detailed Implementation Reference (from former Offline-First Design chapter, now consolidated here):

Overview

While event sourcing handles sales conflicts (append-only), other data types benefit from CRDTs (Conflict-free Replicated Data Types) - data structures mathematically guaranteed to converge without coordination.

Traditional Sync Problem
========================

Terminal A (Offline):                Terminal B (Offline):
  Inventory: 100                       Inventory: 100
  Customer purchases 5                 Receives shipment +20
  Local: 95                            Local: 120

When both sync - CONFLICT!
  Which value is correct? 95 or 120?
  Answer: Neither! Correct is 115 (100 - 5 + 20)

CRDT Solution:
  Both terminals track OPERATIONS, not STATE
  G-Counter for additions: {A: 0, B: 20}
  PN-Counter for decrements: {A: 5, B: 0}
  Final value: 100 + 20 - 5 = 115

CRDT Types for POS

G-Counter Implementation (Transaction Counts)

// GCounter.cs - Grow-only counter

public class GCounter
{
    // Each node tracks its own increment count
    private readonly Dictionary<string, long> _counters = new();
    private readonly string _nodeId;

    public GCounter(string nodeId)
    {
        _nodeId = nodeId;
        _counters[nodeId] = 0;
    }

    public void Increment(long amount = 1)
    {
        _counters[_nodeId] += amount;
    }

    public long Value => _counters.Values.Sum();

    // Merge with another G-Counter (associative, commutative, idempotent)
    public void Merge(GCounter other)
    {
        foreach (var (nodeId, count) in other._counters)
        {
            if (_counters.TryGetValue(nodeId, out var existing))
            {
                _counters[nodeId] = Math.Max(existing, count);
            }
            else
            {
                _counters[nodeId] = count;
            }
        }
    }

    public Dictionary<string, long> State => new(_counters);
}

PN-Counter for Inventory

// PNCounter.cs - Positive-Negative Counter for inventory

public class PNCounter
{
    private readonly GCounter _positive;
    private readonly GCounter _negative;
    private readonly string _nodeId;

    public PNCounter(string nodeId)
    {
        _nodeId = nodeId;
        _positive = new GCounter(nodeId);
        _negative = new GCounter(nodeId);
    }

    public void Increment(long amount = 1)
    {
        _positive.Increment(amount);
    }

    public void Decrement(long amount = 1)
    {
        _negative.Increment(amount);
    }

    public long Value => _positive.Value - _negative.Value;

    public void Merge(PNCounter other)
    {
        _positive.Merge(other._positive);
        _negative.Merge(other._negative);
    }
}

// Usage in inventory sync
public class InventoryCRDT
{
    private readonly Dictionary<string, PNCounter> _inventory = new();

    public void RecordSale(string sku, int quantity, string terminalId)
    {
        if (!_inventory.ContainsKey(sku))
            _inventory[sku] = new PNCounter(terminalId);

        _inventory[sku].Decrement(quantity);
    }

    public void RecordReceiving(string sku, int quantity, string terminalId)
    {
        if (!_inventory.ContainsKey(sku))
            _inventory[sku] = new PNCounter(terminalId);

        _inventory[sku].Increment(quantity);
    }

    public int GetQuantity(string sku) =>
        _inventory.TryGetValue(sku, out var counter)
            ? (int)counter.Value
            : 0;
}

LWW-Register for Price Updates

// LWWRegister.cs - Last-Writer-Wins Register

public class LWWRegister<T>
{
    private T? _value;
    private DateTime _timestamp;
    private string _nodeId;

    public LWWRegister(string nodeId)
    {
        _nodeId = nodeId;
        _timestamp = DateTime.MinValue;
    }

    public void Set(T value, DateTime? timestamp = null)
    {
        var ts = timestamp ?? DateTime.UtcNow;
        if (ts > _timestamp)
        {
            _value = value;
            _timestamp = ts;
        }
    }

    public T? Value => _value;
    public DateTime Timestamp => _timestamp;

    public void Merge(LWWRegister<T> other)
    {
        if (other._timestamp > _timestamp)
        {
            _value = other._value;
            _timestamp = other._timestamp;
        }
    }
}

// Usage for price sync
public class PriceCRDT
{
    private readonly Dictionary<string, LWWRegister<decimal>> _prices = new();

    public void UpdatePrice(string sku, decimal price, string terminalId)
    {
        if (!_prices.ContainsKey(sku))
            _prices[sku] = new LWWRegister<decimal>(terminalId);

        _prices[sku].Set(price);
    }

    public decimal? GetPrice(string sku) =>
        _prices.TryGetValue(sku, out var register)
            ? register.Value
            : null;
}

OR-Set for Cart Items (with Tombstones)

// ORSet.cs - Observed-Remove Set with tombstones

public class ORSet<T>
{
    private readonly Dictionary<T, HashSet<string>> _additions = new();
    private readonly Dictionary<T, HashSet<string>> _removals = new();
    private readonly string _nodeId;
    private int _counter = 0;

    public ORSet(string nodeId)
    {
        _nodeId = nodeId;
    }

    public void Add(T element)
    {
        var uniqueTag = $"{_nodeId}:{++_counter}";

        if (!_additions.ContainsKey(element))
            _additions[element] = new HashSet<string>();

        _additions[element].Add(uniqueTag);
    }

    public void Remove(T element)
    {
        // Only remove tags we've seen (observed-remove semantics)
        if (_additions.TryGetValue(element, out var tags))
        {
            if (!_removals.ContainsKey(element))
                _removals[element] = new HashSet<string>();

            foreach (var tag in tags)
            {
                _removals[element].Add(tag);
            }
        }
    }

    public IEnumerable<T> Elements =>
        _additions
            .Where(kv =>
            {
                var remainingTags = _removals.TryGetValue(kv.Key, out var removed)
                    ? kv.Value.Except(removed)
                    : kv.Value;
                return remainingTags.Any();
            })
            .Select(kv => kv.Key);

    public void Merge(ORSet<T> other)
    {
        // Merge additions
        foreach (var (element, tags) in other._additions)
        {
            if (!_additions.ContainsKey(element))
                _additions[element] = new HashSet<string>();
            _additions[element].UnionWith(tags);
        }

        // Merge removals (tombstones)
        foreach (var (element, tags) in other._removals)
        {
            if (!_removals.ContainsKey(element))
                _removals[element] = new HashSet<string>();
            _removals[element].UnionWith(tags);
        }
    }
}

Tombstone Handling Strategy

// TombstoneManager.cs

public class TombstoneManager
{
    private readonly TimeSpan _tombstoneTTL = TimeSpan.FromDays(7);

    public void CompactTombstones<T>(ORSet<T> set)
    {
        // Remove tombstones older than TTL
        // Requires tracking tombstone timestamps
    }

    public bool IsSafeToCompact(DateTime tombstoneCreated) =>
        DateTime.UtcNow - tombstoneCreated > _tombstoneTTL;
}

CRDT Sync Protocol

CRDT Sync Flow
==============

POS Terminal A                        Central API
     |                                      |
     |  1. Push local CRDT state           |
     |  ────────────────────────────────►  |
     |     {                                |
     |       "inventory": {                 |
     |         "NXJ1078": {                |
     |           "positive": {"A": 5},     |
     |           "negative": {"A": 2}      |
     |         }                            |
     |       },                             |
     |       "prices": {...}               |
     |     }                                |
     |                                      |
     |  2. Server merges with global state |
     |                                      |
     |  3. Return merged state              |
     |  ◄─────────────────────────────────  |
     |     {                                |
     |       "inventory": {                 |
     |         "NXJ1078": {                |
     |           "positive": {"A": 5, "B": 10, "HQ": 100},
     |           "negative": {"A": 2, "C": 3}
     |         }                            |
     |       }                              |
     |     }                                |
     |                                      |
     |  4. Local merge                      |
     |     Final inventory = 110            |

When to Use CRDTs vs. Event Sourcing

Reference Libraries

L.10A.2 Tax Engine Decision

Tax Calculation Hierarchy (Priority Order):

┌─────────────────────────────────────────────────────────────┐
│                  TAX CALCULATION HIERARCHY                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. PRODUCT-LEVEL OVERRIDE (Highest Priority)               │
│     └── Example: "Grocery Food - 1.5%"                      │
│     └── Example: "Prepared Food - 10%"                      │
│     └── Example: "Prescription Drugs - 0%"                  │
│                                                              │
│  2. CUSTOMER-LEVEL EXEMPTION                                 │
│     └── Example: "Reseller Certificate"                     │
│     └── Example: "Non-Profit 501(c)(3)"                     │
│     └── Example: "Diplomatic Status"                        │
│                                                              │
│  3. LOCATION-BASED TAX (Default)                            │
│     └── State Tax + County Tax + City Tax + District Tax    │
│     └── Based on store physical address                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Virginia Initial Configuration:

tax_jurisdictions:
  virginia:
    state_rate: 4.3
    default_local_rate: 1.0

    # Regional additional taxes
    regions:
      hampton_roads:
        counties: ["Norfolk", "Virginia Beach", "Newport News", "Hampton"]
        additional_rate: 0.7
      northern_virginia:
        counties: ["Arlington", "Fairfax", "Loudoun", "Prince William"]
        additional_rate: 0.7
      central_virginia:
        counties: ["Henrico", "Chesterfield", "Richmond City"]
        additional_rate: 0.0

    # Product exemptions/reduced rates
    exemptions:
      - category: "grocery_food"
        rate: 1.5  # Reduced rate
      - category: "prescription_drugs"
        rate: 0.0
      - category: "medical_equipment"
        rate: 0.0

Expansion Roadmap:

jurisdiction_modules:
  virginia:     { status: "active" }
  california:   { status: "planned", notes: "Complex district taxes, no gift card expiry" }
  oregon:       { status: "planned", notes: "No sales tax state" }
  canada:       { status: "planned", notes: "GST/PST/HST complexity" }
  european_union: { status: "planned", notes: "VAT with reverse charge" }

L.10A.3 Payment Integration Decision

Payment Flow Architecture:

┌─────────────────────────────────────────────────────────────┐
│                SAQ-A PAYMENT ARCHITECTURE                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐            │
│  │ POS UI   │────►│ Backend  │────►│ Terminal │            │
│  │          │     │ API      │     │          │            │
│  └──────────┘     └──────────┘     └────┬─────┘            │
│       ▲                                  │                   │
│       │                                  ▼                   │
│       │           ┌─────────────────────────────────────┐   │
│       │           │         PAYMENT PROCESSOR            │   │
│       │           │     (Card data ONLY here)            │   │
│       │           └─────────────────────────────────────┘   │
│       │                          │                          │
│       │                          ▼                          │
│       │           ┌─────────────────────────────────────┐   │
│       └───────────│  Token + Approval + Masked Card     │   │
│                   │  (NO full PAN, CVV, or track data)  │   │
│                   └─────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Data Storage Rules:

┌─────────────────────────────────────────────────────────────┐
│              PAYMENT DATA STORAGE RULES                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ✅ STORED (Allowed):              ❌ PROHIBITED (Never):   │
│  ├── Payment token                 ├── Full card number     │
│  ├── Approval code                 ├── CVV/CVC              │
│  ├── Masked card (****1234)        ├── Track data           │
│  ├── Card brand (Visa/MC/Amex)     ├── PIN block            │
│  ├── Entry method (chip/tap)       ├── EMV cryptogram (raw) │
│  ├── Terminal ID                   │                        │
│  └── Timestamp                     │                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

L.10A.4 Multi-Tenancy Decision

v18.0 Update: The original Architecture Styles Worksheet v1.6 specified Schema-Per-Tenant. Expert panel review identified a contradiction: every data model table in BRD v18.0 includes tenant_id UUID FK (row-level isolation pattern, 135 occurrences). This revision aligns the architecture decision with the actual BRD data models.

Database Structure:

database: pos_production
│
├── schema: shared
│   ├── tax_rates (global, no tenant_id)
│   ├── system_config (global)
│   └── tenant_registry (tenant metadata)
│
└── schema: public (all tenant data)
    ├── orders          (tenant_id UUID FK + RLS)
    ├── customers        (tenant_id UUID FK + RLS)
    ├── inventory        (tenant_id UUID FK + RLS)
    ├── products         (tenant_id UUID FK + RLS)
    ├── integration_providers (tenant_id UUID FK + RLS)
    └── ... (all other tables with tenant_id + RLS)

RLS Policy Implementation:

-- Enable RLS on every tenant table
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Create isolation policy
CREATE POLICY tenant_isolation ON orders
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

-- Force RLS for non-superuser roles
ALTER TABLE orders FORCE ROW LEVEL SECURITY;

Connection Pattern:

// Tenant resolution via middleware
public class TenantMiddleware
{
    public async Task InvokeAsync(HttpContext context)
    {
        var tenantId = ResolveTenantFromJwt(context);

        // Set PostgreSQL session variable for RLS
        await connection.ExecuteAsync(
            "SET app.current_tenant = @tenantId",
            new { tenantId });

        await _next(context);
    }
}

Benefits:

• Simpler connection pooling (shared pool, not per-schema)
• Standard query patterns (no search_path manipulation)
• Easier migrations (single schema, applied once)
• RLS enforcement at database level (defense-in-depth)
• Matches BRD v18.0 data model conventions

Trade-offs:

• Less physical isolation than schema separation (mitigated by RLS)
• All tenants share same table structure (flexibility limited)
• RLS policies must be applied to every table (automated via migration scripts)

L.10A.4A Multi-Tenancy Strategies Comparison

Detailed Implementation Reference (from former Multi-Tenancy Design chapter, now consolidated here):

Multi-Tenancy Strategies
========================

Strategy 1: Shared Tables (Row-Level)
+----------------------------------+
| products                          |
| +--------+--------+------------+ |
| | tenant | id     | name       | |
| +--------+--------+------------+ |
| | nexus  | 1      | T-Shirt    | |
| | acme   | 2      | Jacket     | |
| | nexus  | 3      | Jeans      | |
| +--------+--------+------------+ |
+----------------------------------+
Pros: Simple, low overhead
Cons: Risk of data leakage, complex queries, no isolation

Strategy 2: Separate Databases
+-------------+    +-------------+    +-------------+
| nexus_db    |    | acme_db     |    | beta_db     |
| +--------+  |    | +--------+  |    | +--------+  |
| |products|  |    | |products|  |    | |products|  |
| +--------+  |    | +--------+  |    | +--------+  |
| |sales   |  |    | |sales   |  |    | |sales   |  |
| +--------+  |    | +--------+  |    | +--------+  |
+-------------+    +-------------+    +-------------+
Pros: Complete isolation
Cons: Connection overhead, backup complexity, cost at scale

Strategy 3: Schema-Per-Tenant
+-----------------------------------------------------+
| pos_platform database                                |
|                                                      |
| +-----------+  +--------------+  +--------------+   |
| | shared    |  | tenant_nexus |  | tenant_acme  |   |
| +-----------+  +--------------+  +--------------+   |
| | tenants   |  | products     |  | products     |   |
| | plans     |  | sales        |  | sales        |   |
| | features  |  | inventory    |  | inventory    |   |
| +-----------+  | customers    |  | customers    |   |
|                +--------------+  +--------------+   |
+-----------------------------------------------------+
Pros: Isolation + efficiency, easy backup/restore per tenant
Cons: More complex migrations (but manageable)

Decision Matrix

Note: The Architecture Styles analysis (L.10A.4 above) selected Row-Level Isolation with PostgreSQL RLS as the production strategy, which aligns with BRD v18.0 data models (135 occurrences of tenant_id). The Schema-Per-Tenant comparison above is preserved for reference and as an alternative should physical isolation requirements change.

L.10A.4B Tenant Resolution & Middleware

Detailed Implementation Reference (from former Multi-Tenancy Design chapter, now consolidated here):

Tenant Resolution Flow

Tenant Resolution Flow
======================

                     +---------------------------+
                     |   Incoming Request        |
                     |   nexus.pos-platform.com  |
                     +-------------+-------------+
                                   |
                                   v
                     +---------------------------+
                     |   Extract Subdomain       |
                     |   subdomain = "nexus"     |
                     +-------------+-------------+
                                   |
                                   v
                     +---------------------------+
                     |   Lookup in shared.tenants|
                     |   WHERE subdomain = ?     |
                     +-------------+-------------+
                                   |
            +----------------------+----------------------+
            |                                             |
      [Found]                                       [Not Found]
            |                                             |
            v                                             v
+---------------------------+               +---------------------------+
| Set PostgreSQL            |               | Return 404               |
| search_path TO            |               | "Tenant not found"       |
| tenant_nexus, shared      |               +---------------------------+
+-------------+-------------+
              |
              v
+---------------------------+
| Continue with request     |
| All queries now use       |
| tenant_nexus schema       |
+---------------------------+

ASP.NET Core Tenant Middleware

// TenantMiddleware.cs

public class TenantMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<TenantMiddleware> _logger;

    public TenantMiddleware(RequestDelegate next, ILogger<TenantMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context, ITenantService tenantService, IDbContextFactory<PosDbContext> dbFactory)
    {
        // 1. Extract subdomain from host
        var host = context.Request.Host.Host;
        var subdomain = ExtractSubdomain(host);

        if (string.IsNullOrEmpty(subdomain))
        {
            context.Response.StatusCode = 400;
            await context.Response.WriteAsJsonAsync(new { error = "Invalid tenant" });
            return;
        }

        // 2. Lookup tenant in shared schema
        var tenant = await tenantService.GetBySubdomainAsync(subdomain);

        if (tenant == null)
        {
            context.Response.StatusCode = 404;
            await context.Response.WriteAsJsonAsync(new { error = "Tenant not found" });
            return;
        }

        if (tenant.Status == "suspended")
        {
            context.Response.StatusCode = 403;
            await context.Response.WriteAsJsonAsync(new { error = "Account suspended" });
            return;
        }

        // 3. Store tenant in HttpContext for downstream use
        context.Items["Tenant"] = tenant;
        context.Items["TenantSchema"] = tenant.SchemaName;

        _logger.LogDebug("Resolved tenant: {TenantSlug} -> {Schema}", tenant.Slug, tenant.SchemaName);

        // 4. Continue pipeline
        await _next(context);
    }

    private string? ExtractSubdomain(string host)
    {
        // nexus.pos-platform.com -> nexus
        // localhost:5000 -> null (development fallback)

        var parts = host.Split('.');
        if (parts.Length >= 3)
        {
            return parts[0];
        }

        // Development fallback: check header
        return null;
    }
}

// ITenantService.cs
public interface ITenantService
{
    Task<Tenant?> GetBySubdomainAsync(string subdomain);
    Task<Tenant?> GetBySlugAsync(string slug);
    Task<string> CreateTenantAsync(CreateTenantRequest request);
}

// TenantService.cs
public class TenantService : ITenantService
{
    private readonly IDbContextFactory<SharedDbContext> _dbFactory;
    private readonly ILogger<TenantService> _logger;

    public TenantService(IDbContextFactory<SharedDbContext> dbFactory, ILogger<TenantService> logger)
    {
        _dbFactory = dbFactory;
        _logger = logger;
    }

    public async Task<Tenant?> GetBySubdomainAsync(string subdomain)
    {
        await using var db = await _dbFactory.CreateDbContextAsync();
        return await db.Tenants
            .AsNoTracking()
            .FirstOrDefaultAsync(t => t.Subdomain == subdomain);
    }

    public async Task<string> CreateTenantAsync(CreateTenantRequest request)
    {
        var schemaName = $"tenant_{request.Slug}";

        await using var db = await _dbFactory.CreateDbContextAsync();

        // 1. Create tenant record
        var tenant = new Tenant
        {
            Slug = request.Slug,
            Name = request.Name,
            Subdomain = request.Subdomain,
            SchemaName = schemaName,
            PlanId = request.PlanId,
            Status = "active"
        };

        db.Tenants.Add(tenant);
        await db.SaveChangesAsync();

        // 2. Create schema (raw SQL)
        await db.Database.ExecuteSqlRawAsync($"CREATE SCHEMA {schemaName}");

        // 3. Run migrations on new schema
        await RunMigrationsAsync(schemaName);

        _logger.LogInformation("Created tenant: {Slug} with schema {Schema}", request.Slug, schemaName);

        return tenant.Id.ToString();
    }

    private async Task RunMigrationsAsync(string schemaName)
    {
        // Apply all tenant schema tables
        // This would run the full schema creation script
    }
}

DbContext with Dynamic Schema

// PosDbContext.cs

public class PosDbContext : DbContext
{
    private readonly string _schemaName;

    public PosDbContext(DbContextOptions<PosDbContext> options, IHttpContextAccessor httpContextAccessor)
        : base(options)
    {
        // Get schema from HttpContext (set by TenantMiddleware)
        _schemaName = httpContextAccessor.HttpContext?.Items["TenantSchema"]?.ToString()
            ?? "tenant_default";
    }

    public DbSet<Product> Products => Set<Product>();
    public DbSet<Sale> Sales => Set<Sale>();
    public DbSet<Customer> Customers => Set<Customer>();
    public DbSet<Employee> Employees => Set<Employee>();
    public DbSet<Location> Locations => Set<Location>();
    // ... other DbSets

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Set default schema for all entities
        modelBuilder.HasDefaultSchema(_schemaName);

        // Apply entity configurations
        modelBuilder.ApplyConfigurationsFromAssembly(typeof(PosDbContext).Assembly);
    }
}

Connection String with search_path

// TenantDbContextFactory.cs

public class TenantDbContextFactory : IDbContextFactory<PosDbContext>
{
    private readonly IConfiguration _config;
    private readonly IHttpContextAccessor _httpContextAccessor;

    public TenantDbContextFactory(IConfiguration config, IHttpContextAccessor httpContextAccessor)
    {
        _config = config;
        _httpContextAccessor = httpContextAccessor;
    }

    public PosDbContext CreateDbContext()
    {
        var schemaName = _httpContextAccessor.HttpContext?.Items["TenantSchema"]?.ToString()
            ?? throw new InvalidOperationException("No tenant context");

        var baseConnectionString = _config.GetConnectionString("DefaultConnection");

        // Append search_path to connection string
        var connectionString = $"{baseConnectionString};Search Path={schemaName},shared";

        var optionsBuilder = new DbContextOptionsBuilder<PosDbContext>();
        optionsBuilder.UseNpgsql(connectionString);

        return new PosDbContext(optionsBuilder.Options);
    }
}

L.10A.4C Tenant Provisioning

Detailed Implementation Reference (from former Multi-Tenancy Design chapter, now consolidated here):

New Tenant Signup Flow
======================

[Admin Portal]                      [API]                          [Database]
      |                               |                                  |
      | 1. POST /tenants              |                                  |
      |   { name, slug, plan }        |                                  |
      |------------------------------>|                                  |
      |                               |                                  |
      |                               | 2. Validate slug uniqueness      |
      |                               |--------------------------------->|
      |                               |                                  |
      |                               | 3. Insert into shared.tenants    |
      |                               |--------------------------------->|
      |                               |                                  |
      |                               | 4. CREATE SCHEMA tenant_{slug}   |
      |                               |--------------------------------->|
      |                               |                                  |
      |                               | 5. Run schema migrations         |
      |                               |   (create all tables)            |
      |                               |--------------------------------->|
      |                               |                                  |
      |                               | 6. Seed default data             |
      |                               |   (roles, permissions)           |
      |                               |--------------------------------->|
      |                               |                                  |
      |                               | 7. Create admin user             |
      |                               |--------------------------------->|
      |                               |                                  |
      | 8. Return tenant details      |                                  |
      |   { id, subdomain, status }   |                                  |
      |<------------------------------|                                  |
      |                               |                                  |
      | 9. Redirect to tenant portal  |                                  |
      |   nexus.pos-platform.com      |                                  |
      |                               |                                  |

L.10A.4D Schema Migration Strategy

Detailed Implementation Reference (from former Multi-Tenancy Design chapter, now consolidated here):

Applying Migrations to All Tenants

// TenantMigrationService.cs

public class TenantMigrationService
{
    private readonly SharedDbContext _sharedDb;
    private readonly ILogger<TenantMigrationService> _logger;

    public async Task ApplyMigrationToAllTenantsAsync(string migrationScript)
    {
        var tenants = await _sharedDb.Tenants.ToListAsync();

        foreach (var tenant in tenants)
        {
            try
            {
                _logger.LogInformation("Applying migration to {Schema}", tenant.SchemaName);

                await _sharedDb.Database.ExecuteSqlRawAsync(
                    $"SET search_path TO {tenant.SchemaName}; {migrationScript}"
                );

                _logger.LogInformation("Migration complete for {Schema}", tenant.SchemaName);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Migration failed for {Schema}", tenant.SchemaName);
                // Continue with other tenants or abort based on policy
            }
        }
    }
}

Migration Script Example

-- Migration: Add loyalty_tier to customers
-- File: 2025-01-15_add_loyalty_tier.sql

DO $$
DECLARE
    tenant_schema TEXT;
BEGIN
    FOR tenant_schema IN
        SELECT schema_name FROM shared.tenants WHERE status = 'active'
    LOOP
        EXECUTE format('ALTER TABLE %I.customers ADD COLUMN IF NOT EXISTS loyalty_tier VARCHAR(20) DEFAULT ''bronze''', tenant_schema);
    END LOOP;
END $$;

Shared Schema SQL Reference

-- Schema: shared

-- Tenant Registry
CREATE TABLE shared.tenants (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    slug            VARCHAR(50) UNIQUE NOT NULL,   -- 'nexus', 'acme'
    name            VARCHAR(255) NOT NULL,         -- 'Nexus Clothing'
    subdomain       VARCHAR(100) UNIQUE NOT NULL,  -- 'nexus.pos-platform.com'
    schema_name     VARCHAR(100) NOT NULL,         -- 'tenant_nexus'
    plan_id         UUID REFERENCES shared.subscription_plans(id),
    status          VARCHAR(20) DEFAULT 'active',  -- active, suspended, trial
    trial_ends_at   TIMESTAMPTZ,
    created_at      TIMESTAMPTZ DEFAULT NOW(),
    updated_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Subscription Plans
CREATE TABLE shared.subscription_plans (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name            VARCHAR(100) NOT NULL,         -- 'Starter', 'Professional'
    code            VARCHAR(50) UNIQUE NOT NULL,   -- 'starter', 'pro', 'enterprise'
    price_monthly   DECIMAL(10,2),
    price_yearly    DECIMAL(10,2),
    max_locations   INTEGER DEFAULT 1,
    max_registers   INTEGER DEFAULT 2,
    max_employees   INTEGER DEFAULT 5,
    max_products    INTEGER DEFAULT 1000,
    features        JSONB DEFAULT '{}',            -- Feature flags
    is_active       BOOLEAN DEFAULT TRUE,
    created_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Feature Flags
CREATE TABLE shared.feature_flags (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    key             VARCHAR(100) UNIQUE NOT NULL,  -- 'loyalty_program'
    name            VARCHAR(255) NOT NULL,
    description     TEXT,
    default_enabled BOOLEAN DEFAULT FALSE,
    created_at      TIMESTAMPTZ DEFAULT NOW()
);

-- Insert default plans
INSERT INTO shared.subscription_plans (name, code, price_monthly, max_locations, max_registers, max_employees, max_products) VALUES
('Starter', 'starter', 49.00, 1, 2, 5, 1000),
('Professional', 'pro', 149.00, 3, 10, 25, 10000),
('Enterprise', 'enterprise', 499.00, -1, -1, -1, -1);  -- -1 = unlimited

L.10A.5 Commission Reversal Decision

Commission Reversal Rules:

┌─────────────────────────────────────────────────────────────┐
│              COMMISSION REVERSAL LOGIC                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  VOID (Same day, before drawer close):                      │
│  ├── Reversal: 100% (full)                                  │
│  ├── Rationale: Mistake correction, sale didn't happen      │
│  └── Example: $6 commission → reverse $6                    │
│                                                              │
│  RETURN (After sale completed):                             │
│  ├── Reversal: Proportional to returned value               │
│  ├── Formula: Original Commission × (Returned / Original)  │
│  └── Example:                                               │
│      Sale: $120, Commission: $6 (5%)                        │
│      Return: $80 of items                                   │
│      Reversal: $6 × ($80/$120) = $4.00                     │
│      Net Commission: $6 - $4 = $2.00                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Configuration:

commissions:
  default_rate_percent: 2.0
  category_rates:
    electronics: 3.0
    services: 5.0

  # Reversal rules
  reverse_on_void: true
  void_reversal_method: "full"        # 100%

  reduce_on_return: true
  return_reversal_method: "proportional"  # Based on value

L.10A.6 Geographic Expansion Strategy

Expansion Strategy:

┌─────────────────────────────────────────────────────────────┐
│              GEOGRAPHIC EXPANSION ROADMAP                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  PHASE 1: Virginia (Day 1)                                  │
│  ├── Tax: State 4.3% + Local 1% + Regional 0.7%            │
│  ├── Gift Cards: 5-year minimum expiry allowed              │
│  └── Compliance: Virginia Consumer Protection Act           │
│                                                              │
│  PHASE 2: US Expansion                                       │
│  ├── California: No gift card expiry, $10 cash-out rule    │
│  ├── Oregon: No sales tax                                   │
│  ├── New York: Complex local taxes                          │
│  └── Florida: No income tax, tourism taxes                  │
│                                                              │
│  PHASE 3: International                                      │
│  ├── Canada: GST/HST/PST provincial variations              │
│  ├── EU: VAT with reverse charge for B2B                    │
│  └── UK: Post-Brexit VAT rules                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Design Principle: Always design for the most restrictive jurisdiction (California for US), then enable features where permitted.

Gift Card Jurisdiction Matrix: | Jurisdiction | Expiry Allowed | Inactivity Fee | Cash-Out Required | |–––––––|––––––––|––––––––|—————––| | Virginia | Yes (5yr min) | Yes (after 12mo) | No | | California | No | No | Yes ($10 threshold) | | New York | No | No | No | | Default | No | No | No |

L.10A.7 Decision Dependency Graph

┌─────────────────────────────────────────────────────────────┐
│              ARCHITECTURE DECISION DEPENDENCIES              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│                    ┌──────────────────┐                     │
│                    │ Geographic Scope │                     │
│                    │   (ADR-BRD-006)  │                     │
│                    └────────┬─────────┘                     │
│                             │                                │
│              ┌──────────────┼──────────────┐                │
│              ▼              ▼              ▼                │
│     ┌────────────┐  ┌────────────┐  ┌────────────┐        │
│     │ Tax Engine │  │ Gift Card  │  │ Compliance │        │
│     │(ADR-BRD-002)│  │   Rules    │  │   Rules    │        │
│     └──────┬─────┘  └────────────┘  └────────────┘        │
│            │                                                │
│            ▼                                                │
│     ┌────────────┐                                         │
│     │  Offline   │───────────────────────────┐             │
│     │(ADR-BRD-001)│                          │             │
│     └──────┬─────┘                           │             │
│            │                                  ▼             │
│            ▼                          ┌────────────┐       │
│     ┌────────────┐                    │ Payment    │       │
│     │ Multi-     │                    │(ADR-BRD-003)│       │
│     │ Tenancy    │                    └────────────┘       │
│     │(ADR-BRD-004)│                                        │
│     └────────────┘                                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

L.11 Style Decision Summary

Final Selection

+------------------------------------------------------------------+
|                   ARCHITECTURE DECISION SUMMARY                    |
|                        (v2.0 - Panel Reviewed)                    |
+------------------------------------------------------------------+
|                                                                   |
|  QUESTION: What is the primary architecture style?                |
|  ANSWER:   Event-Driven Modular Monolith                          |
|                                                                   |
|  ┌─────────────────────────────────────────────────────────────┐ |
|  │                    SELECTED PATTERNS                         │ |
|  ├─────────────────────────────────────────────────────────────┤ |
|  │  ✅ Modular Monolith      → Central API                     │ |
|  │  ✅ Microkernel (Plugin)  → POS Client                      │ |
|  │  ✅ Event-Driven          → PostgreSQL Events (v1.0)        │ |
|  │                             Kafka (v2.0, when justified)    │ |
|  │  ✅ Event Sourcing        → Sales (Full) + Inventory (Audit)│ |
|  │                             + Integrations (Audit-trail)    │ |
|  │  ✅ CQRS                  → Sales Module (Read/Write split) │ |
|  │  ✅ Offline-First         → POS Client (SQLite)             │ |
|  │  ✅ Row-Level with RLS    → Multi-Tenant Isolation          │ |
|  │  ✅ Integration Gateway   → Module 6 (Extractable)          │ |
|  │  ✅ Circuit Breaker       → External API Resilience         │ |
|  │  ✅ Transactional Outbox  → Guaranteed Event Delivery       │ |
|  │  ✅ Provider Abstraction  → IIntegrationProvider Interface  │ |
|  │  ✅ Credential Vault      → HashiCorp Vault                 │ |
|  └─────────────────────────────────────────────────────────────┘ |
|                                                                   |
|  ┌─────────────────────────────────────────────────────────────┐ |
|  │                    REJECTED PATTERNS                         │ |
|  ├─────────────────────────────────────────────────────────────┤ |
|  │  ❌ Microservices         → Too complex for current scale   │ |
|  │  ❌ Space-Based           → Too complex for financial audit │ |
|  │  ❌ Schema-Per-Tenant     → Replaced by Row-Level with RLS │ |
|  │  ❌ Kafka (v1.0)          → Deferred to v2.0               │ |
|  └─────────────────────────────────────────────────────────────┘ |
|                                                                   |
+------------------------------------------------------------------+

Document Information

Change Log

Next Chapter: Chapter 05: Architecture Components (BRD v20.0)

This chapter is part of the POS Blueprint Book. All content is self-contained.

Chapter 05: Architecture Components (BRD v20.0)

5.0 About This Chapter

This chapter contains the complete Business Requirements Document (BRD) v20.0 for the POS Platform. It serves as the authoritative source for all functional requirements, business rules, state machines, and module specifications.

Authority Rule: When any other chapter in this Blueprint conflicts with content in this chapter, this chapter (BRD) wins.

Module Overview

How to Use This Chapter

• For implementation: Find the relevant Module and Section number
• For business rules: Check the YAML business rules in each module
• For state machines: See Module 7 (State Machine Reference)
• For decisions: 113 decisions documented throughout, summarized in Appendix
• For user stories: Gherkin acceptance criteria at the end of each module

This document consolidates all features into a modular architecture.

• Module 1 (Sales): Covers Scanner, Financials, Discounts, Post-Sale corrections, Gift Cards, Exchanges, Special Orders, Multi-Store, Commissions, Cash Management, Offline Operations, Tax Engine, Payment Integration, and more.
• Module 2 (Customers): Covers Profiles, Merging, Tax Logic, Data Management, Customer Groups, Notes, Communication Preferences, and Privacy Compliance.
• Module 3 (Catalog): Covers Product Types & Data Model (with retail attributes, custom fields, UoM, shipping, templates, matrix management), Product Lifecycle, Pricing Engine (price hierarchy, price books, promotions, markdowns), Barcode Management, Categories/Seasons/Collections, Multi-Channel Management, Shopify Integration, Vendor Management, Search & Discovery, Label Printing, Media Management, Notes & Attachments, Permissions & Approvals, Product Analytics, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 4 (Inventory): Covers Inventory Status Model, Purchase Orders & Procurement, Receiving & Inspection, Reorder Management, Inventory Counting & Auditing, Inventory Adjustments, Inter-Store Transfers, Vendor RMA & Returns, Serial & Lot Tracking, Landed Cost & Costing, Product Movement History, POS & Sales Integration, Online Order Fulfillment, Offline Operations, Alerts & Notifications, Dashboard & Reports, Business Rules, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 5 (Setup & Configuration): Covers System Settings, Multi-Currency, Location Management, Supplier Configuration, User Profiles & Permissions, Time Tracking (Clock-In/Clock-Out), Register Management, Printers & Peripherals, Tax Configuration, UoM Management, Payment Methods, Custom Fields, Approval Workflows, Receipt Configuration, Email Templates, Loyalty Settings, Audit Logging, Consolidated Business Rules (YAML), Tenant Onboarding Wizard, Field Specifications Reference with Technical User Stories, and comprehensive User Stories with Gherkin acceptance criteria.
• Module 6 (Integrations & External Systems): Covers Integration Architecture (provider abstraction, retry/backoff, circuit breaker, idempotency, rate limiting, webhook pipeline), Shopify Integration (enhanced with GraphQL, bulk operations, third-party POS rules, BOPIS, omnichannel), Amazon SP-API Integration (OAuth/LWA, catalog/listings/orders/FBA APIs, FBA+FBM fulfillment, compliance, safety buffers), Google Merchant API Integration (product data management, local inventory, disapproval prevention, image requirements, GBP integration), Cross-Platform Product Data Requirements (unified validation matrix, strictest-rule-wins), Cross-Platform Inventory Sync Rules (safety buffers, oversell prevention, channel-specific rules), Payment Processor Integration, Email Provider Integration, Carrier & Shipping Integration, Integration Hub, Integration Business Rules (YAML), and comprehensive User Stories with Gherkin acceptance criteria.

1. Sales Module

1.1 Core Sales Workflow (Item Entry & Logic)

Scope: Scanner/Manual Entry, Inventory Checks, Parking, and Customer Association.

Cross-Reference: See Module 4, Section 4.13 for inventory reservation model during sales.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant SC as Scanner
    participant API as Backend
    participant DB as DB
    participant PROMO as Promo Engine

    Note over U, PROMO: Phase 1: Initiation & Entry

    loop Action Loop
        U->>UI: Toggle Mode (Sale / Return / Exchange)

        alt Input Methods
            U->>UI: Scan Barcode / Search SKU
            UI->>API: GET /product/{sku}
        else Scanner Broadcast
            SC->>UI: Tags Detected (Array)
            UI->>API: POST /products/bulk-lookup
            Note right of API: Max 50 tags per request
        end

        API->>DB: Fetch Price, Stock, Tax
        DB-->>UI: Return Product Data

        alt Stock Validation
            opt Mode == Sale
                UI->>UI: Check Stock > 0
                alt Low Stock
                    UI-->>U: Warning / Block Item
                end
            end
        end

        alt Mode Check
            opt Mode == Exchange
                U->>UI: Load Original Sale for Exchange
                UI->>API: GET /orders/{id}
                API-->>UI: Return Original Sale Items
                UI->>UI: Select Items to Exchange OUT
                UI->>UI: Scan/Add New Items IN
                UI->>UI: Calculate Price Difference
                Note right of UI: Links to Exchange flow in Section 1.4
            end
        end

        UI->>UI: Add to Cart

        par Intelligence & Context
            UI->>PROMO: Analyze Cart Context
            PROMO-->>UI: Trigger Upsell Alert ("Buy 1 more for 10% off")
        and Customer Attachment
            opt Attach Customer
                UI->>API: GET /customer/{id} (Loyalty/Debt/Price Tier)
                API-->>UI: Return Profile (Credit Limit, Tax Class, Price Level)
                UI->>UI: Recalculate Prices (if Price Tier applies)
                UI->>UI: Recalculate Tax (if Exempt)
            end
        end
    end

    opt Session Management
        U->>UI: Click "Park Sale"
        UI->>API: POST /sales/park
        API->>DB: Serialize State & Release Locks

        U->>UI: Click "Retrieve Sale"
        UI->>API: GET /sales/parked
        API-->>UI: Restore Cart
    end

1.1.1 Parked Sale State Machine

stateDiagram-v2
    [*] --> ACTIVE: Cart Created
    ACTIVE --> PARKED: Staff Parks Sale
    PARKED --> ACTIVE: Staff Retrieves Sale
    PARKED --> EXPIRED: TTL Exceeded (4 hours)
    EXPIRED --> [*]: Inventory Released
    ACTIVE --> PENDING: Proceed to Payment

Parked Sale Rules:

• Maximum parked sales per terminal: 5
• TTL (Time-to-Live): 4 hours
• Inventory is soft-reserved while parked (visible to other terminals with warning)
• Expired parked sales auto-release inventory and log reason

1.1.2 Reports: Core Sales

1.2 Discounts & Pricing Logic

Scope: Line-item overrides, Global discounts, Promotion application, Price Tiers, and Loyalty Redemptions.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 2: Modification & Pricing

    loop Pricing Actions
        alt Line Item Modification
            U->>UI: Select Item -> Override Price
            opt Manager Auth
                UI-->>U: Prompt PIN
                U->>UI: Enter PIN
            end
            UI->>UI: Apply New Price & Reason Code (e.g., "Damaged")
        end

        alt Discounting
            U->>UI: Apply Global Discount / Promo Code / Coupon
            UI->>API: Validate Code (Expiry/Stacking/Single-Use)
            API-->>UI: Valid

            Note right of UI: Critical Calculation Order:
            UI->>UI: 1. Apply Price Tier (Wholesale/VIP)
            UI->>UI: 2. Apply Line Discounts
            UI->>UI: 3. Apply Global % (Excluding Non-Discountable)
            UI->>UI: 4. Apply Coupons
            UI->>UI: 5. Calculate Tax (on discounted subtotal)
            UI->>UI: 6. Apply Loyalty Redemptions (after tax)
        end
    end

1.2.1 Discount Calculation Order (Definitive)

The system applies discounts in this strict order:

Non-Discountable Items: Gift cards, deposits, and items flagged is_discountable = false are excluded from global discounts.

1.2.2 Reports: Discounts & Pricing

1.3 Financial Settlement (Payments, Layaway, Third-Party Financing)

Scope: Split tenders, Credit Limits, Gift Cards, Third-Party Financing (Affirm), and Finalization.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant PAY as Payment Gateway

    Note over U, DB: Phase 3: Settlement

    U->>UI: Click "Pay"

    loop Tender Processing
        U->>UI: Select Method
        Note right of UI: Multiple tenders allowed: cash + card(s), multiple cards, etc.

        alt Cash
            UI-->>U: Show "Collect: $20.03"
            U->>UI: Enter Amount Received
            UI->>UI: Calculate Change Due

        else Gift Card
            U->>UI: Scan/Enter Gift Card Number
            UI->>API: GET /giftcards/{number}/balance
            API-->>UI: Return Balance & Expiry
            alt Sufficient Balance
                UI->>UI: Deduct from Gift Card
                UI->>UI: Add to Tender List
            else Insufficient Balance
                UI-->>U: "Card Balance: $X. Apply partial?"
                U->>UI: Apply Partial Amount
            end

        else On-Account (Store Credit)
            UI->>API: Check Credit Limit (Balance + Pending Layaways + Cart)
            alt Exceeds Limit
                API-->>UI: Block Transaction
            else Approved
                UI->>UI: Add to Tender List
            end

        else Layaway Deposit
            U->>UI: Select Layaway Mode
            UI->>UI: Validate Min Deposit %
            Note right of UI: Sale Status -> LAYAWAY

        else Credit Card (SAQ-A Flow)
            UI->>API: POST /payments/initiate {amount, order_id}
            API->>PAY: Send amount to terminal
            Note over PAY: Customer taps/inserts card
            PAY-->>API: Token + Approval Code
            API->>DB: Store token (never card data)
            API-->>UI: Payment Approved

        else Third-Party Financing (Affirm)
            U->>UI: Select "Pay with Affirm"
            UI->>API: POST /payments/affirm/initiate {amount, order_id, customer}
            API->>PAY: Create Affirm Checkout Session
            PAY-->>API: Redirect URL / QR Code
            API-->>UI: Display QR Code or Redirect
            Note over PAY: Customer completes Affirm application on their device
            PAY-->>API: Webhook: Loan Approved + Charge ID
            API->>DB: Store Affirm charge_id, loan_id, status
            API-->>UI: Payment Approved (Affirm)
            Note right of API: Full amount received from Affirm; customer pays Affirm directly
        end

        UI->>UI: Update Remaining Balance
    end

    UI->>API: POST /orders/finalize

    par Backend Operations
        API->>DB: Write Order Record
        API->>DB: Update Inventory (Decrement Sale / Increment Return)
        API->>DB: Update Customer (Loyalty Points / Increase Debt)
        API->>DB: Update Gift Card Balance (if used)
        API->>DB: Record Commission (Employee ID + Amount)
    end

    API-->>UI: Transaction Success

    opt Receipt Printing
        U->>UI: Select Template (Thermal / A4 Invoice / Gift Receipt)
        UI->>U: Print / Email Receipt
    end

1.3.1 Order State Machine

stateDiagram-v2
    [*] --> DRAFT: Cart Created
    DRAFT --> PENDING: Click Pay
    PENDING --> PARTIAL_PAID: Partial Payment
    PARTIAL_PAID --> PENDING: More Payment Needed
    PENDING --> PAID: Full Payment
    PARTIAL_PAID --> PAID: Full Payment
    PAID --> COMPLETED: Finalized
    PAID --> HOLD_FOR_PICKUP: Hold Requested
    HOLD_FOR_PICKUP --> READY_FOR_PICKUP: Items Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> HOLD_EXPIRED: Deadline Passed
    HOLD_EXPIRED --> CONTACT_CUSTOMER: Staff Notified
    CONTACT_CUSTOMER --> READY_FOR_PICKUP: Deadline Extended
    CONTACT_CUSTOMER --> REFUNDED: Customer Wants Refund
    COMPLETED --> VOIDED: Void Action (Same Day)
    COMPLETED --> PARTIALLY_RETURNED: Partial Return
    PARTIALLY_RETURNED --> FULLY_RETURNED: All Items Returned
    VOIDED --> [*]
    FULLY_RETURNED --> [*]
    REFUNDED --> [*]

1.3.2 Layaway State Machine

stateDiagram-v2
    [*] --> DEPOSIT_PAID: Min Deposit Received
    DEPOSIT_PAID --> RESERVED: Inventory Reserved
    RESERVED --> RESERVED: Additional Payment
    RESERVED --> PAID_IN_FULL: Final Payment
    PAID_IN_FULL --> COMPLETED: Items Released
    RESERVED --> CANCELLED: Customer Cancels
    RESERVED --> FORFEITED: Payment Deadline Missed
    CANCELLED --> [*]
    FORFEITED --> [*]
    COMPLETED --> [*]

1.3.3 Credit Limit Calculation

When checking if a customer can use On-Account payment:

Available Credit = Credit Limit - (Current Debt + Pending Layaway Balances + Current Cart Total)

Example:

• Credit Limit: $500
• Current Debt: $150
• Pending Layaway (remaining balance): $100
• Current Cart: $200
• Available Credit: $500 - ($150 + $100 + $200) = $50
• Result: Blocked (cart exceeds available credit by $150)

1.3.4 Reports: Financial Settlement

1.4 Post-Sale Management (History, Void, Returns, Exchanges)

Scope: Corrections, History, Returns, Dedicated Exchanges, Receipt Reprinting, and Data Export.

sequenceDiagram
    autonumber
    participant U as Manager
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    U->>UI: Open Sales History
    U->>UI: Apply Filters (Date, User, Status)
    UI->>API: GET /sales/history

    alt Action: Void (Same-Day Correction Only)
        Note right of U: "Oops, wrong item - same day"
        UI->>API: GET /orders/{id}/void-eligibility
        API-->>UI: Check if same business day & drawer still open

        alt Eligible for Void
            U->>UI: Click Void -> Confirm
            UI->>API: POST /sales/{id}/void

            par Reversal
                API->>DB: Reverse Inventory & Loyalty
                API->>DB: Reverse Commission (Full)
                API->>DB: Set Status "VOIDED"
            end

            UI-->>U: Alert: "Manually Refund Card Terminal"
        else Not Eligible (Different Day)
            UI-->>U: "Cannot void - use Return instead"
        end

    else Action: Return (with Policy Check)
        Note right of U: "Customer brought it back"
        U->>UI: Scan Receipt Barcode
        UI->>API: POST /receipts/validate {barcode_data}
        API->>DB: Verify receipt authenticity & match to order
        alt Receipt Valid
            API-->>UI: Receipt Verified - Load Original Sale
        else Receipt Invalid
            API-->>UI: "Invalid Receipt - Cannot Process Return"
            UI-->>U: "Receipt validation failed. Verify receipt."
        end
        UI->>API: GET /sales/{id}/return-eligibility
        API-->>UI: Return Policy Result

        alt Within Policy (Receipt + Time)
            UI->>UI: Select Items to Return
            UI->>UI: Process Refund to Original Payment
            API->>DB: Reverse Commission (Proportional)
        else Outside Policy (No Receipt / Expired)
            UI-->>U: "Policy Exception - Store Credit Only"
            opt Manager Override
                UI-->>U: Prompt Manager PIN
                U->>UI: Enter PIN + Reason Code
            end
            UI->>UI: Issue Store Credit
        end

    else Action: Exchange (Dedicated Flow)
        Note right of U: "Customer wants different size"
        U->>UI: Load Original Sale -> Click "Exchange"
        UI->>UI: Select Item(s) to Exchange OUT
        UI->>UI: Scan/Add New Item(s) IN
        UI->>UI: Calculate Price Difference

        alt Customer Owes Money
            UI-->>U: "Collect: $15.00 difference"
            U->>UI: Process Payment
        else Store Owes Refund
            UI-->>U: "Refund: $10.00 to customer"
            U->>UI: Process Refund
        else Even Exchange
            UI->>UI: No Payment Required
        end

        UI->>API: POST /sales/exchange
        API->>DB: Create Exchange Record (Links Old & New)
        API->>DB: Update Inventory (Both Directions)
        API->>DB: Adjust Commission (if price difference)

    else Action: Reprint Receipt
        U->>UI: Click "Reprint Receipt"
        UI->>API: GET /orders/{id}/receipt
        API-->>UI: Return Receipt Data
        U->>UI: Select Format (Thermal / A4 / Email)
        opt Email to Different Address
            U->>UI: Enter Email Address
            UI->>API: POST /orders/{id}/email-receipt
        end

    else Action: Pay Off Layaway
        U->>UI: Retrieve Layaway
        UI->>UI: Pay Remaining Balance
        UI->>API: Finalize (Status: COMPLETED)
        API->>DB: Release Reserve -> Sold
    end

Cross-Reference: See Module 4, Section 4.13 for POS inventory integration details.

1.4.1 Void vs. Return Rules

Card Refund Method Selection (Returns Only):

• Manual on terminal: Customer presents physical card. Staff processes refund on the payment terminal. Use when customer is present with their card.
• Automatic via token: System uses the stored payment token to process refund without card present. Use when customer does not have their card or for remote returns.
• Cash payments: Refund is always cash from drawer. No token option available for cash transactions.

1.4.2 Reports: Post-Sale

Email Template: TMPL-REFUND-CONFIRMATION

1.5 Gift Card Management

Scope: Selling, Activating, Redeeming, Balance Management, and Jurisdiction Compliance.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Gift Card Operations

    alt Sell New Gift Card
        U->>UI: Scan Gift Card (or Enter Number)
        U->>UI: Enter Load Amount
        UI->>API: POST /giftcards/activate
        API->>DB: Create Gift Card Record (Number, Balance, Expiry)
        API->>DB: Set Jurisdiction Rules (based on store location)
        API-->>UI: Activation Success
        UI->>UI: Add Gift Card to Cart as Product
        Note right of UI: Proceeds through normal checkout
    end

    alt Check Balance
        U->>UI: Click "Gift Card Balance"
        U->>UI: Scan/Enter Card Number
        UI->>API: GET /giftcards/{number}/balance
        API-->>UI: Display Balance & Expiry Date (if applicable)
    end

    alt Reload Existing Card
        U->>UI: Scan Gift Card
        UI->>API: GET /giftcards/{number}
        API-->>UI: Card Found - Current Balance
        U->>UI: Enter Reload Amount
        UI->>UI: Add Reload to Cart
        Note right of UI: Balance updated after payment
    end

    alt Cash Out (California Compliance)
        U->>UI: Scan Gift Card
        UI->>API: GET /giftcards/{number}
        API-->>UI: Return Balance & Jurisdiction
        alt Balance <= Cash Out Threshold
            UI-->>U: "Eligible for Cash Out: $8.50"
            U->>UI: Process Cash Out
            API->>DB: Zero Balance, Record Cash Out
        else Balance > Threshold
            UI-->>U: "Not eligible for cash out"
        end
    end

1.5.1 Gift Card State Machine

stateDiagram-v2
    [*] --> INACTIVE: Card Manufactured
    INACTIVE --> ACTIVE: Activated at POS (Sold)
    ACTIVE --> ACTIVE: Partial Redemption
    ACTIVE --> ACTIVE: Reload
    ACTIVE --> DEPLETED: Balance = $0.00
    ACTIVE --> EXPIRED: Past Expiry Date (where allowed)
    DEPLETED --> ACTIVE: Reloaded
    DEPLETED --> CASHED_OUT: Cash Out Processed
    EXPIRED --> [*]
    CASHED_OUT --> [*]

    note right of ACTIVE
        Balance > $0
        Within expiry (if applicable)
    end note

    note right of DEPLETED
        Balance = $0
        Can be reloaded
    end note

1.5.2 Gift Card Jurisdiction Compliance

Implementation: Store location determines which jurisdiction rules apply. System defaults to most restrictive (California-style) and enables features where permitted.

1.5.3 Reports: Gift Cards

1.6 Special Orders & Back Orders

Scope: Ordering out-of-stock items with customer deposits.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant INV as Inventory/Purchasing

    Note over U, INV: Special Order Flow

    U->>UI: Search Product -> Out of Stock
    UI-->>U: "Available for Special Order"

    U->>UI: Click "Create Special Order"
    UI->>UI: Attach Customer (Required)
    UI->>UI: Enter Quantity Needed
    UI->>UI: Calculate Deposit (Min 50% or Full)

    C->>U: Agrees to Deposit
    U->>UI: Process Deposit Payment
    UI->>API: POST /special-orders/create

    par Order Creation
        API->>DB: Create Special Order Record
        API->>DB: Link Customer & Deposit Payment
        API->>DB: Set Status: DEPOSIT_PAID
        API->>INV: Notify Purchasing Team
    end

    API-->>UI: Order #SO-12345 Created
    UI->>U: Print Special Order Receipt

    Note over INV, DB: Later - Item Arrives

    INV->>API: POST /special-orders/{id}/received
    API->>DB: Update Status: READY_FOR_PICKUP
    API-->>C: Send Notification (SMS/Email)

    Note over U, C: Customer Pickup

    U->>UI: Retrieve Special Order
    UI->>UI: Show Deposit Already Paid
    UI->>UI: Calculate Remaining Balance
    U->>UI: Collect Remaining Payment
    UI->>API: POST /special-orders/{id}/complete
    API->>DB: Status: COMPLETED

1.6.1 Special Order State Machine

stateDiagram-v2
    [*] --> CREATED: Order Initiated
    CREATED --> DEPOSIT_PAID: Deposit Received
    DEPOSIT_PAID --> ORDERED: Sent to Vendor
    ORDERED --> RECEIVED: Item Arrived at Store
    RECEIVED --> READY_FOR_PICKUP: Inspected & Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> ABANDONED: No Pickup (30+ days)

    CREATED --> CANCELLED: Customer Cancels (No Deposit)
    DEPOSIT_PAID --> CANCELLED_REFUND: Customer Cancels (Refund Deposit)

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    COMPLETED --> [*]
    ABANDONED --> [*]

1.6.2 Reports: Special Orders

Email Template: TMPL-SPECIAL-ORDER-READY

1.7 Multi-Store Inventory & Transfers

Scope: Cross-store inventory lookup, transfers, and reservations (requires full payment).

Cross-Reference: See Module 4, Section 4.8 for inter-store transfer details.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant S2 as Store B

    Note over U, S2: Multi-Store Inventory Check

    U->>UI: Search Product -> Low/No Stock
    U->>UI: Click "Check Other Stores"
    UI->>API: GET /inventory/multi-store/{sku}
    Note right of API: Eventually consistent (max 5 min stale)
    API-->>UI: Return Stock Levels (All Locations)

    UI-->>U: Display: "Store B: 5 units, Store C: 2 units"

    alt Request Transfer to This Store
        U->>UI: Select Store B -> "Request Transfer"
        UI->>UI: Enter Quantity
        UI-->>U: "Customer must pay in full to process"

        C->>U: Agrees to Pay
        U->>UI: Add Item to Cart (Status: TRANSFER_PENDING)
        U->>UI: Complete Full Payment

        UI->>API: POST /transfers/request
        API->>DB: Create Transfer Record (PAID)
        API->>S2: Notify Store B to Ship
        API-->>UI: Transfer #TRF-789 Created

        UI-->>U: "Item will arrive in 2-3 days"
        UI->>U: Print Transfer Receipt for Customer

    else Reserve at Other Store (Customer Pickup)
        U->>UI: Select Store B -> "Reserve for Pickup"
        UI-->>U: "Customer must pay in full to reserve"

        C->>U: Agrees to Pay
        U->>UI: Process Full Payment

        UI->>API: POST /reservations/create
        API->>DB: Create Reservation (PAID)
        API->>S2: Reserve Item at Store B
        API-->>UI: Reservation #RES-456 Created

        UI-->>U: "Reserved at Store B until [date]"
        UI->>U: Print Pickup Voucher for Customer
    end

    Note over S2, DB: Store B Fulfillment

    S2->>API: POST /transfers/{id}/picked
    API->>DB: Update Status: PICKING
    S2->>API: POST /transfers/{id}/shipped
    API->>DB: Update Status: SHIPPED
    Note right of DB: Carrier scan triggers IN_TRANSIT
    API-->>U: Notification: "Transfer Shipped"

1.7.1 Transfer State Machine

stateDiagram-v2
    [*] --> REQUESTED: Transfer Initiated
    REQUESTED --> PAID: Customer Paid in Full
    PAID --> PICKING: Source Store Processing
    PICKING --> SHIPPED: Handed to Carrier
    SHIPPED --> IN_TRANSIT: Carrier Scan Confirmed
    IN_TRANSIT --> RECEIVED: Arrived at Destination
    RECEIVED --> COMPLETED: Customer Notified & Picked Up

    REQUESTED --> CANCELLED: Cancelled Before Payment
    PAID --> CANCELLED_REFUND: Cancelled After Payment

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    COMPLETED --> [*]

1.7.2 Reservation State Machine

stateDiagram-v2
    [*] --> REQUESTED: Reservation Initiated
    REQUESTED --> PAID: Customer Paid in Full
    PAID --> RESERVED: Item Held at Store
    RESERVED --> PICKED_UP: Customer Collected
    RESERVED --> EXPIRED: Reservation Deadline Passed
    EXPIRED --> REFUND_PENDING: Auto-Refund Triggered
    REFUND_PENDING --> REFUNDED: Refund Processed

    REQUESTED --> CANCELLED: Cancelled Before Payment

    CANCELLED --> [*]
    PICKED_UP --> [*]
    REFUNDED --> [*]

1.7.3 Ship to Customer from Other Location

Scope: Direct shipping from a source store to the customer’s address, with carrier integration for real-time shipping cost calculation.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB
    participant S2 as Source Store
    participant SHIP as Carrier API

    Note over U, SHIP: Ship to Customer from Another Store

    U->>UI: Search Product -> Low/No Stock
    U->>UI: Click "Check Other Stores"
    UI->>API: GET /inventory/multi-store/{sku}
    API-->>UI: Return Stock Levels (All Locations)

    U->>UI: Select Source Store -> "Ship to Customer"
    UI-->>U: "Enter Customer Shipping Address"
    C->>U: Provides Shipping Address
    U->>UI: Enter Address Details

    UI->>API: POST /shipping/calculate
    Note right of API: {origin_store, destination_address, items, weight}
    API->>SHIP: Request Shipping Rates
    SHIP-->>API: Return Shipping Options
    API-->>UI: Display Shipping Options

    UI-->>U: "Standard (3-5 days): $8.99 | Express (1-2 days): $15.99"
    C->>U: Selects Shipping Option

    U->>UI: Add Item + Shipping to Cart
    UI->>UI: Total = Item Price + Shipping Cost
    UI-->>U: "Customer must pay in full"

    C->>U: Pays Full Amount (Item + Shipping)
    U->>UI: Process Payment

    UI->>API: POST /shipments/create
    API->>DB: Create Shipment Record (PAID)
    API->>S2: Notify Source Store to Pack & Ship
    API-->>UI: Shipment #SHP-101 Created

    UI-->>U: "Item will be shipped to customer"
    UI->>U: Print Shipment Receipt for Customer

    Note over S2, SHIP: Source Store Fulfillment

    S2->>API: POST /shipments/{id}/packed
    API->>DB: Update Status: PACKED
    S2->>SHIP: Request Shipping Label
    SHIP-->>S2: Return Label + Tracking Number
    S2->>API: POST /shipments/{id}/shipped {tracking_number}
    API->>DB: Update Status: SHIPPED
    API-->>C: Send Tracking Email to Customer

    Note over SHIP, DB: Delivery
    SHIP->>API: Webhook: Delivered
    API->>DB: Update Status: DELIVERED
    API-->>C: Send Delivery Confirmation Email

1.7.4 Ship-to-Customer State Machine

stateDiagram-v2
    [*] --> REQUESTED: Shipment Initiated
    REQUESTED --> PAID: Customer Paid (Item + Shipping)
    PAID --> PICKING: Source Store Processing
    PICKING --> PACKED: Items Packed
    PACKED --> SHIPPED: Label Generated & Handed to Carrier
    SHIPPED --> IN_TRANSIT: Carrier Pickup Confirmed
    IN_TRANSIT --> DELIVERED: Delivery Confirmed

    REQUESTED --> CANCELLED: Cancelled Before Payment
    PAID --> CANCELLED_REFUND: Cancelled After Payment (Full Refund)

    CANCELLED --> [*]
    CANCELLED_REFUND --> [*]
    DELIVERED --> [*]

1.7.5 Reports: Multi-Store & Shipping

Email Template: TMPL-SHIPMENT-TRACKING

Email Template: TMPL-DELIVERY-CONFIRMATION

1.8 Sales Commissions

Scope: Track employee sales for commission calculation with proportional reversal on returns.

Cross-Reference: See Module 5, Section 5.5 for user commission rate configuration.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Commission Tracking (Per Transaction)

    U->>UI: Login to POS (Employee ID Captured)

    Note right of UI: Throughout Sale...
    UI->>UI: Employee ID attached to session

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Commission Recording
        API->>DB: Calculate Commission Amount
        Note right of API: Based on: Sale Total, Product Categories, Employee Tier
        API->>DB: Insert Commission Record
        Note right of DB: {employee_id, order_id, amount, date, line_items[]}
    end

    Note over U, DB: Commission Reversal on Return

    U->>UI: Process Return (2 of 3 items)
    UI->>API: POST /returns/create

    par Proportional Reversal
        API->>DB: Calculate Return Value / Original Sale Value
        Note right of API: $80 returned / $120 sale = 66.7%
        API->>DB: Reverse 66.7% of Commission
        API->>DB: Update Commission Record
    end

    Note over U, DB: Commission Reporting

    U->>UI: Manager -> Reports -> Commissions
    UI->>API: GET /reports/commissions?date_range&employee
    API->>DB: Aggregate Commission Data
    API-->>UI: Return Commission Summary
    UI-->>U: Display: Employee | Sales | Returns | Net Commission

1.8.1 Commission Calculation Rules

commission_calculation:
  # Base calculation
  base_method: "percentage_of_sale"

  # Reversal rules
  void_reversal: "full"           # 100% reversal on void
  return_reversal: "proportional" # Based on returned value

  # Proportional calculation
  # Commission Adjustment = Original Commission × (Returned Value / Original Sale Value)

  # Example:
  # Original Sale: $120, Commission: $6.00 (5%)
  # Return: $80 worth of items
  # Reversal: $6.00 × ($80/$120) = $4.00
  # Net Commission: $6.00 - $4.00 = $2.00

1.8.2 Reports: Commissions

1.9 Return Policy Engine

Configuration Note: Store return and exchange policies are manually configured in the application’s Settings/Setup module. Policies are NOT hardcoded in the application. Each tenant can configure different policies per store location and per sales channel (online vs in-store).

Scope: Configurable return rules based on receipt, time, and item type.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Return Policy Evaluation

    U->>UI: Start Return

    alt Has Receipt
        U->>UI: Scan Receipt Barcode
        UI->>API: POST /receipts/validate {barcode_data}
        API->>DB: Verify receipt authenticity & match to order
        alt Receipt Valid
            API-->>UI: Receipt Verified
        else Receipt Invalid
            API-->>UI: "Invalid Receipt"
            UI-->>U: "Receipt validation failed"
        end
        UI->>API: GET /orders/{id}
        API-->>UI: Return Original Sale Data
        UI->>UI: Calculate Days Since Purchase

        alt Within 30 Days
            UI-->>U: "Full Refund Eligible"
            UI->>UI: Refund to Original Payment Method
        else 31-90 Days
            UI-->>U: "Store Credit Only"
            UI->>UI: Issue Store Credit
        else Beyond 90 Days
            UI-->>U: "Manager Approval Required"
            U->>UI: Enter Manager PIN
            U->>UI: Select Exception Reason
        end

    else No Receipt
        U->>UI: Scan Item Barcode
        UI->>API: GET /products/{sku}/current-price
        API-->>UI: Return Current Selling Price
        UI-->>U: "No Receipt - Store Credit at Current Price"
        UI-->>U: "Manager Approval Required"
        U->>UI: Enter Manager PIN
        UI->>UI: Issue Store Credit (Current Price)
    end

    alt Item-Specific Rules
        opt Final Sale Item
            UI-->>U: "BLOCKED: Final Sale - No Returns"
        end
        opt Opened Electronics
            UI-->>U: "Restocking Fee: 15%"
            UI->>UI: Deduct Restocking Fee
        end
    end

1.9.1 Default Policy Configuration Examples

Note: These are example default values only. Actual policies are configured per tenant in the application’s Settings/Setup module and are NOT hardcoded.

Online Sales Policy

In-Store Sales Policy

Policy Configuration Fields (Settings/Setup):

• Return window (days/hours per channel)
• Exchange window (days/hours per channel)
• Refund method options (original method, store credit, etc.)
• Restocking fee percentage and applicable categories
• Final sale categories
• Manager override permissions
• Online shipping/processing fee exclusion rules

1.9.2 Reports: Return Policy

1.10 Serial Number Tracking

Scope: Capture serial numbers for designated high-value items.

Cross-Reference: See Module 4, Section 4.10 for serial number tracking lifecycle.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Serial Number Capture at Sale

    U->>UI: Scan Product (Serial Required Flag)
    UI-->>U: "Enter Serial Number"
    U->>UI: Scan/Enter Serial Number

    UI->>API: POST /serials/validate
    alt Serial Already Sold
        API-->>UI: "ERROR: Serial already in system"
        UI-->>U: Block Item - Investigate
    else Serial Valid/New
        API-->>UI: Valid
        UI->>UI: Attach Serial to Line Item
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize
    API->>DB: Store Serial with Order Line
    Note right of DB: {order_id, line_id, serial_number, product_sku}

    Note over U, DB: Serial Lookup (Returns/Warranty)

    U->>UI: Search by Serial Number
    UI->>API: GET /serials/{number}
    API-->>UI: Return Purchase History
    UI-->>U: "Sold on [date] to [customer] - Order #123"

1.10.1 Reports: Serial Number Tracking

1.11 Hold for Pickup (Including BOPIS)

Scope: Fully paid items held for customer pickup at the CURRENT store. This includes both in-store holds and BOPIS (Buy Online, Pick Up In Store) orders. Different from Layaway (partial payment) and Reservation (item at another store).

Cross-Reference: See Module 4, Section 4.13 for inventory reservation model.

Reservation vs Hold for Pickup - Key Distinction:

Aspect	Reservation (Section 1.7.2)	Hold for Pickup (Section 1.11)
What it is	Reserve item at a DIFFERENT store for customer pickup	Pay for items at THIS store, pick up later
Origin	In-store POS (staff-initiated)	In-store POS or Online order (BOPIS)
Payment	Full payment at originating store	Full payment required upfront
Inventory location	At the remote store	At the current store
Customer picks up at	The remote store	The same store (or originating store for BOPIS)
BOPIS	No	Yes - this is the BOPIS flow
Use case	“Store B has it, I’ll drive there to get it”	“I’ll pay now, come back Saturday” or “Order online, pick up in store”

Examples:

Reservation Example: Customer is at Store A. Item is out of stock. Store B has 3 units. Customer pays at Store A. Item is reserved at Store B. Customer drives to Store B to pick it up with their pickup voucher.

Hold for Pickup Example 1 (In-Store): Customer at Store A buys a large piece of furniture. Pays in full. Asks store to hold it until Saturday when they can bring a truck. Store stages the item. Customer returns Saturday to pick up.

Hold for Pickup Example 2 (Online/BOPIS): Customer browses the online store. Selects “Pick Up at Store A.” Pays online. Store A receives the order, stages the items. Customer receives “Ready for Pickup” notification. Customer walks into Store A and picks up.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Hold for Pickup Flow

    U->>UI: Add Items to Cart
    U->>UI: Attach Customer
    U->>UI: Click "Hold for Pickup"

    UI->>UI: Set Pickup Deadline (Default: 7 days)
    UI-->>U: "Customer must pay in full"

    C->>U: Pays Full Amount
    U->>UI: Process Payment

    UI->>API: POST /orders/finalize
    API->>DB: Create Order (Status: HOLD_FOR_PICKUP)
    API->>DB: Set Pickup Deadline
    API->>DB: Reserve Inventory

    API-->>UI: Order Complete
    UI->>U: Print Pickup Slip

    Note over U, DB: Customer Returns to Pickup

    U->>UI: Retrieve Held Order
    UI->>API: GET /orders/held/{id}
    API-->>UI: Display Order Details
    U->>UI: Verify Customer ID
    U->>UI: Click "Release to Customer"

    UI->>API: PATCH /orders/{id}/pickup-complete
    API->>DB: Status: COMPLETED
    API->>DB: Release Inventory Hold

    Note over API, DB: Expiry Handling (Background Job)

    API->>DB: Check Overdue Holds Daily
    alt Hold Expired
        API->>DB: Status: HOLD_EXPIRED
        API-->>U: Alert: "Hold #123 expired - contact customer"
    end

1.11.1 Hold for Pickup State Machine

stateDiagram-v2
    [*] --> HOLD_FOR_PICKUP: Full Payment + Hold Request
    HOLD_FOR_PICKUP --> READY_FOR_PICKUP: Items Staged
    READY_FOR_PICKUP --> COMPLETED: Customer Picked Up
    READY_FOR_PICKUP --> HOLD_EXPIRED: Deadline Passed
    HOLD_EXPIRED --> CONTACT_CUSTOMER: Staff Notified
    CONTACT_CUSTOMER --> READY_FOR_PICKUP: Deadline Extended
    CONTACT_CUSTOMER --> REFUNDED: Customer Wants Refund

    REFUNDED --> [*]
    COMPLETED --> [*]

1.12 Cash Drawer Management

Scope: Opening float, blind counts, variance tracking, X-reports (mid-shift), and Z-reports (end-of-shift).

Cross-Reference: See Module 5, Section 5.7 for register configuration and Section 5.6 for clock-in/clock-out time tracking.

sequenceDiagram
    autonumber
    participant U as Staff
    participant M as Manager
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Shift Start - Open Drawer

    M->>UI: Open Cash Drawer Session
    M->>UI: Enter Opening Float Amount
    UI->>API: POST /cash-drawer/open
    API->>DB: Create Drawer Session (opening_float, start_time)
    API-->>UI: Drawer Session Started

    Note over U, DB: During Shift - Transactions

    loop Cash Transactions
        U->>UI: Process Cash Sale/Refund
        UI->>DB: Record Cash In/Out
    end

    opt Mid-Shift Check (X-Report)
        U->>UI: Click "X-Report"
        UI->>API: GET /cash-drawer/x-report
        API->>DB: Calculate Current Expected Amount
        Note right of API: Expected = Float + Cash Sales So Far - Cash Refunds - Payouts
        API-->>UI: Return X-Report Data
        UI->>U: Print/Display X-Report
        Note right of UI: X-Report does NOT close the drawer
        Note right of UI: Can be run multiple times per shift
    end

    Note over U, DB: Shift End - Close Drawer

    U->>UI: Click "Close Drawer"
    UI-->>U: "Perform Blind Count"

    U->>UI: Enter Counted Cash (Blind - no expected shown)
    UI->>API: POST /cash-drawer/count

    API->>DB: Calculate Expected Amount
    Note right of API: Expected = Float + Cash Sales - Cash Refunds - Payouts
    API->>DB: Calculate Variance (Counted - Expected)

    alt Variance Within Tolerance
        API-->>UI: "Drawer Balanced"
    else Variance Outside Tolerance
        API-->>UI: "Variance: -$5.00 - Manager Approval Required"
        M->>UI: Enter PIN + Variance Reason
    end

    API->>DB: Close Drawer Session
    API->>DB: Record Final Counts & Variance

    UI->>U: Print Z-Report

    Note over M, DB: Z-Report Contents
    Note right of UI: - Opening Float
    Note right of UI: - Cash Sales Total
    Note right of UI: - Cash Refunds Total
    Note right of UI: - Expected Cash
    Note right of UI: - Counted Cash
    Note right of UI: - Variance (+/-)
    Note right of UI: - Transaction Count

1.12.1 Cash Drawer State Machine

stateDiagram-v2
    [*] --> CLOSED: Drawer Secured
    CLOSED --> OPENING: Manager Opens
    OPENING --> OPEN: Float Entered
    OPEN --> OPEN: Transactions Processed
    OPEN --> COUNTING: Close Initiated
    COUNTING --> BALANCED: Variance Within Tolerance
    COUNTING --> VARIANCE_DETECTED: Variance Outside Tolerance
    VARIANCE_DETECTED --> MANAGER_REVIEW: Awaiting Approval
    MANAGER_REVIEW --> BALANCED: Manager Approved
    BALANCED --> CLOSED: Z-Report Printed

    CLOSED --> [*]

1.12.2 X-Report vs Z-Report

X-Report Use Cases:

• Manager wants to verify cash during a busy period
• Shift handoff between employees (outgoing staff checks before handing off)
• Routine mid-day audit required by store policy
• Investigating a suspected cash handling issue

1.12.3 Reports: Cash Drawer

1.13 Price Check Mode

Scope: Quick price lookup without adding to cart.

sequenceDiagram
    autonumber
    participant U as Staff
    participant C as Customer
    participant UI as POS UI
    participant API as Backend

    C->>U: "How much is this?"

    U->>UI: Click "Price Check" Mode
    UI->>UI: Switch to Price Check Display

    U->>UI: Scan Item Barcode
    UI->>API: GET /products/{sku}
    API-->>UI: Return Product Info

    UI-->>U: Display Large Price
    UI-->>U: Show: Name, SKU, Price, Stock Level

    opt Promotion Active
        UI-->>U: "ON SALE: Was $50, Now $39.99"
    end

    U->>UI: Press Any Key / Timeout
    UI->>UI: Return to Normal Sale Mode

1.14 Coupon System

Scope: Single-use and multi-use coupons (separate from promo codes).

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Coupon Application

    U->>UI: Click "Apply Coupon"
    U->>UI: Scan/Enter Coupon Code

    UI->>API: POST /coupons/validate
    API->>DB: Lookup Coupon

    alt Single-Use Coupon (e.g., Birthday)
        API->>DB: Check if Already Redeemed
        alt Already Used
            API-->>UI: "Coupon Already Redeemed"
        else Valid
            API-->>UI: Return Discount Details
        end

    else Multi-Use Coupon (e.g., SAVE10)
        API->>DB: Check Usage Limit & Expiry
        API-->>UI: Return Discount Details
    end

    alt Valid Coupon
        UI->>UI: Apply Discount
        UI->>UI: Display Savings
        Note right of UI: Coupon marked for redemption at finalize
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Coupon Processing
        API->>DB: Mark Single-Use Coupon as REDEEMED
        API->>DB: Increment Multi-Use Coupon Counter
        API->>DB: Link Coupon to Order
    end

1.14.1 Coupon State Machine

stateDiagram-v2
    [*] --> CREATED: Coupon Generated
    CREATED --> ACTIVE: Published/Distributed

    state ACTIVE {
        [*] --> AVAILABLE
        AVAILABLE --> APPLIED: Added to Cart
        APPLIED --> AVAILABLE: Removed from Cart
        APPLIED --> REDEEMED: Order Finalized
    }

    ACTIVE --> EXPIRED: Past Expiry Date
    ACTIVE --> DEPLETED: Usage Limit Reached (Multi-Use)
    REDEEMED --> [*]: Single-Use Complete
    EXPIRED --> [*]
    DEPLETED --> [*]

1.15 Flexible Loyalty Programs

Scope: Configurable loyalty: points-per-dollar, punch cards, spend thresholds.

Cross-Reference: See Module 5, Section 5.17 for loyalty program settings configuration (point rates, tier thresholds, gift card settings).

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Loyalty Program Types

    U->>UI: Attach Customer to Sale
    UI->>API: GET /customers/{id}/loyalty
    API-->>UI: Return Loyalty Profile & Active Programs

    alt Points Per Dollar Program
        Note right of UI: Earn 1 point per $1 spent
        UI->>UI: Calculate Points to Earn
        UI-->>U: "Customer earns 45 points"

        opt Redeem Points
            U->>UI: Click "Redeem Points"
            UI-->>U: "500 points = $5 off"
            U->>UI: Apply Redemption
        end

    else Punch Card Program
        Note right of UI: Buy 10, Get 1 Free
        UI->>UI: Check Qualifying Items in Cart
        UI-->>U: "Coffee Purchase: Punch 3 of 10"

        opt Card Complete
            UI-->>U: "FREE ITEM EARNED!"
            UI->>UI: Auto-Apply Free Item Discount
        end

    else Spend Threshold Program
        Note right of UI: Spend $100, Get $10 Off
        UI->>UI: Check Customer's Period Spend
        UI-->>U: "Customer has spent $85 this month"

        opt Threshold Reached This Sale
            UI-->>U: "$10 Reward Unlocked!"
            UI->>UI: Apply or Save for Next Visit
        end
    end

    U->>UI: Complete Sale
    UI->>API: POST /orders/finalize

    par Loyalty Updates
        API->>DB: Award Points Earned
        API->>DB: Update Punch Card Count
        API->>DB: Update Spend Totals
        API->>DB: Check Tier Upgrades
    end

1.15.1 Customer Tier State Machine

stateDiagram-v2
    [*] --> BRONZE: New Customer
    BRONZE --> SILVER: Spend >= $1,000/year
    SILVER --> GOLD: Spend >= $5,000/year
    GOLD --> GOLD: Maintains Spend
    GOLD --> SILVER: Annual Spend < $5,000
    SILVER --> BRONZE: Annual Spend < $1,000

    note right of BRONZE
        1x points
        Standard pricing
    end note

    note right of SILVER
        1.5x points
        5% discount
    end note

    note right of GOLD
        2x points
        10% discount
        Early access
    end note

1.15.2 Reports: Loyalty Programs

1.16 Offline Operations

Scope: Queue-and-sync architecture for network resilience.

Cross-Reference: See Module 4, Section 4.15 for offline inventory operations.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant Q as Local Queue
    participant API as Backend
    participant DB as DB

    Note over U, DB: Network Loss Detected

    UI->>UI: Detect Network Unavailable
    UI-->>U: Display "OFFLINE MODE" Indicator

    Note over U, Q: Processing Sales Offline

    U->>UI: Process Sale
    UI->>Q: Queue Transaction Locally
    Note right of Q: Store: items, customer_id, payments, timestamp
    Q-->>UI: Transaction Queued (#1)
    UI-->>U: "Sale Complete (Pending Sync)"
    UI->>U: Print Receipt with "OFFLINE" watermark

    loop Continue Offline Sales
        U->>UI: Process More Sales
        UI->>Q: Queue Each Transaction
        UI-->>U: Show Queue Count (e.g., "3 pending")
    end

    Note over UI, DB: Network Restored

    UI->>UI: Detect Network Available
    UI-->>U: Display "SYNCING..." Indicator

    loop Sync Queue
        Q->>API: POST /orders/sync
        API->>DB: Validate & Write

        alt Conflict: Item Out of Stock
            API-->>UI: Conflict Detected
            UI-->>U: Alert: "Item X sold out - review order #1"
            Note right of UI: Flag for manager review
        else Success
            API-->>UI: Synced
            Q->>Q: Remove from Queue
        end
    end

    UI-->>U: "All transactions synced"

1.16.1 Offline Mode State Machine

stateDiagram-v2
    [*] --> ONLINE: Network Available
    ONLINE --> OFFLINE: Network Lost
    OFFLINE --> SYNCING: Network Restored
    SYNCING --> ONLINE: Queue Empty
    SYNCING --> CONFLICT_REVIEW: Conflicts Detected
    CONFLICT_REVIEW --> SYNCING: Conflicts Resolved
    CONFLICT_REVIEW --> ONLINE: Manager Override

    note right of OFFLINE
        Queue transactions locally
        Limited operations only
    end note

    note right of SYNCING
        Processing queue
        Show progress
    end note

1.16.2 Offline Operations Rules

offline_mode:
  # Maximum transactions to queue locally
  max_queue_size: 100

  # Auto-sync interval when online (seconds)
  sync_interval_seconds: 30

  # Conflict resolution strategy
  conflict_strategy: "server_wins_with_review"

  # Operations ALLOWED offline
  allowed_offline:
    - sale_new
    - return_with_receipt
    - price_check
    - gift_card_balance_check  # Cached balance, show warning
    - parked_sale_create
    - parked_sale_retrieve

  # Operations BLOCKED offline
  blocked_offline:
    - customer_create          # Requires uniqueness check
    - credit_limit_check       # Requires real-time balance
    - on_account_payment       # Risk of exceeding limit
    - multi_store_inventory    # Requires network
    - gift_card_activation     # Must register immediately
    - gift_card_reload         # Risk of double-load
    - transfer_request         # Requires other store
    - reservation_create       # Requires other store

  # Gift card handling offline
  gift_card_offline:
    balance_check: "use_cached"  # Show cached with warning
    redemption: "block"          # Too risky - balance could be stale

  # Inventory conflict handling
  inventory_conflict:
    # If offline sale sold item that's now out of stock
    resolution: "manager_review"
    auto_backorder: false

1.16.3 Offline Sync Conflict Resolution

1.16.4 Offline Conflict Email Templates

When the system comes back online and discovers that a Transfer, Ship-to-Customer, or Reservation request cannot be fulfilled because the item was sold from the source location during the offline period, the system must automatically notify the customer.

Email Template: TMPL-OFFLINE-SOLD (Item Availability Change Notification)

Offline Conflict Notification Rules:

offline_conflict_notifications:
  # Notify customer when item sold from source location
  item_sold_at_source:
    notify_customer: true
    email_template: "TMPL-OFFLINE-SOLD"
    fallback_if_no_email: "staff_alert"
    # Staff alert appears in manager dashboard
    staff_alert_priority: "high"

1.17 Tax Calculation Engine

Scope: Custom tax engine with jurisdiction support, hierarchy rules, and exemptions.

Cross-Reference: See Module 5, Section 5.9 for tax jurisdiction setup, compound rate configuration (State/County/City), and rate assignment per location.

sequenceDiagram
    autonumber
    participant UI as POS UI
    participant API as Backend
    participant TAX as Tax Engine
    participant DB as DB

    Note over UI, DB: Tax Calculation Flow

    UI->>API: Calculate Tax for Cart
    API->>TAX: Submit Cart + Store Location + Customer

    TAX->>DB: Get Store Tax Jurisdiction
    Note right of DB: Store in Virginia: State 4.3% + Local 1%

    TAX->>DB: Get Customer Tax Status
    Note right of DB: Customer: Regular (no exemption)

    loop For Each Line Item
        TAX->>DB: Get Product Tax Category

        alt Product Override (e.g., Food)
            TAX->>TAX: Apply Product Tax Rate (0% for groceries)
        else Customer Exempt
            TAX->>TAX: Apply 0% Tax
        else Standard
            TAX->>TAX: Apply Jurisdiction Rate (5.3%)
        end
    end

    TAX-->>API: Return Tax Breakdown
    API-->>UI: Display Tax Summary

    Note right of UI: Tax Breakdown:
    Note right of UI: State Tax (4.3%): $4.30
    Note right of UI: Local Tax (1.0%): $1.00
    Note right of UI: Total Tax: $5.30

1.17.1 Tax Hierarchy (Priority Order)

1. Product-Level Override (Highest Priority)
   └── Example: "Grocery - Tax Exempt", "Prepared Food - 10%"

2. Customer-Level Exemption
   └── Example: "Reseller Certificate", "Diplomatic Status", "Non-Profit"

3. Location-Based Tax (Default)
   └── Based on store physical address
   └── Includes: State + County + City + Special District

1.17.2 Virginia Tax Configuration

tax_jurisdictions:
  virginia:
    state_rate: 4.3

    # Regional taxes (in addition to state)
    regions:
      hampton_roads:
        counties: ["Norfolk", "Virginia Beach", "Newport News", "Hampton"]
        additional_rate: 0.7

      northern_virginia:
        counties: ["Arlington", "Fairfax", "Loudoun", "Prince William"]
        additional_rate: 0.7

      central_virginia:
        counties: ["Henrico", "Chesterfield", "Richmond City"]
        additional_rate: 0.0

    # Local tax (most localities)
    default_local_rate: 1.0

    # Product exemptions
    exemptions:
      - category: "grocery_food"
        rate: 1.5  # Reduced rate for groceries
      - category: "prescription_drugs"
        rate: 0.0
      - category: "medical_equipment"
        rate: 0.0

tax_exemption_types:
  - code: "RESALE"
    description: "Reseller Certificate"
    requires_certificate: true
    certificate_expiry: true

  - code: "NONPROFIT"
    description: "501(c)(3) Non-Profit"
    requires_certificate: true
    certificate_expiry: true

  - code: "DIPLOMAT"
    description: "Diplomatic Exemption"
    requires_certificate: true
    certificate_expiry: false

  - code: "NATIVE"
    description: "Native American Tribal Member"
    requires_certificate: true
    certificate_expiry: false

1.17.3 Tax Engine Design for Expansion

Note: The Virginia compound tax jurisdiction model is the active reference implementation. See Section 5.9 for the tax_jurisdictions and tax_rates tables that implement the 3-level compound model (State + County + City).

jurisdiction_modules:
  virginia:
    status: "active"           # Reference implementation
    model: "compound_3_level"  # State + County/Regional + City
    sales_tax: true
    use_tax: false

  california:
    status: "planned"
    sales_tax: true
    district_taxes: true  # Complex district overlay

  oregon:
    status: "planned"
    sales_tax: false  # No sales tax state

  canada:
    status: "planned"
    gst: true
    pst: true  # Varies by province
    hst: true  # Harmonized in some provinces

  european_union:
    status: "planned"
    vat: true
    reverse_charge: true  # B2B cross-border

1.18 Payment Integration (SAQ-A)

Scope: Semi-integrated payment terminal architecture with PCI SAQ-A compliance.

Cross-Reference: Payment data storage rules, terminal communication protocol, processor configuration, and failure handling details have been consolidated into Module 6, Section 6.8. The payment flow sequence diagram below remains in this section as it is part of the core sales workflow.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Your Backend
    participant TERM as Payment Terminal
    participant PROC as Payment Processor

    Note over U, PROC: Card Payment Flow (SAQ-A)

    U->>UI: Click "Pay by Card"
    UI->>API: POST /payments/initiate
    Note right of API: {order_id, amount, terminal_id}

    API->>TERM: Send Payment Request
    Note right of TERM: Amount: $45.00

    TERM-->>U: "Insert/Tap Card"
    Note over TERM: Customer interacts with terminal only

    U->>TERM: Customer taps card
    TERM->>PROC: Encrypted Card Data
    Note right of PROC: Card data NEVER touches your system

    PROC-->>TERM: Authorization Response
    TERM-->>API: Token + Approval Code + Masked Card

    API->>API: Store Token (NOT card data)
    Note right of API: Stored: token, approval_code, ****1234, VISA

    API-->>UI: Payment Approved
    UI-->>U: "Approved - $45.00"

    Note over U, PROC: Refund Flow (Using Token)

    U->>UI: Process Refund
    UI->>API: POST /refunds/create
    Note right of API: {order_id, amount, reason}

    API->>API: Retrieve Stored Token
    API->>PROC: Refund Request with Token
    PROC-->>API: Refund Approved

    API-->>UI: Refund Complete

1.18.1 Payment Data Storage Rules

payment_data:
  # Data your system STORES
  stored:
    - transaction_id        # Your internal ID
    - payment_token         # Processor token for refunds
    - approval_code         # Authorization code
    - masked_card_number    # Last 4 digits only (****1234)
    - card_brand            # Visa, Mastercard, Amex, Discover
    - entry_method          # chip, tap, swipe, manual
    - terminal_id           # Which terminal processed
    - timestamp             # When processed
    - amount                # Transaction amount

  # Data your system NEVER stores (PCI prohibited)
  prohibited:
    - full_card_number      # 16-digit PAN
    - cvv_cvc               # Security code
    - track_data            # Magnetic stripe data
    - pin_block             # Encrypted PIN
    - emv_data              # Chip cryptogram (raw)

1.18.2 Terminal Communication

terminal_integration:
  protocol: "cloud_api"  # Terminal vendor's cloud service

  # Timeout settings
  payment_timeout_seconds: 60
  connection_timeout_seconds: 10

  # Terminal states
  states:
    - IDLE: "Ready for transaction"
    - WAITING_FOR_CARD: "Display amount, await tap/insert"
    - PROCESSING: "Communicating with processor"
    - APPROVED: "Transaction successful"
    - DECLINED: "Transaction declined"
    - ERROR: "Communication or hardware error"
    - CANCELLED: "Customer or staff cancelled"

  # Error handling
  on_timeout: "prompt_retry_or_cancel"
  on_decline: "display_reason_allow_retry"
  on_error: "log_and_alert_manager"

  # Void window (same-day before batch)
  same_day_void: true
  batch_close_time: "23:00"  # Auto-batch at 11 PM

1.18.3 Payment Terminal Failure Handling

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant TERM as Payment Terminal

    U->>UI: Click "Pay by Card"
    UI->>API: POST /payments/initiate
    API->>TERM: Send Payment Request

    alt Terminal Timeout
        TERM--xAPI: No Response (60s)
        API-->>UI: "Terminal not responding"
        UI-->>U: Options: Retry | Different Terminal | Cash | Cancel

    else Terminal Declined
        TERM-->>API: Declined (Insufficient Funds)
        API-->>UI: "Card Declined: Insufficient Funds"
        UI-->>U: Options: Try Another Card | Cash | Cancel

    else Terminal Error
        TERM-->>API: Error (Hardware Issue)
        API-->>UI: "Terminal Error"
        UI-->>U: Options: Different Terminal | Cash | Cancel
        API->>API: Log Error, Alert Manager
    end

1.18.4 Reports: Payment Integration

1.19 Sales User Stories (Epics)

Epic 1.A: Core Sales & Inventory

• Story 1.A.1 (Hybrid Entry): Staff can add items via Scanner (bulk array, max 50 tags) or Barcode (single SKU), with immediate stock validation.
• Story 1.A.2 (Parking): Staff can “Park” a sale (max 5 per terminal, 4-hour TTL) to serve another customer and “Retrieve” it later. Parked items soft-reserve inventory.
• Story 1.A.3 (Mixed Cart): A single transaction can contain both Sales (positive price) and Returns (negative price), calculating a Net Total.
• Story 1.A.4 (Inventory Checks): System validates stock > 0 before adding to cart. Returns trigger INCREMENT stock event; Sales trigger DECREMENT.
• Story 1.A.5 (Price Check Mode): Staff can scan items in “Price Check” mode to display price without adding to cart. Useful for customer inquiries.

Epic 1.B: Pricing & Promotion

• Story 1.B.1 (Smart Promos): The system alerts staff (“Upsell Opportunity”) when a cart is eligible for a promo (e.g., “Buy 2 Get 1 Free”).
• Story 1.B.2 (Granular Discounts): Line-item discounts apply before global discounts. Manager PIN is required for overrides above a certain %.
• Story 1.B.3 (Discount Stacking): System prevents invalid stacking (e.g., cannot use Promo Code on “Clearance” items).
• Story 1.B.4 (Price Tiers): Customers can be assigned price tiers (Retail, Wholesale, VIP, Employee) that apply different base prices before any discounts.
• Story 1.B.5 (Coupon System): System supports both single-use coupons (birthday, referral) and multi-use coupons (promotional codes). Single-use coupons are marked redeemed after use.
• Story 1.B.6 (Discount Order): Discounts apply in strict order: Price Tier → Line Discounts → Auto Promos → Global % → Coupons → Tax → Loyalty Redemptions. Loyalty redemptions apply after tax calculation.

Epic 1.C: Payments & Financials

• Story 1.C.1 (On-Account): Trusted customers can buy on credit. System validates Current Debt + Pending Layaways + Cart <= Credit Limit. Paying off debt requires Cash/Card (prevents circular credit).
• Story 1.C.2 (Layaway): Customers can reserve items with a partial deposit. Inventory is reserved immediately (Status: RESERVED), but revenue is not fully recognized until completion.
• Story 1.C.3 (Split Tender): Transactions support mixed payments (e.g., $20 Cash + Remaining on Card). Customers can use multiple credit cards and combine cash + card(s) in any combination. Each card’s token is stored separately for refund processing.
• Story 1.C.4 (Gift Cards): Staff can sell gift cards, reload existing cards, check balances, and accept gift cards as payment. Partial redemption is supported. Jurisdiction rules apply.
• Story 1.C.5 (Cash Drawer Management): Each shift requires opening float entry, blind cash counts at close, variance tracking, X-report (mid-shift) and Z-report (end-of-shift) generation. Variances outside tolerance require manager approval.
• Story 1.C.6 (Credit Card Payments - SAQ-A): Card payments use semi-integrated terminals. Card data never touches our system. Only tokens, approval codes, and masked card numbers are stored.
• Story 1.C.7 (Payment Failures): When terminal times out, declines, or errors, staff can retry, switch terminals, accept cash, or cancel. All failures are logged.
• Story 1.C.8 (Third-Party Financing - Affirm): Staff can offer Affirm as a payment option. Customer completes financing on their device. Store receives full payment from Affirm immediately. Customer repays Affirm per their loan terms.
• Story 1.C.9 (Multiple Payment Methods): Customers can split payment across multiple credit cards or combine cash + card(s). System tracks each card’s token separately for individual refund processing.

Epic 1.D: Post-Sale & Data

• Story 1.D.1 (Voiding): Voiding is only allowed same business day with drawer open. Voiding reverses inventory, loyalty, and commissions (full reversal). Record is flagged VOIDED, not deleted.
• Story 1.D.2 (Returns): Returns require staff to scan the receipt for system validation before processing. Commission is reversed proportionally based on returned value. Refunds use stored payment tokens or manual terminal processing (staff chooses).
• Story 1.D.3 (Receipts): Staff can choose between Thermal (standard), A4 (invoice), or Gift Receipts (hidden price) at print time.
• Story 1.D.4 (Receipt Reprint): Staff can reprint any historical receipt or email to a different address.
• Story 1.D.5 (History & Export): Managers can filter history by Date/User/Status and export to CSV (limit 1,000 rows for performance).
• Story 1.D.6 (Return Policy Engine): System enforces return and exchange policies that are manually configured in the application’s Settings/Setup module. Policies are per-tenant, per-store, and per-channel (online vs in-store). Example defaults: 30 days full refund with receipt, 31-90 days store credit, no receipt = store credit at current price with manager approval.
• Story 1.D.7 (Dedicated Exchanges): Staff can process exchanges as a single transaction showing item out, item in, and price difference. Exchange records link the original and new items. Commission adjusts for price difference.

Epic 1.E: Special Orders & Transfers

• Story 1.E.1 (Special Orders): Staff can create special orders for out-of-stock items. Customer pays deposit (minimum 50% or configurable). System tracks order status and notifies customer on arrival.
• Story 1.E.2 (Multi-Store Inventory): Staff can view inventory at all store locations (eventually consistent, max 5 min stale). Can request transfers or reserve items at other stores for customer pickup.
• Story 1.E.3 (Transfer/Reserve Payment): Transfers and reservations require customer to pay in full before the request is submitted to the system. This prevents unpaid phantom requests.
• Story 1.E.4 (Hold for Pickup): Fully paid orders can be held for customer pickup with a configurable time limit (default 7 days). System alerts staff when holds expire.
• Story 1.E.5 (Ship to Customer): Staff can ship items from other store locations directly to the customer’s address. System integrates with carrier APIs to calculate real-time shipping costs based on origin store and destination address. Customer pays item price + shipping in full before shipment is initiated. Tracking number is shared with customer via email.

Epic 1.F: Tracking & Commissions

• Story 1.F.1 (Serial Numbers): Designated products require serial number capture at sale. System validates serial hasn’t been previously sold. Serial numbers are searchable for warranty/return lookup.
• Story 1.F.2 (Sales Commissions): Each transaction records the employee ID. Commission amounts are calculated based on sale total and stored for reporting.
• Story 1.F.3 (Commission Reversal): Voided sales reverse commission fully. Returns reverse commission proportionally (returned value / original sale value).
• Story 1.F.4 (Commission Reports): Managers can view commission reports by date range and employee, showing total sales, returns, and net commission earned.

Epic 1.G: Loyalty Programs

• Story 1.G.1 (Points Program): Customers earn points per dollar spent. Points can be redeemed for discounts at configurable rates (e.g., 100 points = $1).
• Story 1.G.2 (Punch Cards): Digital punch cards track qualifying purchases (e.g., 10 coffees = 1 free). Punches are automatically applied based on product categories.
• Story 1.G.3 (Spend Thresholds): Customers earn rewards when spending thresholds are met (e.g., spend $100/month, get $10 off). Rewards can be auto-applied or saved.
• Story 1.G.4 (Loyalty Tiers): Customers automatically upgrade tiers (Bronze → Silver → Gold) based on spend. Higher tiers earn more points or get better rewards.

Epic 1.H: Offline & Resilience

• Story 1.H.1 (Offline Detection): System automatically detects network loss and switches to offline mode with clear visual indicator.
• Story 1.H.2 (Offline Sales): Staff can process sales, returns with receipt, and price checks while offline. Transactions queue locally (max 100).
• Story 1.H.3 (Blocked Offline): System blocks risky operations offline: new customer creation, credit checks, gift card activation/reload, multi-store operations.
• Story 1.H.4 (Auto Sync): When network restores, system automatically syncs queued transactions. Conflicts are flagged for manager review.
• Story 1.H.5 (Conflict Resolution): Manager can review sync conflicts (out of stock, price changes) and approve, modify, or cancel affected transactions.

Epic 1.I: Tax Calculation

• Story 1.I.1 (Jurisdiction Taxes): System calculates tax based on store physical address, applying state + county + city + district rates as applicable.
• Story 1.I.2 (Tax Hierarchy): Product-level tax overrides take priority over customer exemptions, which take priority over default store rates.
• Story 1.I.3 (Tax Exemptions): Customers with valid exemption certificates (resale, non-profit, diplomatic) can be flagged for tax-exempt purchases.
• Story 1.I.4 (Tax Display): Receipt shows tax breakdown by jurisdiction (State Tax: $X, Local Tax: $Y).

1.20 Sales Acceptance Criteria (Gherkin)

Feature: Gift Card Operations

Feature: Gift Card Management
  As a retail staff member
  I need to sell, reload, and redeem gift cards
  So that customers can purchase and use store credit

  Background:
    Given I am logged into the POS system
    And the cash drawer is open

  Scenario: Sell a new gift card
    Given I have a physical gift card with number "GC-000000001234"
    And the gift card status is "INACTIVE"
    When I scan the gift card
    And I enter load amount "$50.00"
    And the customer pays "$50.00"
    Then the gift card status should be "ACTIVE"
    And the gift card balance should be "$50.00"
    And a receipt should print showing "Gift Card Activated: $50.00"

  Scenario: Check gift card balance
    Given a gift card "GC-000000001234" with balance "$35.50"
    When I click "Gift Card Balance"
    And I scan the gift card
    Then the display should show "Balance: $35.50"
    And the display should show expiry info based on jurisdiction

  Scenario: Partial redemption
    Given a gift card "GC-000000001234" with balance "$50.00"
    And a cart total of "$30.00"
    When I apply the gift card as payment
    Then the gift card balance should become "$20.00"
    And the order should be marked "PAID"
    And the gift card status should remain "ACTIVE"

  Scenario: Full redemption depletes card
    Given a gift card "GC-000000001234" with balance "$25.00"
    And a cart total of "$25.00"
    When I apply the gift card as payment
    Then the gift card balance should become "$0.00"
    And the gift card status should be "DEPLETED"

  Scenario: Insufficient balance prompts partial
    Given a gift card "GC-000000001234" with balance "$20.00"
    And a cart total of "$50.00"
    When I apply the gift card as payment
    Then the system should display "Card Balance: $20.00. Apply partial?"
    When I confirm partial application
    Then "$20.00" should be applied from the gift card
    And remaining balance should show "$30.00"

  Scenario: Reload existing gift card
    Given a gift card "GC-000000001234" with balance "$10.00"
    When I scan the gift card
    And I select "Reload"
    And I enter reload amount "$25.00"
    And the customer pays "$25.00"
    Then the gift card balance should be "$35.00"

  Scenario: Cash out in California
    Given the store is located in California
    And a gift card "GC-000000001234" with balance "$8.50"
    When I scan the gift card
    Then the system should show "Eligible for Cash Out: $8.50"
    When I process cash out
    Then the gift card balance should be "$0.00"
    And "$8.50" cash should be given to customer

Feature: Exchange Transactions

Feature: Dedicated Exchange Flow
  As a retail staff member
  I need to process exchanges efficiently
  So that customers can swap items in a single transaction

  Background:
    Given I am logged into the POS system
    And order "ORD-001" exists with item "Blue Shirt" at "$40.00"
    And the original sale had commission "$2.00"

  Scenario: Even exchange - same price items
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" to exchange OUT
    And I scan "Red Shirt" priced at "$40.00" to exchange IN
    Then the price difference should show "$0.00"
    And I should see "Even Exchange - No Payment Required"
    When I complete the exchange
    Then a new exchange record should link "ORD-001" to the new order
    And inventory for "Blue Shirt" should INCREMENT by 1
    And inventory for "Red Shirt" should DECREMENT by 1
    And commission should remain unchanged

  Scenario: Customer owes money - upgrade
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" ($40.00) to exchange OUT
    And I scan "Premium Jacket" priced at "$80.00" to exchange IN
    Then the price difference should show "Customer Owes: $40.00"
    When the customer pays "$40.00"
    And I complete the exchange
    Then the exchange should be recorded successfully
    And additional commission should be recorded for the $40.00 difference

  Scenario: Store owes refund - downgrade
    Given I load order "ORD-001" for exchange
    When I select "Blue Shirt" ($40.00) to exchange OUT
    And I scan "Basic Tee" priced at "$25.00" to exchange IN
    Then the price difference should show "Refund to Customer: $15.00"
    When I process the refund
    And I complete the exchange
    Then "$15.00" should be refunded to original payment method
    And commission should be reduced proportionally

Feature: Multi-Store Transfer (Full Payment Required)

Feature: Multi-Store Inventory Transfer
  As a retail staff member
  I need to request transfers from other stores
  So that customers can get items not available locally

  Background:
    Given I am logged into POS at "Store A"
    And "Store B" has 5 units of "SKU-12345"
    And "Store A" has 0 units of "SKU-12345"

  Scenario: Transfer request requires full payment
    Given a customer wants "SKU-12345" priced at "$75.00"
    When I search for "SKU-12345"
    And I click "Check Other Stores"
    Then I should see "Store B: 5 units"
    And I should see "Last updated: X minutes ago"
    When I click "Request Transfer" from "Store B"
    Then I should see "Customer must pay in full to process"
    When the customer pays "$75.00"
    Then a transfer record should be created with status "PAID"
    And "Store B" should receive a transfer notification
    And I should print a transfer receipt for the customer

  Scenario: Transfer blocked without payment
    Given a customer wants "SKU-12345" priced at "$75.00"
    When I click "Request Transfer" from "Store B"
    And the customer declines to pay
    Then no transfer record should be created
    And "Store B" inventory should remain unchanged

  Scenario: Reservation at other store requires full payment
    Given a customer wants to pick up "SKU-12345" at "Store B"
    When I click "Reserve at Store B"
    Then I should see "Customer must pay in full to reserve"
    When the customer pays "$75.00"
    Then a reservation should be created at "Store B"
    And the customer should receive a pickup voucher
    And the reservation should expire in 7 days

Feature: Return Policy Engine

Feature: Return Policy Enforcement
  As a retail staff member
  I need the system to enforce return policies
  So that returns are handled consistently

  Scenario: Full refund within 30 days with receipt
    Given order "ORD-001" was placed 15 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Full Refund Eligible"
    And the refund should go to the original payment method
    And commission should be reversed proportionally

  Scenario: Store credit for 31-90 days
    Given order "ORD-001" was placed 45 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Store Credit Only"
    And I should issue store credit for the return amount

  Scenario: Manager override required beyond 90 days
    Given order "ORD-001" was placed 120 days ago
    And the customer has the receipt
    When I scan the receipt
    And I select items to return
    Then the system should show "Manager Approval Required"
    When a manager enters their PIN
    And selects exception reason "Customer Goodwill"
    Then the return should proceed

  Scenario: No receipt - store credit at current price
    Given a customer wants to return "Blue Shirt"
    And the customer has no receipt
    And "Blue Shirt" current price is "$35.00"
    When I scan the item barcode
    Then the system should show "No Receipt - Store Credit at Current Price"
    And the system should show "Manager Approval Required"
    When a manager approves
    Then store credit for "$35.00" should be issued

  Scenario: Final sale items blocked
    Given order "ORD-001" contains item "Clearance Item" marked as "Final Sale"
    When I attempt to return "Clearance Item"
    Then the system should show "BLOCKED: Final Sale - No Returns"
    And the return should not proceed

  Scenario: Restocking fee for opened electronics
    Given order "ORD-001" contains "Headphones" in category "Electronics"
    And the item has been opened
    When I process the return
    Then the system should show "Restocking Fee: 15%"
    And the refund should be reduced by 15%

Feature: Void vs Return Distinction

Feature: Void vs Return Rules
  As a retail staff member
  I need clear rules for when to void vs return
  So that corrections are handled properly

  Scenario: Void allowed same day with drawer open
    Given order "ORD-001" was completed today
    And the cash drawer is still open
    When I select order "ORD-001"
    And I click "Void"
    Then the void should be allowed
    And inventory should be reversed immediately
    And commission should be fully reversed
    And the order status should be "VOIDED"

  Scenario: Void blocked after drawer close
    Given order "ORD-001" was completed today
    And the cash drawer has been closed
    When I select order "ORD-001"
    And I click "Void"
    Then the system should show "Cannot void - drawer closed. Use Return instead."

  Scenario: Void blocked next day
    Given order "ORD-001" was completed yesterday
    When I select order "ORD-001"
    And I click "Void"
    Then the system should show "Cannot void - different business day. Use Return instead."

  Scenario: Return uses proportional commission reversal
    Given order "ORD-001" has 3 items totaling "$120.00"
    And commission was "$6.00" (5%)
    When I return 1 item worth "$40.00"
    Then commission should be reduced by "$2.00" (40/120 × $6)
    And net commission should be "$4.00"

Feature: Special Orders

Feature: Special Order Management
  As a retail staff member
  I need to create special orders for out-of-stock items
  So that customers can order items not currently available

  Scenario: Create special order with deposit
    Given "SKU-99999" is out of stock
    And it is available for special order at "$100.00"
    When I create a special order for customer "John Doe"
    And I enter quantity "1"
    Then the system should calculate deposit as "$50.00" (50%)
    When the customer pays "$50.00" deposit
    Then special order "SO-12345" should be created
    And the status should be "DEPOSIT_PAID"
    And the purchasing team should be notified

  Scenario: Complete special order on arrival
    Given special order "SO-12345" exists with deposit "$50.00"
    And the remaining balance is "$50.00"
    When the item arrives and status becomes "READY_FOR_PICKUP"
    Then customer "John Doe" should receive a notification
    When the customer arrives and pays "$50.00"
    Then the special order status should be "COMPLETED"

Feature: Cash Drawer Management

Feature: Cash Drawer Operations
  As a retail staff member
  I need to manage the cash drawer
  So that cash is tracked accurately

  Scenario: Open drawer with float
    Given the cash drawer is closed
    When a manager opens the drawer
    And enters opening float "$200.00"
    Then the drawer session should start
    And the drawer status should be "OPEN"

  Scenario: Close drawer with balanced count
    Given the drawer is open with float "$200.00"
    And cash sales today total "$350.00"
    And cash refunds today total "$50.00"
    When I click "Close Drawer"
    And I perform blind count entering "$500.00"
    Then expected amount should be "$500.00"
    And variance should be "$0.00"
    And the system should show "Drawer Balanced"
    And a Z-report should print

  Scenario: Variance requires manager approval
    Given the drawer is open with float "$200.00"
    And expected cash is "$500.00"
    When I perform blind count entering "$493.00"
    Then variance should be "-$7.00"
    And the system should show "Variance: -$7.00 - Manager Approval Required"
    When a manager enters PIN and reason "Counting Error"
    Then the drawer should close
    And the variance should be logged

  Scenario: Variance within tolerance auto-approves
    Given variance tolerance is set to "$5.00"
    And expected cash is "$500.00"
    When I perform blind count entering "$497.00"
    Then variance should be "-$3.00"
    And the system should show "Drawer Balanced" (within tolerance)

  Scenario: Run X-Report mid-shift
    Given the drawer is open with float "$200.00"
    And cash sales so far total "$150.00"
    And cash refunds so far total "$20.00"
    When I click "X-Report"
    Then the X-Report should show opening float "$200.00"
    And the X-Report should show cash sales "$150.00"
    And the X-Report should show cash refunds "$20.00"
    And the X-Report should show expected cash "$330.00"
    And the drawer should remain OPEN
    And I should be able to continue processing transactions

  Scenario: Run multiple X-Reports in one shift
    Given the drawer is open
    When I run an X-Report at 10:00 AM
    And I process more sales
    And I run another X-Report at 2:00 PM
    Then both X-Reports should complete successfully
    And the second X-Report should reflect updated totals
    And the drawer should remain OPEN

Feature: Coupon System

Feature: Coupon Redemption
  As a retail staff member
  I need to apply coupons to transactions
  So that customers receive their discounts

  Scenario: Apply single-use birthday coupon
    Given coupon "BDAY-JOHN-2026" exists
    And it is a single-use coupon for "$10 off"
    And it has not been redeemed
    When I scan the coupon
    Then "$10.00" discount should apply
    When I complete the sale
    Then the coupon status should be "REDEEMED"

  Scenario: Reject already-used single-use coupon
    Given coupon "BDAY-JOHN-2026" has been redeemed
    When I scan the coupon
    Then the system should show "Coupon Already Redeemed"
    And no discount should apply

  Scenario: Apply multi-use promotional coupon
    Given coupon "SAVE10" exists
    And it is a multi-use coupon for "10% off"
    And it has been used 50 times (limit 1000)
    When I scan the coupon
    Then "10% off" discount should apply
    When I complete the sale
    Then the coupon usage count should be 51

  Scenario: Reject expired coupon
    Given coupon "SUMMER2025" expired on "2025-08-31"
    When I scan the coupon
    Then the system should show "Coupon Expired"
    And no discount should apply

Feature: Loyalty Programs

Feature: Flexible Loyalty Programs
  As a retail staff member
  I need to manage customer loyalty
  So that customers are rewarded for purchases

  Scenario: Earn points per dollar
    Given customer "Jane Doe" is attached to the sale
    And the loyalty program awards 1 point per $1
    And the cart total is "$45.00"
    When I complete the sale
    Then "Jane Doe" should earn 45 points
    And the receipt should show "Points Earned: 45"

  Scenario: Redeem points for discount
    Given customer "Jane Doe" has 500 points
    And redemption rate is 100 points = $1
    When I click "Redeem Points"
    And I redeem 500 points
    Then "$5.00" discount should apply
    And "Jane Doe" points should become 0

  Scenario: Punch card completion
    Given customer "Jane Doe" has a coffee punch card
    And she has 9 of 10 punches
    And the cart contains 1 coffee
    When I complete the sale
    Then the punch card should show "FREE ITEM EARNED!"
    And the 10th coffee should be free
    And a new punch card should start

  Scenario: Tier upgrade on spend threshold
    Given customer "Jane Doe" is "BRONZE" tier
    And she has spent "$950" this year
    And the cart total is "$100"
    When I complete the sale
    Then "Jane Doe" should be upgraded to "SILVER"
    And the system should show "Customer upgraded to Silver!"
    And she should now earn 1.5x points

Feature: Offline Operations

Feature: Offline Mode Operations
  As a retail staff member
  I need to continue serving customers when network is down
  So that business is not interrupted

  Background:
    Given I am logged into the POS system
    And the cash drawer is open

  Scenario: Detect offline and show indicator
    Given the network connection is lost
    Then the UI should show "OFFLINE MODE" indicator
    And the indicator should be prominently visible

  Scenario: Process sale while offline
    Given I am in offline mode
    When I scan items and complete a sale
    Then the transaction should be queued locally
    And the receipt should print with "OFFLINE" watermark
    And I should see "1 transaction pending sync"

  Scenario: Block risky operations offline
    Given I am in offline mode
    When I try to create a new customer
    Then the system should show "Not available offline"
    When I try to activate a gift card
    Then the system should show "Not available offline"
    When I try to check multi-store inventory
    Then the system should show "Not available offline"

  Scenario: Auto-sync when network restores
    Given I am in offline mode
    And I have 3 queued transactions
    When the network connection is restored
    Then the UI should show "SYNCING..."
    And transactions should sync automatically
    When sync completes
    Then the UI should show "All transactions synced"

  Scenario: Handle sync conflict
    Given I am in offline mode
    And I sold the last unit of "SKU-123"
    When the network restores
    And another store also sold the last unit
    Then the system should show "Conflict: SKU-123 out of stock"
    And I should be prompted for manager review
    When the manager approves backorder
    Then the transaction should complete with backorder status

Feature: Payment Integration

Feature: SAQ-A Payment Processing
  As a retail staff member
  I need to process card payments securely
  So that customer card data is protected

  Scenario: Successful card payment
    Given a cart total of "$45.00"
    When I click "Pay by Card"
    Then the terminal should display "$45.00"
    When the customer taps their card
    And the payment is approved
    Then I should see "Approved - $45.00"
    And the receipt should show "VISA ****1234"
    And no full card number should be stored

  Scenario: Card declined - insufficient funds
    Given a cart total of "$200.00"
    When I click "Pay by Card"
    And the customer's card is declined for insufficient funds
    Then I should see "Card Declined: Insufficient Funds"
    And I should have options: "Try Another Card" | "Cash" | "Cancel"

  Scenario: Terminal timeout
    Given a cart total of "$45.00"
    When I click "Pay by Card"
    And the terminal does not respond within 60 seconds
    Then I should see "Terminal not responding"
    And I should have options: "Retry" | "Different Terminal" | "Cash" | "Cancel"

  Scenario: Refund using stored token
    Given order "ORD-001" was paid by card
    And the payment token is stored
    When I process a refund for "ORD-001"
    Then the refund should use the stored token
    And I should not need to re-enter card details
    And the receipt should show "Refund to VISA ****1234"

  Scenario: Pay with Affirm financing
    Given a cart total of "$500.00"
    When I click "Pay with Affirm"
    Then a QR code or redirect should display for the customer
    When the customer completes Affirm application on their device
    And Affirm approves the loan
    Then I should see "Payment Approved (Affirm)"
    And the full $500.00 should be received from Affirm
    And no card data should be stored
    And an Affirm charge_id should be stored

  Scenario: Split payment across two credit cards
    Given a cart total of "$200.00"
    When I click "Pay by Card"
    And the customer pays "$100.00" with first card
    Then remaining balance should show "$100.00"
    When I click "Pay by Card" again
    And the customer pays "$100.00" with second card
    Then the order should be marked "PAID"
    And two separate payment tokens should be stored

  Scenario: Combine cash and card payment
    Given a cart total of "$150.00"
    When I accept "$50.00" cash
    Then remaining balance should show "$100.00"
    When the customer pays "$100.00" by card
    Then the order should be marked "PAID"

Feature: Tax Calculation

Feature: Tax Calculation Engine
  As a retail staff member
  I need accurate tax calculation
  So that the correct tax is collected

  Scenario: Standard Virginia tax
    Given the store is located in Richmond, Virginia
    And the cart contains taxable items totaling "$100.00"
    When I calculate tax
    Then state tax should be "$4.30" (4.3%)
    And local tax should be "$1.00" (1.0%)
    And total tax should be "$5.30"

  Scenario: Northern Virginia regional tax
    Given the store is located in Fairfax, Virginia
    And the cart contains taxable items totaling "$100.00"
    When I calculate tax
    Then state tax should be "$4.30" (4.3%)
    And local tax should be "$1.00" (1.0%)
    And regional tax should be "$0.70" (0.7%)
    And total tax should be "$6.00"

  Scenario: Product-level tax override
    Given the cart contains "Grocery Item" in tax category "grocery_food"
    And "Grocery Item" price is "$20.00"
    When I calculate tax
    Then tax on "Grocery Item" should be "$0.30" (1.5% reduced rate)

  Scenario: Customer tax exemption
    Given customer "ABC Nonprofit" has tax exemption status "NONPROFIT"
    And the cart contains taxable items totaling "$100.00"
    When I attach customer "ABC Nonprofit" to the sale
    And I calculate tax
    Then total tax should be "$0.00"
    And the receipt should show "Tax Exempt: 501(c)(3)"

  Scenario: Tax hierarchy - product override takes priority
    Given customer "ABC Nonprofit" has tax exemption status
    And the cart contains "Prepared Food" (10% tax rate)
    When I calculate tax
    Then the product-level 10% rate should apply
    Because product-level overrides take priority over customer exemption

2. Customers Module

2.1 Customer Management Workflow

Scope: Creating Profiles, Merging Duplicates, Tax Logic, Groups, and Deletion Guards.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 1: Creation & Maintenance

    U->>UI: Search Customer (Name / Phone / Email)
    UI->>API: GET /customers/search

    alt Customer Found
        API-->>UI: Return Profile
        UI-->>U: Display Customer Details + Group + Price Tier
    else Create New
        U->>UI: Enter Details (Name, Phone, Email)
        U->>UI: Enter Physical Address (Shipping)
        U->>UI: Enter Billing Address (if different)

        opt Customer Group Assignment
            U->>UI: Select Group (Retail/Wholesale/VIP/Staff)
            Note right of UI: Group determines Price Tier
        end

        opt Tax Assignment
            U->>UI: Select Custom Tax Rate (e.g., "Tax Exempt")
            Note right of UI: Overrides Default Store Tax
        end

        opt Communication Preferences
            U->>UI: Set Email Opt-In (Y/N)
            U->>UI: Set SMS Opt-In (Y/N)
            U->>UI: Set Preferred Contact Method
        end

        opt Customer Notes
            U->>UI: Enter Size Preferences
            U->>UI: Enter Free-Form Notes
        end

        UI->>API: POST /customers/create
        API->>DB: Insert Record
    end

2.2 Customer Groups & Tiers

Scope: Automatic and manual group assignment with price tier implications.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Customer Group Management

    alt Manual Group Assignment
        U->>UI: Open Customer Profile
        U->>UI: Click "Change Group"
        U->>UI: Select Group (Retail/Wholesale/VIP/Staff)
        UI->>API: PATCH /customers/{id}/group
        API->>DB: Update Customer Group
        API->>DB: Update Price Tier (Based on Group)
        API-->>UI: Group Updated
    end

    Note over API, DB: Automatic Tier Upgrades (Background Job)

    API->>DB: Check Customer Spend Totals

    alt Spend >= Gold Threshold ($5,000/year)
        API->>DB: Upgrade to Gold Tier
        API-->>UI: Notify: "Customer upgraded to Gold!"
    else Spend >= Silver Threshold ($1,000/year)
        API->>DB: Upgrade to Silver Tier
    end

    Note right of DB: Tier Benefits:
    Note right of DB: Bronze: 1x points
    Note right of DB: Silver: 1.5x points + 5% discount
    Note right of DB: Gold: 2x points + 10% discount

2.3 Customer Notes & Preferences

Scope: Structured fields and free-form notes for customer preferences.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    U->>UI: Open Customer Profile
    U->>UI: Click "Notes & Preferences"

    Note over UI, DB: Structured Preferences

    U->>UI: Enter Clothing Size (S/M/L/XL)
    U->>UI: Enter Shoe Size
    U->>UI: Select Color Preferences
    U->>UI: Enter Brand Preferences

    Note over UI, DB: Free-Form Notes

    U->>UI: Enter Notes (e.g., "Prefers classic styles, allergic to wool")

    UI->>API: PATCH /customers/{id}/preferences
    API->>DB: Update Preference Fields
    API-->>UI: Saved

    Note over U, UI: Notes Display at POS

    U->>UI: Attach Customer to Sale
    UI->>API: GET /customers/{id}
    API-->>UI: Return Profile with Notes
    UI-->>U: Display: "Notes: Prefers classic styles, Size M"

2.4 Communication Preferences

Scope: Marketing consent, contact preferences, and opt-out management.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Communication Preference Management

    U->>UI: Open Customer Profile -> Communications

    UI-->>U: Display Current Settings:
    Note right of UI: Email Marketing: [ON/OFF]
    Note right of UI: SMS Marketing: [ON/OFF]
    Note right of UI: Preferred Contact: [Email/Phone/SMS]
    Note right of UI: Do Not Contact: [Y/N]

    U->>UI: Toggle Email Marketing ON
    U->>UI: Toggle SMS Marketing OFF
    U->>UI: Set Preferred: Email

    UI->>API: PATCH /customers/{id}/communication-prefs
    API->>DB: Update Communication Preferences
    API->>DB: Log Consent Change (Audit Trail)
    API-->>UI: Preferences Saved

    Note over API, DB: Privacy Compliance
    Note right of DB: All consent changes logged with timestamp
    Note right of DB: Customer can request full data export
    Note right of DB: "Do Not Contact" blocks all outreach

2.5 Advanced Customer Actions

Scope: Merge duplicates, safe deletion, data export, and privacy compliance.

sequenceDiagram
    autonumber
    participant U as Staff
    participant UI as POS UI
    participant API as Backend
    participant DB as DB

    Note over U, DB: Phase 2: Advanced Actions (Merge & Delete)

    alt Action: Merge Duplicates
        U->>UI: Select "Source" (Duplicate) & "Target" (Primary)
        U->>UI: Click "Merge Customers"
        UI->>API: POST /customers/merge

        par Data Transfer
            API->>DB: Move History, Loyalty, Balance to Target
            API->>DB: Merge Notes (Append Source to Target)
            API->>DB: Keep Higher Tier
            API->>DB: Soft-Delete "Source" Profile
        end

        API-->>UI: Merge Success
    end

    alt Action: Delete Customer
        U->>UI: Click "Delete Customer"
        UI->>API: GET /customers/{id}/balance-check

        alt Has Debt or Open Layaway
            API-->>UI: Error: "Cannot Delete - Outstanding Balance"
            UI-->>U: Alert: "Settle Balance First"
        else Safe to Delete
            UI->>API: DELETE /customers/{id}
            API->>DB: Anonymize Personal Data
            API->>DB: Retain Sales History (Linked to "Anonymous")
            API-->>UI: Deletion Success
        end
    end

    alt Action: Export Data
        U->>UI: Filter List -> Click "Export CSV"
        UI->>API: POST /customers/export
        Note right of UI: Limit 1000 rows
        API-->>UI: Download CSV File
    end

    alt Action: Data Subject Request (Privacy)
        U->>UI: Click "Privacy Request"
        U->>UI: Select Type: Export / Delete / Restrict
        UI->>API: POST /customers/{id}/privacy-request
        API->>DB: Log Request with Timestamp
        API-->>UI: Request ID Generated
        Note right of API: Must complete within 30 days
    end

2.6 Customer Self-Service

Scope: Customer-facing loyalty balance and preference management.

sequenceDiagram
    autonumber
    participant C as Customer
    participant UI as Self-Service Kiosk / App
    participant API as Backend
    participant DB as DB

    Note over C, DB: Customer Self-Service Options

    alt Check Loyalty Balance
        C->>UI: Enter Phone Number or Scan Card
        UI->>API: GET /customers/lookup?phone={phone}
        API->>DB: Find Customer
        API-->>UI: Return Loyalty Summary
        UI-->>C: Display: "Points: 450 | Tier: Silver | $4.50 available"
    end

    alt Update Preferences
        C->>UI: Login (Phone + PIN)
        UI->>API: GET /customers/{id}/preferences
        API-->>UI: Return Current Preferences
        C->>UI: Update Email / SMS Opt-In
        UI->>API: PATCH /customers/{id}/communication-prefs
        API->>DB: Update & Log Consent Change
        API-->>UI: Saved
    end

    alt Request Data Export
        C->>UI: Click "Download My Data"
        UI->>API: POST /customers/{id}/data-export
        API->>DB: Queue Export Job
        API-->>UI: "Export will be emailed within 24 hours"
    end

2.6.1 Reports: Customer Module

Email Template: TMPL-WELCOME

Email Template: TMPL-TIER-UPGRADE

2.7 Customer User Stories (Epics)

Epic 2.A: Profile & Data Management

• Story 2.A.1 (Detailed Profile): Staff can store distinct “Shipping” (Physical) and “Billing” addresses for a customer to support delivery and invoicing.
• Story 2.A.2 (Duplicate Handling / Merge): Managers can merge two customer profiles. The system must transfer all Sales History, Loyalty Points, Account Balances, and Notes to the “Primary” profile and archive the “Duplicate”.
• Story 2.A.3 (Safe Deletion): The system must block deletion if the customer has an active “On Account” debt or an open “Layaway”. If deleted, their historical sales must remain but be anonymized.
• Story 2.A.4 (Export): Staff can export the customer list to CSV for marketing, limited to 1,000 rows per batch for system stability.
• Story 2.A.5 (Customer Notes): Staff can record structured preferences (size, color, brand) and free-form notes on customer profiles. Notes are displayed when customer is attached to a sale.

Epic 2.B: Financial & Tax Settings

• Story 2.B.1 (Custom Tax Rates): Managers can assign a specific tax exemption status (e.g., “Reseller”, “Non-Profit”) to a customer profile. This status overrides the Store Default Tax when the hierarchy allows.
• Story 2.B.2 (Credit Limits): Managers can set a hard “Credit Limit”. The POS must block any “On Account” sale that pushes (Current Debt + Pending Layaways + Cart) over this limit.
• Story 2.B.3 (Loyalty Adjustments): Managers can manually adjust loyalty points (e.g., +50 “Sorry for wait”). A mandatory reason note is required for audit trails.

Epic 2.C: Customer Groups & Tiers

• Story 2.C.1 (Customer Groups): Customers can be assigned to groups (Retail, Wholesale, VIP, Staff). Each group maps to a price tier that determines base pricing.
• Story 2.C.2 (Automatic Tier Upgrades): Customers automatically upgrade tiers (Bronze → Silver → Gold) when spend thresholds are met. Upgrades can also be manually assigned by managers.
• Story 2.C.3 (Tier Benefits): Each tier has configurable benefits: point multipliers, automatic discounts, and early access to sales.
• Story 2.C.4 (Price Tiers): Different customer groups see different base prices (not just discounts). Wholesale customers may see cost+markup pricing while retail sees standard pricing.

Epic 2.D: Communication & Preferences

• Story 2.D.1 (Communication Consent): Customers can opt-in or opt-out of email and SMS marketing. All consent changes are logged for compliance.
• Story 2.D.2 (Preferred Contact): Customers can specify their preferred contact method (Email, Phone, SMS). Staff can see this preference when reaching out.
• Story 2.D.3 (Do Not Contact): Customers can be flagged as “Do Not Contact” which blocks all marketing outreach while preserving transaction notifications.

Epic 2.E: Privacy & Compliance

• Story 2.E.1 (Data Export): Customers can request a full export of their personal data. Export must be provided within 30 days.
• Story 2.E.2 (Right to Deletion): Customers can request deletion of their personal data. System anonymizes records while preserving transaction history for accounting.
• Story 2.E.3 (Consent Audit Trail): All marketing consent changes are logged with timestamp and source for regulatory compliance.
• Story 2.E.4 (Data Retention): Customer data is retained according to configurable retention policies. Inactive customers can be auto-anonymized after retention period.

Epic 2.F: Self-Service

• Story 2.F.1 (Loyalty Balance Check): Customers can check their loyalty points balance via kiosk, app, or website using phone number lookup.
• Story 2.F.2 (Preference Update): Customers can update their communication preferences (opt-in/opt-out) via self-service channels.
• Story 2.F.3 (Data Request): Customers can submit data export or deletion requests via self-service, which are queued for staff processing.

2.8 Customer Acceptance Criteria (Gherkin)

Feature: Customer Groups and Tiers

Feature: Customer Group Management
  As a retail manager
  I need to assign customers to groups
  So that they receive appropriate pricing and benefits

  Scenario: Assign customer to wholesale group
    Given customer "ABC Corp" exists
    When I open the customer profile
    And I click "Change Group"
    And I select "Wholesale"
    Then the customer group should be "Wholesale"
    And the price tier should update to "Wholesale Pricing"

  Scenario: Automatic tier upgrade on spend
    Given customer "Jane Doe" is "BRONZE" tier
    And she has spent "$4,900" this year
    And annual spend threshold for Silver is "$1,000"
    And annual spend threshold for Gold is "$5,000"
    When she makes a purchase of "$150"
    Then her annual spend becomes "$5,050"
    And she should be upgraded to "GOLD" tier
    And she should now earn 2x points
    And she should receive 10% automatic discount

Feature: Customer Merge

Feature: Merge Duplicate Customers
  As a retail manager
  I need to merge duplicate customer profiles
  So that customer data is consolidated

  Scenario: Merge two customer profiles
    Given customer "John Doe" (ID: 100) has:
      | Loyalty Points | 500 |
      | Account Balance | $50.00 |
      | Tier | Silver |
    And customer "J. Doe" (ID: 101) has:
      | Loyalty Points | 200 |
      | Account Balance | $25.00 |
      | Tier | Bronze |
    When I select "J. Doe" as source and "John Doe" as target
    And I click "Merge Customers"
    Then "John Doe" should have:
      | Loyalty Points | 700 |
      | Account Balance | $75.00 |
      | Tier | Silver |
    And "J. Doe" profile should be archived
    And sales history from both should be under "John Doe"

Feature: Safe Customer Deletion

Feature: Customer Deletion Guards
  As a retail manager
  I need deletion to be blocked when unsafe
  So that we don't lose important data

  Scenario: Block deletion with outstanding debt
    Given customer "John Doe" has account balance "$150.00"
    When I click "Delete Customer"
    Then the system should show "Cannot Delete - Outstanding Balance"
    And the deletion should be blocked

  Scenario: Block deletion with open layaway
    Given customer "John Doe" has an active layaway order
    When I click "Delete Customer"
    Then the system should show "Cannot Delete - Open Layaway"
    And the deletion should be blocked

  Scenario: Safe deletion anonymizes data
    Given customer "John Doe" has no debt or layaway
    And "John Doe" has 5 historical orders
    When I click "Delete Customer"
    And I confirm the deletion
    Then personal data should be anonymized
    And the 5 orders should remain linked to "Anonymous Customer"

Feature: Communication Preferences

Feature: Communication Preference Management
  As a retail staff member
  I need to manage customer communication preferences
  So that we comply with privacy regulations

  Scenario: Update email opt-in
    Given customer "Jane Doe" has email marketing OFF
    When I open communications preferences
    And I toggle email marketing ON
    Then email marketing should be ON
    And a consent change should be logged with timestamp

  Scenario: Do Not Contact blocks outreach
    Given customer "John Doe" is flagged "Do Not Contact"
    When the marketing system attempts to send email
    Then the email should be blocked
    And no marketing should be sent

  Scenario: Transaction notifications still sent
    Given customer "John Doe" is flagged "Do Not Contact"
    When he makes a purchase
    Then a receipt email should still be sent
    Because transaction notifications are not marketing

Feature: Privacy Compliance

Feature: Customer Privacy Rights
  As a customer
  I need to exercise my privacy rights
  So that my data is protected

  Scenario: Request data export
    Given I am customer "Jane Doe"
    When I request a data export
    Then a request should be logged
    And I should receive confirmation
    And my data should be emailed within 30 days

  Scenario: Request data deletion
    Given I am customer "Jane Doe"
    And I have no outstanding balance or layaway
    When I request data deletion
    Then my personal data should be anonymized
    And my transaction history should be preserved (anonymized)
    And I should receive confirmation

  Scenario: Deletion blocked with balance
    Given I am customer "Jane Doe"
    And I have account balance "$50.00"
    When I request data deletion
    Then the system should show "Please settle outstanding balance first"
    And my data should not be deleted

Feature: Customer Self-Service

Feature: Customer Self-Service
  As a customer
  I want to check my loyalty status
  So that I know my rewards

  Scenario: Check loyalty balance
    Given I am customer with phone "555-1234"
    And I have 450 loyalty points
    And I am Silver tier
    When I enter my phone number at the kiosk
    Then I should see "Points: 450"
    And I should see "Tier: Silver"
    And I should see "$4.50 available for redemption"

  Scenario: Update marketing preferences
    Given I am logged into self-service
    And email marketing is ON
    When I toggle email marketing OFF
    Then email marketing should be OFF
    And a consent change should be logged

3. Catalog Module

3.1 Product Types & Data Model

Scope: Core POS Catalog – all product entries, types, data fields, and the relationships between them. Every item sold, bundled, or serviced flows through the catalog. The data model supports four distinct product types that cover the full range of retail merchandise: individually tracked goods, multi-dimension variants, composite bundles, and non-inventory services. Beyond the standard field set, the model supports tenant-defined custom attributes, product templates for rapid creation, and a matrix management interface for efficient variant operations.

Cross-Reference: See Module 5, Section 5.10 for UoM configuration and Section 5.12 for custom fields.

3.1.1 Product Types

3.1.2 Product Class Diagram

classDiagram
    class Product {
        +UUID id
        +String sku
        +String name
        +String product_type
        +Decimal base_price
        +Decimal cost
        +String lifecycle_status
        +Boolean shippable
        +UUID package_type_id
        +Enum selling_uom
        +Enum purchasing_uom
        +Decimal uom_conversion_factor
        +UUID season_id
        +UUID brand_id
        +DateTime created_at
        +DateTime updated_at
    }

    class StandardProduct {
        +String barcode
        +String[] alternate_barcodes
        +Boolean track_inventory
        +Integer low_stock_threshold
    }

    class VariantParent {
        +String[] dimension_names
        +Integer dimension_count
        +String style_number
        +String[] demographics_age_group
        +String[] demographics_gender
        +String origin
        +String fabric
        +UUID season_id
    }

    class VariantChild {
        +UUID parent_id
        +String dimension_1_value
        +String dimension_2_value
        +String dimension_3_value
        +String barcode
        +Decimal price_override
        +Decimal msrp
        +Boolean track_inventory
        +Boolean deletion_protected
    }

    class CompositeProduct {
        +Decimal bundle_price
        +Boolean allow_component_substitution
    }

    class BundleComponent {
        +UUID composite_id
        +UUID component_product_id
        +Integer quantity
        +Decimal component_cost_allocation
    }

    class ServiceProduct {
        +Integer estimated_minutes
        +Boolean requires_appointment
        +String service_category
    }

    class CustomAttributeDefinition {
        +UUID id
        +String name
        +Enum type
        +Boolean required
        +UUID tenant_id
    }

    class ProductCustomAttribute {
        +UUID product_id
        +UUID definition_id
        +String value
    }

    class PackageType {
        +UUID id
        +String name
        +Decimal length
        +Decimal width
        +Decimal height
        +Decimal empty_weight
        +UUID tenant_id
    }

    Product <|-- StandardProduct
    Product <|-- VariantParent
    Product <|-- CompositeProduct
    Product <|-- ServiceProduct
    VariantParent "1" --> "*" VariantChild : has children
    CompositeProduct "1" --> "*" BundleComponent : contains
    BundleComponent "*" --> "1" Product : references component
    Product "0..*" --> "0..*" ProductCustomAttribute : has custom values
    ProductCustomAttribute "*" --> "1" CustomAttributeDefinition : defined by
    Product "*" --> "0..1" PackageType : ships in

3.1.3 Full Product Data Model

Business Rules – Shipping:

• IF shippable = true THEN weight, length, width, and height are all mandatory. The system rejects save attempts where shippable is enabled but physical dimensions are missing.
• IF package_type_id is set, the package dimensions auto-populate from the PackageType record but can be overridden at the product level.

Business Rules – Unit of Measure:

• IF purchasing_uom differs from selling_uom, then uom_conversion_factor is mandatory.
• Receiving inventory via Purchase Order uses purchasing_uom; inventory levels and POS transactions use selling_uom. The system automatically converts quantities using the conversion factor.

3.1.4 Custom Attributes

Scope: Tenant-defined key/value custom fields that extend the standard product data model. Custom attributes allow each tenant to capture business-specific data (e.g., “Certification Level”, “Country of Origin Detail”, “Season Year”) without schema changes.

Custom Attribute Definition Table

ProductCustomAttribute Junction Table

Business Rules:

• Limit: Up to 50 custom attribute definitions per tenant. Attempting to create a 51st returns an error with guidance to archive unused attributes.
• Indexing: All attributes marked searchable = true are indexed via a GIN index on a materialized JSONB representation for fast full-text search.
• Filtering: Attributes marked filterable = true appear as sidebar filters in the Admin Portal product list and can be used in smart collection rules.
• Validation: When type = LIST, the system rejects any value not present in list_values[]. When type = NUMBER, the system validates numeric format. When required = true, product save is blocked until a value is provided.
• Inheritance: Custom attributes are set at the parent product level. Variant children inherit parent custom attributes and cannot override them individually.

3.1.5 Product Templates & Cloning

Scope: Accelerating product creation by cloning existing products and by applying category-based templates with pre-filled default values. Templates reduce repetitive data entry for categories with consistent attributes (e.g., all t-shirts share the same weight range, tax code, and fabric type).

Product Cloning

• Clone any product to create a new DRAFT with a new auto-generated SKU. All fields are copied except identity fields (id, sku, barcode), timestamps (created_at, updated_at, published_at), and audit fields (created_by is set to the cloning user).
• Cloned products always start in DRAFT status regardless of the source product’s status.
• For variant products, cloning copies the parent AND all child variants. Each child receives a new auto-generated SKU. Inventory levels are NOT copied (all set to zero).
• Cloned products receive a default name of “{Original Name} (Copy)” which staff must rename before publishing.

Category-Based Templates

Templates save pre-filled default values per category so that new products created in that category start with sensible defaults already populated.

Template Data Model

Example default_values JSON:

{
  "fabric": "100% Cotton",
  "weight": 0.35,
  "weight_unit": "lb",
  "tax_code": "clothing_exempt",
  "selling_uom": "EACH",
  "shippable": true,
  "track_inventory": true,
  "low_stock_threshold": 5,
  "demographics_gender": ["Men"],
  "demographics_age_group": ["Adult"],
  "origin": "Imported",
  "custom_attributes": {
    "Certification": "None",
    "Care Instructions": "Machine wash cold"
  }
}

Business Rules:

• One template per category per tenant. If a template already exists for a category, staff must edit the existing template rather than create a duplicate.
• When a product is created and assigned to a category that has a template, the system auto-fills all fields from default_values. Staff can override any auto-filled value before saving.
• Templates do not retroactively update existing products. They apply only at creation time.
• Template fields that conflict with required product fields are ignored (e.g., a template cannot set name or sku).

3.1.6 Product Matrix Management

Scope: A grid-based interface for managing variant products efficiently. The matrix view presents all variant combinations in a spreadsheet-like layout, enabling rapid price/cost/stock editing and bulk variant creation.

Matrix Grid View

For variant products with two dimensions, the matrix displays:

• Rows = Dimension 1 values (e.g., sizes: S, M, L, XL, XXL)
• Columns = Dimension 2 values (e.g., colors: Red, Blue, Navy, Black)
• Each cell shows: price, cost, and current stock level for that combination

              | Red        | Blue       | Navy       | Black      |
---------------------------------------------------------------------------
  S           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 14  | Stock: 11  | Stock: 9   | Stock: 7   |
---------------------------------------------------------------------------
  M           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 22  | Stock: 18  | Stock: 15  | Stock: 13  |
---------------------------------------------------------------------------
  L           | $29 / $12  | $29 / $12  | $29 / $12  | $29 / $12  |
              | Stock: 19  | Stock: 16  | Stock: 12  | Stock: 10  |
---------------------------------------------------------------------------
  XL          | $32 / $13  | $32 / $13  | $32 / $13  | $32 / $13  |
              | Stock: 8   | Stock: 6   | Stock: 5   | Stock: 4   |

Inline Editing:

• Click any cell to edit price, cost, or stock level directly in the grid.
• Tab key moves to the next cell. Enter confirms the edit.
• Changed cells are highlighted until saved. A single “Save All Changes” action persists all edits in one batch.

Bulk-Create Variants:

• Select dimension value combinations via checkboxes (e.g., check “XXL” row and all color columns) to generate all child SKUs in one operation.
• The system auto-generates SKUs using the configured SKU pattern, assigns the parent’s base price and cost as defaults, and sets initial inventory to zero.
• Staff can review generated variants before confirming creation.

Matrix Import via CSV:

• Upload a CSV file with columns matching dimension values and data fields.
• CSV format: dimension_1_value, dimension_2_value, price, cost, barcode
• The system validates all rows, reports errors (duplicate barcodes, invalid dimension values, non-numeric prices), and applies valid rows in batch.
• Supports both CREATE (new variants) and UPDATE (existing variants matched by dimension values) modes.

Business Rules:

• Matrix view is available only for products with exactly 2 variant dimensions. Products with 1 or 3 dimensions use the standard list editor.
• Cells for non-existent variant combinations display as empty with a “+” icon to create that specific variant on demand.
• Deleting a variant from the matrix is only permitted when the variant has zero inventory across all locations and no open orders referencing it.

3.2 Product Lifecycle

Scope: Managing products from initial creation through active selling, discontinuation, archival, and potential re-creation from archived templates. The lifecycle enforces data completeness before publishing and protects against premature archival while stock remains on hand.

3.2.1 Product Lifecycle State Machine

stateDiagram-v2
    [*] --> DRAFT: Product Created
    DRAFT --> ACTIVE: Publish
    ACTIVE --> DISCONTINUED: Discontinue
    DISCONTINUED --> ACTIVE: Reactivate
    DISCONTINUED --> ARCHIVED: Archive (stock = 0 all locations)
    ARCHIVED --> DRAFT: Clone as New (new SKU)

    note right of DRAFT
        Incomplete product
        Not visible at POS
        No sales allowed
    end note

    note right of ACTIVE
        Fully configured
        Available for sale
        Visible at POS
    end note

    note right of DISCONTINUED
        Sell-through mode
        No restock / no new POs
        Still sellable until stock = 0
    end note

    note right of ARCHIVED
        Read-only historical record
        Not visible at POS
        Can clone to create new product
    end note

3.2.2 Lifecycle Transition Rules

Business Rules:

• A product cannot be archived while any location holds stock. The system checks qty_on_hand across all locations before allowing the transition.
• Cloning an archived product does NOT restore the original. It creates a new, separate product that can be edited independently.
• Discontinued products continue to appear in POS barcode lookup and search so that remaining stock can be sold.

3.3 Pricing Engine

Scope: Managing product pricing across channels, customer groups, and promotional periods. The engine supports centralized pricing with cascading overrides, named price books, four promotion types, formal markdown workflows, and best-price conflict resolution. Every price determination is auditable – the system logs which rules were evaluated, which rule won, and the final price applied.

3.3.1 Price Hierarchy

Centralized pricing with cascading override resolution. When determining the price for a product at checkout, the system evaluates five priority levels and applies the highest-priority match:

flowchart TD
    A[Start: Determine Price] --> B{Manual Override?}
    B -->|Yes| C[Use Manual Override Price]
    B -->|No| D{Active Promotion?}
    D -->|Yes| E[Use Promotion Price]
    D -->|No| F{Price Book Match?}
    F -->|Yes| G[Use Price Book Price]
    F -->|No| H{Channel Price Set?}
    H -->|Yes| I[Use Channel Price]
    H -->|No| J[Use base_price from Product]
    C --> K[Log Price Resolution to Audit Trail]
    E --> K
    G --> K
    I --> K
    J --> K
    K --> L[Return Final Price]

3.3.2 Price Books

Scope: Named price lists that override global pricing for specific customer groups, channels, or date ranges. Price books enable scenarios such as wholesale pricing for B2B customers, employee discount pricing, and seasonal price adjustments without modifying the base product price.

Price Book Data Model

Price Book Entry Table

Business Rules:

• Exclusivity: Only one price book can be active per customer group per channel at any given time. If a new price book overlaps with an existing active book for the same group/channel combination, the system rejects creation and prompts the user to deactivate the conflicting book first.
• No stacking: Price books do not stack. When multiple price books match (e.g., one by customer group and one by channel), only the book with the highest priority value applies.
• Audit: Every price book activation, deactivation, and entry modification is logged with the acting user and timestamp.
• Bulk entry: Staff can import price book entries via CSV with columns: sku, override_price, override_cost. The system validates SKU existence and numeric formats before applying.

3.3.3 Promotions

Scope: Four promotion types that cover the most common retail discount scenarios. Promotions can be automatic (applied when conditions are met) or code-based (requiring manual entry at POS).

Promotion Types

Tiered / Volume Example:

BOGO / Cross-Item Example:

• Buy 2 Shirts (buy_product_id = shirts category, buy_qty = 2), Get 1 Belt 50% off (get_product_id = belts category, get_qty = 1, get_discount_type = PERCENT, get_discount_value = 50)

Scheduled / Automatic Example:

• Happy Hour: schedule_type = RECURRING, recurrence_pattern = “MON-FRI 15:00-17:00” – 15% off all drinks every weekday from 3 PM to 5 PM

Promotion Data Model

Promotion Lifecycle

stateDiagram-v2
    [*] --> DRAFT : Create Promotion
    DRAFT --> SCHEDULED : Set dates & activate
    DRAFT --> CANCELLED : Cancel before scheduling
    SCHEDULED --> ACTIVE : Start date reached
    SCHEDULED --> CANCELLED : Cancel before start
    ACTIVE --> EXPIRED : End date passed
    ACTIVE --> CANCELLED : Manually deactivate
    CANCELLED --> [*]
    EXPIRED --> [*]

Lifecycle Transition Rules:

• DRAFT: Promotion is being configured. Not visible to POS. Can be edited freely.
• SCHEDULED: Promotion is locked for editing (except cancellation). Awaiting start date.
• ACTIVE: Promotion is live. Applied automatically or via code at POS. Only the is_active toggle and end_date can be modified.
• EXPIRED: Terminal state. Promotion has passed its end date. Preserved for reporting. Cannot be reactivated – must be cloned to create a new promotion.
• CANCELLED: Terminal state. Promotion was manually stopped. Preserved for reporting.

3.3.4 Markdown & Clearance Management

Scope: Formal workflows for reducing prices, tracking clearance merchandise, and handling end-of-life write-offs. Every price reduction is accountable – the system enforces approval workflows and logs all changes for audit.

Markdown Request Workflow

sequenceDiagram
    autonumber
    participant S as Staff
    participant UI as Admin Portal
    participant API as Backend
    participant M as Manager
    participant DB as DB
    participant POS as POS Client

    Note over S, POS: Markdown Request Workflow

    S->>UI: Create Markdown Request
    Note right of UI: Product, new_price, effective_date, reason

    UI->>API: POST /markdowns
    API->>DB: Save request (status: PENDING)
    API-->>UI: Request #MD-001 created

    API->>M: Notification: Markdown request pending
    M->>UI: Review request details
    Note right of M: Current price, proposed price,<br/>margin impact, reason

    alt Approved
        M->>API: PATCH /markdowns/MD-001 {status: APPROVED}
        API->>DB: Update status, schedule price change
        Note right of DB: effective_date triggers price update

        DB-->>API: Price updated on effective_date
        API->>POS: Push updated price to all terminals
        API->>DB: Log to price_audit_trail
        Note right of DB: who, when, old_price,<br/>new_price, reason, approval_id
    else Rejected
        M->>API: PATCH /markdowns/MD-001 {status: REJECTED, reject_reason: "..."}
        API-->>S: Notification: Markdown rejected
    end

Manual Price Changes:

• Staff with appropriate permissions can change a product’s price directly without the formal markdown workflow.
• Every manual change requires selecting a reason from a configurable list: Damaged, Price Match, Manager Discretion, Competitive Adjustment, Cost Change, Seasonal Reduction, Error Correction.
• All manual changes are logged to the price audit trail: user_id, timestamp, product_id, old_price, new_price, reason, location_id.

Automatic Markdown Rules:

• Configurable rules engine that evaluates nightly and flags or automatically applies markdowns:

• Automatic rules can be configured to either flag for review (creates a pending markdown request) or apply immediately (executes the price change and logs it as auto-rule).