01 — System Architecture & Topology Specification

1. Executive Summary & Core Tenets

LQPOS is an enterprise-grade, local-first Point of Sale (POS) and Backoffice system engineered specifically for independent retail liquor stores. Unlike general-purpose cloud POS platforms that suffer from latency, rigid retail schemas, and cloud dependency, LQPOS is built upon five foundational tenets:

1. Sub-100ms Ergonomic Velocity: Register checkout must never wait on network I/O or heavy web rendering. The cashier UI operates at keystroke speed.
2. The "Friday 5 PM" Zero-Downtime Rule: A catastrophic ISP outage during peak weekend rush hours must have zero impact on scanning, ringing, cash management, or local card processing.
3. PCI-DSS Out-of-Scope Architecture: Cardholder data (PAN, CVV, expiration) never touches POS memory or storage. Payment terminals operate in semi-integrated Point-to-Point Encryption (P2PE) mode.
4. Automated Distributor Ingestion as a First-Class Engine: Electronic distributor invoice processing (Fintech EDI/CSV, DSDLink) is deeply integrated into inventory and margin pricing.
5. Multi-Unit Inventory Disaggregation: Native parent-child relationship between master cases, inner packs (4-pack/6-pack/12-pack), and individual bottles/cans.

2. System Topology & Deployment Architecture

                    ┌────────────────────────────────────────────────────────┐
                    │               CLOUD INFRASTRUCTURE                     │
                    │  • Central Catalog & Analytics                         │
                    │  • Multi-Store Aggregator (if enabled)                 │
                    │  • Secure Offsite Backup & QuickBooks Sync             │
                    └───────────────────────────▲────────────────────────────┘
                                                │
                                    Encrypted HTTPS / WSS Sync
                                    (Resilient Event Stream)
                                                │
════════════════════════════════════════════════╪══════════════════════════════════════════════
IN-STORE LOCAL AREA NETWORK (LAN)               ▼
                                ┌────────────────────────────────┐
                                │     IN-STORE EDGE SERVER       │
                                │   (PostgreSQL + Core Engine)   │
                                │  • Primary In-Store Database   │
                                │  • Invoice Parsing Pipeline    │
                                │  • Backoffice Web Service      │
                                └───────▲────────────────▲───────┘
                                        │                │
                        Fast LAN RPC / WS                Fast LAN RPC / WS
                                        │                │
                ┌───────────────────────┴──┐          ┌──┴────────────────────────┐
                ▼                          │          ▼                           │
   ┌───────────────────────────┐           │   ┌───────────────────────────┐      │
   │      REGISTER LANE 1      │           │   │      REGISTER LANE 2      │      │
   │ • PWA / Electron Shell    │           │   │ • PWA / Electron Shell    │      │
   │ • Local SQLite Cache      │           │   │ • Local SQLite Cache      │      │
   │ • Hardware Agent (HAL)    │           │   │ • Hardware Agent (HAL)    │      │
   └─────────────┬─────────────┘           │   └─────────────┬─────────────┘      │
                 │                         │                 │                    │
        Direct USB / Serial                │        Direct USB / Serial           │
                 ▼                         │                 ▼                    │
     [Scanner, Printer, Drawer]            │     [Scanner, Printer, Drawer]       │
                 │                         │                 │                    │
           Ethernet / IP                   │           Ethernet / IP              │
                 ▼                         │                 ▼                    │
      [Payment Terminal - EMV]             │      [Payment Terminal - EMV]        │
                                           │                                      │
                                           └───────────────┬──────────────────────┘
                                                           ▼
                                            ┌─────────────────────────────┐
                                            │   BACKOFFICE WORKSTATION    │
                                            │   & MOBILE RECEIVING TABLET │
                                            │ • Invoice Review & Diff     │
                                            │ • PO Generation & Auditing  │
                                            └─────────────────────────────┘

Component Nodes

1. Register Lane Node (POS Client):

   • High-performance single-page application (React / Vite + Tailwind CSS) packaged inside a lightweight native runtime (Tauri or Electron).
   • Embedded local data store (SQLite via WASM/native binding) containing the complete product catalog, barcode index, customer lookup, and active promotion rules.
   • Local Hardware Abstraction Layer (HAL) connecting to receipt printers, cash drawers, barcode scanners, and customer displays.

2. In-Store Edge Server (Store Hub):

   • Dedicated appliance or backoffice PC running Linux/Windows.
   • Hosts the master store database (PostgreSQL 16+), the core API service (Node.js/Fastify or Go), and background workers.
   • Orchestrates real-time state synchronization across register lanes via WebSockets.
   • Executes heavy background operations: parsing PDF/EDI/CSV invoices, calculating margin impact, and managing scheduled reports.

3. Cloud Synchronization Service (Optional / Hybrid):

   • Acts as remote backup, remote backoffice access gateway, and QuickBooks Online sync agent.
   • Receives append-only event streams from the in-store server.

3. Resilient Local-First Synchronization Engine

The Problem

Traditional web POS systems freeze or show spinning loaders when the internet or local WiFi wavers. In a busy liquor store, line delays cause walkouts and lost revenue.

The Solution: Append-Only Event Journaling

Every state-changing event on a register (item added to cart, cart finalized, cash payment tendered, drawer kick) is written synchronously to the register's local SQLite journal before any network call is initiated.

[Cashier Action] ──► [Local SQLite WAL Write] ──► [Immediate UI Feedback (<16ms)]
                             │
                             ▼ (Asynchronous LAN Dispatch)
                 [In-Store Edge Server PostgreSQL]
                             │
                             ▼ (Out-of-Band Cloud Push)
                 [Cloud Backup & QuickBooks Engine]

Outage Mode (Network Partition)

• If the LAN connection to the Edge Server fails:
  1. The register UI displays a subtle amber badge: "Offline Mode — Local Cache Active".
  2. Products scan with zero latency directly from SQLite.
  3. Cash sales, manual cards, and offline store-and-forward card transactions (if enabled on payment terminal) proceed normally.
  4. Completed transactions receive an immutable offline_transaction_uuid.
  5. When LAN connectivity resumes, the register automatically replays unacknowledged transaction events to the master PostgreSQL database using idempotent upserts.

4. Security, Authentication & PCI-DSS Scope Minimization

1. Zero Cardholder Data Touch (PCI-DSS Scope Reduction)

• The POS application never receives, processes, or stores primary account numbers (PAN), CVVs, PINs, or track data.
• Payment integration uses a Semi-Integrated Model:
  1. POS sends transaction total and invoice ID over local IP or USB to the EMV terminal (e.g. PAX, Dejavoo, Stripe Terminal, Clover Mini).
  2. Customer inserts, taps, or swipes on the physical terminal.
  3. Terminal communicates directly with the payment gateway over encrypted TLS.
  4. Terminal returns only: status: approved, auth_code: "09428A", card_brand: "VISA", last4: "4242", token: "tok_...".
  5. The POS register stays in PCI-DSS SAQ-A or SAQ-A-EP scope.

2. Fast Cashier Switching & Role-Based Access Control (RBAC)

• Liquor store registers frequently switch cashiers between shifts or during breaks.
• Cashier login utilizes:
  • 4-digit PIN on dedicated touch keypad or physical numpad.
  • Barcode cashier badge scan (CASHIER-104).
  • Instant auto-lock timer (configurable, default 120 seconds of inactivity).
• Permission tiers:
  • Cashier: Scan, tender, return with receipt, view line items.
  • Shift Lead: Line item void, price check, manual 21+ ID bypass, cash drop.
  • Manager: Return without receipt, manual line discount, cash drawer open without sale, end-of-day Z-report.
  • Admin: Full access, employee wage management, database configuration, QuickBooks OAuth.

5. Technology Stack Selection Matrix