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:

Continuous POS operation is non-negotiable. Physical stores must be able to process transactions even during brief network outages. The system uses an online-first architecture with a thin offline fallback (ADR-048) — the API is the primary data source under normal conditions, with a minimal SQLite cache that activates only when connectivity is lost.

Architectural Implications:

• API-primary data access via React Query (server state management)
• 3-state connection monitor (ONLINE / DEGRADED / OFFLINE)
• 2-table SQLite fallback (product_cache + sales_queue)
• FIFO queue flush on reconnection
• Flag-on-sync price discrepancy for manager review

Online-First Justification

The online-first design keeps POS terminals operational under all network conditions while avoiding the complexity of full local database replication:

Online-First with Offline Fallback
====================================

Normal Operation (ONLINE):
  All reads via React Query → Central API → PostgreSQL
  Real-time prices, inventory, customer data
  No local database sync overhead

Intermittent Connectivity (DEGRADED):
  Reads continue via React Query (stale-while-revalidate)
  Writes queue locally in sales_queue table
  Socket.io heartbeat detects degraded state

Network Outage (OFFLINE):
  Product lookups from product_cache (read-only SQLite)
  Sales written to sales_queue (FIFO)
  POS continues processing sales with cached prices

Reconnection:
  sales_queue entries flush to API in FIFO order
  Server applies current prices, flags discrepancies
  product_cache refreshes from API

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

Event Sourcing Supports Offline Queue

Event sourcing (Ch 04 Section L.4A) supports availability by providing a natural model for the offline sales queue. When the POS client is offline, completed sales are captured as immutable events in the local sales_queue. When connectivity is restored, these events are submitted to the central API in FIFO order. Because each event has a unique ID and the server is the authority on current state, the queue flush is straightforward — no conflict resolution or event merging is required. The server accepts each sale, applies current pricing, and flags any discrepancies for review.

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: IntegrationProvider interface with 5 standard methods per provider: connect(), syncProducts(), syncInventory(), validateData(), healthCheck()
• 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 (IntegrationProvider) 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 (dependency-cruiser) 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    |  | (Nexus POS 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

Row-Level Security (RLS) isolation (from Ch 04 Section L.10A.4) provides a strong security boundary enforced at the PostgreSQL database level. Every tenant table includes a tenant_id column and an RLS policy that automatically filters queries by the tenant context set in the connection session variable. Even if application code omits a WHERE tenant_id = ? clause, PostgreSQL’s RLS policies prevent cross-tenant data access:

-- RLS policy on every tenant table
CREATE POLICY tenant_isolation ON products
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

-- Middleware sets tenant context from JWT claims
SET app.current_tenant = 'uuid-of-nexus-tenant';

-- Query automatically filtered by RLS — returns only Nexus products
SELECT * FROM products;

-- Even a query without WHERE clause is safe — RLS enforces isolation
SELECT * FROM orders;
-- Returns only orders for the current tenant

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

Row-Level Security (RLS) 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 Row-Level Security (RLS):
- Every table has tenant_id + RLS policy enforced at database level
- RLS policies automatically filter queries — no risk of missing WHERE clause
- Clear audit trail per tenant_id
- Data export for GDPR: SELECT * FROM customers WHERE tenant_id = :id
- Data deletion for "right to be forgotten": DELETE cascading on tenant_id
- Defense-in-depth: even buggy application code cannot leak cross-tenant data

Per-tenant data export is achieved via COPY (SELECT * FROM table WHERE tenant_id = :id) TO STDOUT, making data portability and right-to-erasure requests straightforward. RLS enforcement at the database level provides defense-in-depth isolation that does not depend on application-level query 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 Nexus POS
• 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. See also Ch 04 Section L.6 for TPS targets and latency budgets.

Architectural Implications:

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

Multi-Tenant Performance Considerations

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

Connection Pooling:

Connection Pool Strategy (Row-Level Security)
==============================================

                    +------------------+
                    |  Connection Pool |
                    |  (PgBouncer)     |
                    +--------+---------+
                             |
        +--------------------+--------------------+
        |                    |                    |
        v                    v                    v
+-------+-------+   +--------+------+   +---------+-----+
| Connection 1  |   | Connection 2  |   | Connection 3  |
| Shared pool   |   | Shared pool   |   | Shared pool   |
| All tenants   |   | All tenants   |   | All tenants   |
+---------------+   +---------------+   +---------------+

Tenant context set per-transaction via middleware:
  SET LOCAL app.current_tenant_id = '<tenant-uuid>';

Use transaction pooling mode in PgBouncer.
Connections are shared across all tenants (no per-tenant pools).

Query Performance:

Row-Level Security uses composite indexes on (tenant_id, ...) so that the RLS policy filter and application query merge into a single efficient index scan:

-- Composite index ensures tenant_id filter is nearly free
CREATE INDEX idx_products_tenant_sku ON products(tenant_id, sku);
CREATE INDEX idx_sales_tenant_date ON sales(tenant_id, sale_date);

-- RLS policy automatically appends tenant filter
-- Application writes simple queries:
SELECT * FROM products WHERE sku = 'NXP0001';
-- PostgreSQL rewrites to:
SELECT * FROM products
 WHERE sku = 'NXP0001'
   AND tenant_id = current_setting('app.current_tenant_id')::uuid;

The composite index prefix on tenant_id ensures the RLS predicate adds negligible overhead — PostgreSQL’s query planner merges the policy filter with application predicates for a single index scan. Shared tables also improve cache utilization for common catalog data.

Tenant Performance Isolation

Row-Level Security provides logical performance isolation between tenants. Composite indexes on (tenant_id, ...) ensure each tenant’s queries scan only their own rows, so a tenant with a large product catalog does not degrade query performance for other tenants. Maintenance operations can target tenant-specific data using partial operations:

-- Analyze statistics for tenant-heavy tables
VACUUM ANALYZE products;
VACUUM ANALYZE sales;

-- Partial reindex targeting specific indexes
REINDEX INDEX CONCURRENTLY idx_products_tenant_sku;

-- Monitor per-tenant table bloat via pg_stat_user_tables
-- Alert when dead_tup_ratio exceeds threshold

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       |
| (Online+Fallback)|                  | (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 online-first architecture with thin offline fallback per ADR-048 — brief network outages handled by 2-table SQLite cache and FIFO sales queue)
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.