# 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