Sentra Retail — Architecture & Tech Stack Delta¶

System Architecture¶

Sistem mengadopsi arsitektur Hybrid Offline-First with Cloud Synchronization. Terminal POS di toko berjalan secara independen tanpa bergantung penuh pada server cloud, sementara manajemen backoffice terpusat mengonsolidasi seluruh data toko secara realtime.

3.1 C4 Container Diagram¶

graph TB
    subgraph "Toko Fisik (Edge)"
        A["POS Client App (Electron / React)"]
        B["Local SQLite Database"]
        A <-->|Read/Write| B
    end

    subgraph "Cloud Backend Services"
        C["API Gateway / Reverse Proxy (Nginx)"]
        D["Auth Service (Go / NestJS)"]
        E["Sync & Transaction Engine (Go)"]
        F["Backoffice Web Console (Next.js)"]

        G[("PostgreSQL Master (Transactional DB)")]
        H[("Redis Cache & Websocket Session Store")]
    end

    A -->|1. Sync Data via WebSockets / HTTPS| C
    F -->|2. CRUD & Admin Dashboard| C
    C --> D
    C --> E
    E <--> G
    E <--> H
    D <--> G

3.2 Sync Protocol (Protokol Sinkronisasi Offline-Online)¶

Aplikasi POS menggunakan mekanisme sinkronisasi berbasis antrean (Event Queue) dengan algoritma deteksi konflik Version Vector:

1. Local Transaction Record: Saat transaksi offline, POS menyimpan data di tabel transactions dengan status PENDING_SYNC dan mengenerate UUID unik sebagai Primary Key.
2. Outbox Pattern: Setiap transaksi memicu entri di tabel local_outbox_queue lokal.
3. Background Sync Worker: Worker berjalan setiap 30 detik (atau langsung saat koneksi terdeteksi terhubung kembali), membaca antrean outbox, mengirimkan payload terkompresi Gzip ke endpoint /api/v1/pos/sync.
4. Idempotency Guarantee: Server cloud menggunakan UUID transaksi sebagai kunci idempotensi untuk mencegah duplikasi data jika koneksi terputus di tengah proses transfer.
5. Stock Resolution Algorithm: Jika stok cabang berkurang secara offline sementara di cloud ada mutasi stok online, server cloud akan menghitung sisa stok menggunakan formula urutan waktu mutasi logis (Logical Lamport Timestamp).

Tech Stack — Retail Delta¶

Baseline: _shared/tech-stack-baseline.md

Overrides¶

• POS Client App → React + Electron / Tauri (alasan: native Windows OS support untuk kasir lama, native printer driver untuk struk termal)

Tambahan Sistem-Spesifik¶

• Local POS DB: SQLite + SQLCipher (AES-256-GCM, key derivation dari user PIN + machine ID)
• Communication: MQTT Broker untuk IoT POS (barcode scanner, EDC)