Qris-Soundbox/01-executive-blueprint.md

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