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.