Chapter 05: High-Level Architecture
The Complete System Overview
This chapter presents the complete high-level architecture of the POS Platform. Every component, connection, and data flow is documented here as the authoritative reference for implementation.
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
The POS Platform follows a clean three-tier architecture with clear separation of concerns.
Tier 1: Cloud Layer (External Services)
External cloud services that the platform integrates with:
| Service | Purpose | Protocol | Data Flow |
|---|---|---|---|
| Shopify API | E-commerce sync | REST/GraphQL | Bidirectional |
| Payment Gateway | Card processing | REST + Webhooks | Request/Response |
| Tax Service | Tax calculation | REST | Request/Response |
| Email Service | Notifications | SMTP/API | Outbound only |
| SMS Service | Alerts | API | Outbound only |
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)
The heart of the platform - all business logic resides here.
API Gateway
The gateway handles cross-cutting concerns before requests reach services:
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
| Service | Responsibilities | Key Endpoints |
|---|---|---|
| Catalog Service | Products, categories, pricing, variants | /api/v1/products/* |
| Sales Service | Transactions, receipts, refunds, holds | /api/v1/sales/* |
| Inventory Service | Stock levels, adjustments, transfers | /api/v1/inventory/* |
| Customer Service | Profiles, loyalty, purchase history | /api/v1/customers/* |
| Employee Service | Users, roles, permissions, shifts | /api/v1/employees/* |
| Sync Service | Offline sync, conflict resolution | /api/v1/sync/* |
Tier 3: Data Layer (Persistence)
All data storage and caching systems:
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)
The primary point-of-sale terminal application.
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 | | |
| | +--------------------+ | |
| +---------------------------+ |
+-------------------------------------------------------------------+
Key Features:
- Offline-first with local SQLite database
- Automatic sync when connectivity restored
- Hardware integration (printers, scanners, drawers)
- Multi-register support per location
Admin Portal (Web)
Management dashboard for administrators and managers.
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)
Mobile application for RFID inventory operations.
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 | | |
| | +------------------+ | | +---------------------+ | |
| +------------------------+ +---------------------------+ |
+-------------------------------------------------------------------+
Data Flow Patterns
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) |
Service Boundaries
Each service owns its data and exposes it only through APIs.
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
| Layer | Technology | Justification |
|---|---|---|
| API Gateway | Kong or NGINX | Proven, scalable, plugin ecosystem |
| Central API | ASP.NET Core 8.0 | Performance, C# ecosystem, EF Core |
| Database | PostgreSQL 16 | Schema-per-tenant, JSON support, reliability |
| Cache | Redis | Session storage, real-time features |
| Event Store | PostgreSQL (append-only) | Simplicity, same DB engine |
| POS Client | Electron or Tauri | Cross-platform desktop, offline SQLite |
| Admin Portal | React + TypeScript | Modern SPA, rich ecosystem |
| Mobile App | .NET MAUI | C# codebase, Zebra RFID SDK support |
| Real-time | SignalR | Inventory broadcasts, notifications |
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 | |
| +-----------------------+ +-----------------------+ |
+------------------------------------------------------------------+
System Flow Overview: From Subscription to Operations
This section explains how the complete system works from a tenant’s perspective - from initial subscription through daily operations.
The Tenant Journey
TENANT JOURNEY: Subscription → Deployment → Operations
======================================================
STEP 1: SUBSCRIPTION
┌─────────────────────────────────────────────────────────────────────────────┐
│ Prospective tenant visits pos-platform.com │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Select Plan │ → │ Create Account │ → │ Payment Setup │ │
│ │ - Starter $49 │ │ - Company info │ │ - Stripe billing │ │
│ │ - Pro $149 │ │ - Admin user │ │ - Trial period │ │
│ │ - Enterprise $499│ │ - Store count │ │ - Auto-provision │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ AUTOMATIC PROVISIONING │ │
│ │ • Create tenant schema: CREATE SCHEMA tenant_{id} │ │
│ │ • Create admin user with temporary password │ │
│ │ • Apply plan limits (stores, registers, features) │ │
│ │ • Generate API keys (Enterprise tier only) │ │
│ │ • Send welcome email with login credentials │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
STEP 2: ADMIN PORTAL ACCESS
┌─────────────────────────────────────────────────────────────────────────────┐
│ Tenant admin logs into Admin Portal (React SPA) │
│ https://app.pos-platform.com │
│ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ INITIAL SETUP WIZARD │ │
│ │ │ │
│ │ 1. Configure Locations → Add store addresses, assign codes │ │
│ │ 2. Import Products → CSV upload or Shopify sync │ │
│ │ 3. Create Employee Accounts → Set roles (Manager, Cashier) │ │
│ │ 4. Configure Tax Rates → By state/locality │ │
│ │ 5. Set Up Payment → Connect Stripe/Square terminal │ │
│ │ 6. Download Client Apps → POS Client + Raptag Mobile │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
STEP 3: CLIENT APPLICATION DEPLOYMENT
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ POS CLIENT DOWNLOAD │ │ RAPTAG MOBILE DOWNLOAD │ │
│ │ │ │ │ │
│ │ From Admin Portal: │ │ From Admin Portal: │ │
│ │ Settings → Downloads │ │ Settings → Downloads │ │
│ │ │ │ │ │
│ │ ┌─────────────────────┐ │ │ ┌─────────────────────┐ │ │
│ │ │ Download for: │ │ │ │ Download for: │ │ │
│ │ │ • Windows (x64) │ │ │ │ • Android (APK) │ │ │
│ │ │ • macOS (Intel/ARM) │ │ │ │ │ │ │
│ │ │ • Linux (AppImage) │ │ │ │ Scan QR code or │ │ │
│ │ └─────────────────────┘ │ │ │ email download link │ │ │
│ │ │ │ └─────────────────────┘ │ │
│ │ Installer includes: │ │ │ │
│ │ • Pre-configured API URL │ │ App auto-discovers: │ │
│ │ • Tenant ID embedded │ │ • Cloud API endpoint │ │
│ │ • SQLite for offline │ │ • Authenticates via QR │ │
│ │ │ │ │ │
│ └─────────────────────────────┘ └─────────────────────────────┘ │
│ │
│ INSTALLATION (per store computer): │
│ 1. Run installer │
│ 2. Log in with employee credentials │
│ 3. Select store location │
│ 4. Initial sync downloads: products, customers, pricing │
│ 5. Ready to ring sales! │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
STEP 4: DAILY OPERATIONS
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ ALL CLIENTS CONNECT TO CLOUD │ │
│ │ │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ POS │ │ POS │ │ Raptag │ │ Admin │ │ │
│ │ │ Store 1 │ │ Store 2 │ │ Mobile │ │ Portal │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ │ │ │ │ │ │
│ │ │ WiFi/LAN │ WiFi │ Browser │ │ │
│ │ │ │ │ │ │ │
│ │ └──────────────┴──────────────┴──────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌──────────────────────────┐ │ │
│ │ │ CENTRAL CLOUD API │ │ │
│ │ │ (Multi-Tenant SaaS) │ │ │
│ │ │ │ │ │
│ │ │ • Real-time sync │ │ │
│ │ │ • Inventory updates │ │ │
│ │ │ • Sales aggregation │ │ │
│ │ │ • Report generation │ │ │
│ │ └──────────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ KEY POINT: POS Client and Raptag are SIBLINGS, not parent-child │
│ - Both connect directly to Cloud API │
│ - Both can work offline (local SQLite cache) │
│ - Both sync independently when connectivity restored │
│ - Raptag does NOT connect to POS Client │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Component Relationship Diagram
Understanding how the three client applications relate:
┌─────────────────────────────────────────┐
│ CENTRAL CLOUD API │
│ (The Single Source of Truth) │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Multi-Tenant PostgreSQL │ │
│ │ └── tenant_acme (schema) │ │
│ │ ├── products │ │
│ │ ├── inventory │ │
│ │ ├── sales │ │
│ │ └── customers │ │
│ └─────────────────────────────────┘ │
└─────────────────┬───────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ POS CLIENT │ │ ADMIN PORTAL │ │ RAPTAG MOBILE │
│ (Desktop App) │ │ (Web App) │ │ (Mobile App) │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ │ │ │ │ │
│ PURPOSE: │ │ PURPOSE: │ │ PURPOSE: │
│ Ring sales, │ │ Manage business,│ │ RFID inventory, │
│ process payments│ │ view reports, │ │ quick counts, │
│ │ │ configure system│ │ transfers │
│ │ │ │ │ │
│ OFFLINE: ✓ │ │ OFFLINE: ✗ │ │ OFFLINE: ✓ │
│ (SQLite cache) │ │ (Requires net) │ │ (SQLite cache) │
│ │ │ │ │ │
│ USERS: │ │ USERS: │ │ USERS: │
│ Cashiers, │ │ Owner, Admin, │ │ Stock clerks, │
│ Managers │ │ Managers │ │ Managers │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
NOTE: These are THREE INDEPENDENT applications
Each connects DIRECTLY to Cloud API
They do NOT connect to each other
Offline Mode Explained
When network connectivity is lost:
ONLINE MODE (Normal) OFFLINE MODE (Network Lost)
==================== ============================
┌─────────────┐ ┌──────────┐ ┌─────────────┐ ┌──────────┐
│ POS Client │────▶│ Cloud │ │ POS Client │ ✗ │ Cloud │
│ │◀────│ API │ │ │ │ API │
└─────────────┘ └──────────┘ └──────┬──────┘ └──────────┘
│
▼
┌──────────────┐
│ LOCAL SQLite │
│ │
│ • Products │ ← Pre-synced catalog
│ • Prices │ ← Pre-synced pricing
│ • Customers │ ← Pre-synced data
│ • Pending │ ← Queue of sales
│ Sales │ awaiting sync
└──────────────┘
WHEN CONNECTIVITY RESTORED:
1. Sync service wakes up
2. Pending sales pushed to Cloud API
3. Cloud applies changes (with conflict resolution)
4. Fresh catalog/inventory pulled down
5. Local SQLite updated
Summary
This high-level architecture provides:
- Clear separation between cloud services, API layer, data layer, and clients
- Multi-tenant design with schema-per-tenant isolation
- Offline-first POS clients with sync queue
- Event-driven inventory and sales tracking
- Scalable stateless API servers behind load balancer
- Secure with TLS, JWT, RBAC, and audit logging
The following chapters dive deep into each architectural decision, starting with multi-tenancy in Chapter 06.