Initial commit

02-system-architecture.md

@@ -0,0 +1,126 @@
+# 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
+```text
+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