Qris-Soundbox/02-system-architecture.md

System Architecture - QRIS Soundbox Platform v1

1. Posisi Sistem

Platform diposisikan sebagai:

• merchant aggregator
• payment orchestrator
• device orchestration platform untuk soundbox lintas vendor

2. Context Eksternal

Pihak eksternal

• Merchant
• Customer payer
• Bank / Issuer / Acquirer / Aggregator QRIS
• SNAP BI / QRIS integration provider
• Device vendor / soundbox devices

3. Layer Arsitektur

Layer 1. Experience Layer

• Admin Web Portal
• Merchant Web Portal
• Ops / Finance Dashboard
• Device UI / Soundbox UI

Layer 2. Access Layer

• API Gateway
• MQTT Broker
• Webhook Receiver
• Auth Gateway

Layer 3. Device Abstraction Layer

• MQTT Adapter
• API Adapter
• Capability Resolver
• Command Router
• Notification Router
• Payload Normalizer

Layer 4. Core Business Layer

• Merchant Service
• Outlet Service
• Terminal Service
• Device/TMS Service
• QRIS Service
• Transaction Service
• Ledger Service
• Settlement Service
• Notification Service
• Reconciliation Service
• Audit Service

Layer 5. Integration Layer

• Bank Connector
• QRIS Partner Connector
• SNAP BI Connector
• Payout / Disbursement Connector

Layer 6. Data Layer

• Merchant Database
• Transaction Database
• Ledger Database
• Device Database
• Audit Log Store
• Queue / Event Store
• Configuration Store

4. Arsitektur Logis

Merchant/Admin/Finance/Device
        |
        v
Access Layer (API Gateway / MQTT Broker / Webhook Receiver)
        |
        v
Device Abstraction + Auth + Capability Resolver
        |
        v
Core Business Services
        |
        +--> Payment/QRIS Integrations
        +--> Ledger & Settlement
        +--> TMS & Notification
        |
        v
Databases / Event Store / Audit Logs

5. Prinsip Routing Device

Static device

• tidak perlu create QR request
• device mainly menerima payment notification

Dynamic MQTT-only device

• uplink via MQTT
• downlink via MQTT
• async success via MQTT

Dynamic API-direct device

• create QR via API
• async success via MQTT
• ops/config dapat via API atau MQTT tergantung capability

6. Prinsip Integrasi Payment

• semua request ke bank/partner dilakukan oleh backend kita
• semua callback payment diterima oleh backend kita
• device tidak pernah menjadi source of truth transaksi
• status transaksi final berasal dari backend setelah verifikasi callback atau reconciliation

7. Prinsip Finansial

• dana customer dihimpun sesuai flow partner/integrasi payout merchant (tanpa vault settlement pusat di awal MVP)
• ledger internal mencatat hak merchant, fee, penyesuaian, dan status reconciliation payout
• settlement/disbursement dieksekusi sebagai domain terpisah dari transaction event

8. Prinsip Operasional

• semua perubahan entity penting harus diaudit
• onboarding merchant harus punya status workflow
• device harus punya heartbeat, last seen, config version, dan binding history
• delivery notification harus dapat di-track dan di-retry

9. NFR Utama

• idempotency untuk create QR, callback, payout, notification
• observability untuk payment, device, settlement
• auditability untuk finance dan merchant changes
• multi-tenant isolation
• secure device auth
• HA untuk broker, callback receiver, dan transaction services