# VietQR Core SDK System Architecture (PaaS & SaaS)

## 1. Overview

**VietQR Core SDK** is an enterprise-grade payment infrastructure adhering strictly to Vietnamese National Standards (NAPAS 247) and the international EMVCo QR specification. Key architectural pillars include:
- **Zero Third-Party Dependency:** Completely independent of external CDNs or APIs (e.g. no reliance on `img.vietqr.io` or `cdn.vietqr.io`). All bank logos, brand assets, typography, and QR image renderers are hosted 100% on your own server.
- **Custom Domain Ready:** All image QuickLinks (`/image/{bin}-{acc}-{template}.png`) and interactive Deeplink Hubs (`/qr/pay`) dynamically resolve against your configured custom domain (e.g., `https://qr.yourdomain.com`).
- **High Performance:** Gateway core built with **Rust (Axum + Tokio)**, sustaining tens of thousands of generation requests per second with RAM footprints below 50MB.
- **Multi-Platform & Multi-Architecture:** Native support for Windows, Linux, and macOS on `x86`, `x64`, `ARMv7`, and `ARM64`.

---

## 2. PaaS & SaaS Architecture Diagram

```
+-------------------------------------------------------------------------------+
|                                  CLIENTS                                      |
|  +--------------------+  +--------------------+  +-------------------------+  |
|  | Web Browser / Ecom |  | iOS / Android Apps |  | ERP / POS / Backend API |  |
|  +---------+----------+  +---------+----------+  +------------+------------+  |
+------------|-----------------------|--------------------------|---------------+
             |                       |                          |
             v                       v                          v
+-------------------------------------------------------------------------------+
|                    REVERSE PROXY & SSL (NGINX / CADDY / CLOUDFLARE)           |
|                https://qr.yourdomain.com (Let's Encrypt TLS)                  |
+------------------------------------+------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------------+
|                       VIETQR GATEWAY ENGINE (RUST SERVICE)                    |
|                                                                               |
|  +------------------------+  +----------------------+  +-------------------+  |
|  |  QuickLink Image API   |  |   Web Deeplink Hub   |  |     REST API      |  |
|  |  /image/{slug}.png     |  |   /qr/pay (Mobile)   |  |  /api/v1/generate |  |
|  +-----------+------------+  +----------+-----------+  +---------+---------+  |
|              |                          |                        |            |
|              v                          v                        v            |
|  +-------------------------------------------------------------------------+  |
|  |                           CORE MODULES                                  |  |
|  |  - EMVCo TLV Generator & Parser (CRC16-CCITT False: 0x1021)             |  |
|  |  - High Performance Canvas Renderer (compact, compact2, standee, sepay) |  |
|  |  - Bank Catalog & Local Assets Registry (62+ Vietnamese Banks)          |  |
|  |  - Deeplink Registry (35+ Banking Apps via Direct URL Schemes)         |  |
|  +-------------------------------------------------------------------------+  |
|                                     |                                         |
|                                     v                                         |
|  +-------------------------------------------------------------------------+  |
|  |                       LOCAL ASSETS & STORAGE                            |  |
|  |  assets/banks/*.png | assets/brand/*.png | assets/fonts/Roboto-Bold.ttf |  |
|  +-------------------------------------------------------------------------+  |
+-------------------------------------------------------------------------------+
                                     ^
                                     | Direct SDK embedding or Gateway REST
+------------------------------------+------------------------------------------+
|                         MULTILINGUAL SDK SUITE                                |
|  +--------+  +----------+  +------+  +------+  +---------+  +-----+  +------+ |
|  | C (C99)|  | C++(C++17|  | Rust |  |  Go  |  | Node/TS |  | PHP |  | Java | |
|  +--------+  +----------+  +------+  +------+  +---------+  +-----+  +------+ |
|  +--------+  +----------+                                                     |
|  | Python |  |  .NET C# |                                                     |
|  +--------+  +----------+                                                     |
+-------------------------------------------------------------------------------+
```

---

## 3. EMVCo & NAPAS 247 Specification

The generated QR code strictly adheres to the EMVCo Merchant-Presented QR standard:
- **Tag 00 (Payload Format Indicator):** Constant `"01"`.
- **Tag 01 (Point of Initiation Method):**
  - `"11"`: Static QR (Fixed counter, user enters variable amount).
  - `"12"`: Dynamic QR (Order-specific, pre-defined amount and memo).
- **Tag 38 (Merchant Account Information - VietQR NAPAS 247):**
  - Sub-tag `00` (Globally Unique Identifier): `"A000000727"` (NAPAS routing ID).
  - Sub-tag `01` (Payment Network Specific):
    - Sub-tag `00`: 6-digit Bank BIN (e.g. `970436` for Vietcombank).
    - Sub-tag `01`: Beneficiary Account Number.
  - Sub-tag `02` (Service Code):
    - `"QRIBFTTA"`: Transfer to Account.
    - `"QRIBFTTC"`: Transfer to Card.
- **Tag 53 (Transaction Currency):** `"704"` (ISO 4217 VND code).
- **Tag 54 (Transaction Amount):** Positive integer (e.g. `"100000"`).
- **Tag 58 (Country Code):** `"VN"`.
- **Tag 59 (Merchant Name):** Beneficiary name in uppercase ASCII (max 25 characters).
- **Tag 62 (Additional Data Field Template):**
  - Sub-tag `08` (Purpose of Transaction): Order memo (max 50 chars, auto-normalized without Vietnamese diacritics for 100% banking app compatibility).
- **Tag 63 (CRC):** 4 uppercase hex digits computed via CRC16-CCITT False (`Polynomial: 0x1021`, `Initial Value: 0xFFFF`, no reflection).