Initial commit

01-executive-blueprint.md

@@ -0,0 +1,79 @@
+# Executive Blueprint - QRIS Soundbox Platform v1
+
+## 1. Ringkasan
+Platform ini dirancang sebagai **Merchant Aggregator QRIS + Payment Orchestration + Soundbox/TMS Platform**.
+
+Sistem menangani:
+- onboarding merchant
+- koneksi ke bank, issuer, acquirer, atau partner QRIS
+- konfigurasi SNAP BI / QRIS integration
+- pemrosesan transaksi QRIS statis dan dinamis
+- ledger internal dan perhitungan hak merchant
+- settlement/disbursement ke merchant
+- manajemen device soundbox lintas vendor
+- notifikasi pembayaran realtime ke device
+- dashboard admin, ops, finance, dan merchant
+
+## 2. Objective
+Tujuan utama sistem:
+1. mendukung banyak jenis soundbox tanpa vendor lock-in
+2. memusatkan kontrol payment dan orkestrasi payout di backend perusahaan, sementara pencairan diproses sesuai rekening/flow payout milik merchant (non-tersentral pada MVP)
+3. memastikan transaksi, ledger, dan settlement dapat diaudit
+4. memberi notifikasi realtime ke merchant melalui soundbox
+5. menyediakan fondasi yang bisa dicicil implementasinya per fase
+
+## 3. Prinsip Kunci
+- backend adalah pusat logika sistem
+- device adalah channel, bukan pusat source of truth
+- callback/webhook payment partner adalah sumber status transaksi eksternal
+- ledger internal adalah sumber kebenaran finansial internal (pending settlement, fee, dan entitlement)
+- settlement/payout dipisah dari payment event dan dapat dikoordinasikan via partner payout merchant
+- device support berbasis capability, bukan hardcode per vendor
+- TMS adalah domain inti, bukan tambahan
+- semua aksi kritikal harus memiliki audit trail
+
+## 4. Tipe Device yang Didukung
+### 4.1 Soundbox Static
+- QR merchant statis
+- transaksi masuk via callback partner
+- backend melakukan mapping ke merchant/outlet/terminal/device
+- notifikasi sukses dikirim ke device via MQTT
+
+### 4.2 Soundbox Dynamic MQTT-only
+- device membuat request QR dynamic via MQTT
+- backend memproses request dan mengirim hasil via MQTT
+- payment success tetap berasal dari callback partner
+- notifikasi sukses ke device via MQTT
+
+### 4.3 Soundbox Dynamic API-direct
+- device dapat hit API backend langsung
+- request-response create QR dilakukan via API
+- payment success tetap berasal dari callback partner
+- notifikasi sukses ke device via MQTT
+
+## 5. Domain Inti
+- Merchant & Onboarding
+- Payment Integration
+- Transaction
+- Ledger & Settlement
+- Device/TMS
+- Notification
+- Operations & Governance
+
+## 6. Keputusan Arsitektur Final
+1. one unified backend
+2. support multi-protocol ingress untuk device
+3. use capability-based routing untuk flow device
+4. use QRIS/payment callback as external payment status trigger
+5. use internal ledger for merchant payable and settlement
+6. support admin portal dan merchant portal terpisah
+7. design all critical integration points with idempotency and auditability
+
+## 7. Hasil yang Diharapkan dari Paket Ini
+Dokumen ini menjadi fondasi untuk:
+- diskusi arsitektur
+- desain UI/UX
+- breakdown sprint engineering
+- definisi database awal
+- definisi API dan kontrak MQTT
+- roadmap delivery bertahap