# Architecture Overview

This document describes the architecture and design of the Antom Payments for WooCommerce plugin.

## System Layers

```
┌──────────────────────────────────────────────────────────────┐
│                    WooCommerce Store                          │
├──────────────┬──────────────────┬────────────────────────────┤
│  Classic     │  Block Checkout  │  Order Pay Page            │
│  Checkout    │  (React)         │  (Re-payment)              │
├──────────────┴──────────────────┴────────────────────────────┤
│                    Gateway Layer (PHP)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ Payments │ │  Card    │ │ AlipayCN │ │  ...     │        │
│  │  (CKP)   │ │(Elements)│ │(Wallet)  │ │(Wallet)  │        │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
│       └────────────┼────────────┼────────────┘              │
│                    ▼                                         │
│              ┌───────────┐                                   │
│              │  Common   │  Shared process_payment,          │
│              │  Gateway  │  webhook, refund logic            │
│              └─────┬─────┘                                   │
│                    ▼                                         │
│  ┌──────────────────────────────────────┐                    │
│  │            SDK Layer                 │                    │
│  │  Client → Signature → HTTP RPC       │                    │
│  │  Request Builder (pay/session/refund) │                   │
│  └─────────────┬────────────────────────┘                    │
│                ▼                                             │
│  ┌──────────────────────────────────────┐                    │
│  │          Model Layer                 │                    │
│  │  Order / Amount / Buyer / Env /      │                    │
│  │  Settlement / PaymentMethod / Refund │                    │
│  └──────────────────────────────────────┘                    │
└─────────────────────────┬────────────────────────────────────┘
                          │
                          ▼
               ┌─────────────────────┐
               │    Antom API        │
               │  open-sea.alipay    │
               │  .com               │
               └─────────────────────┘
```

## Layer Descriptions

### 1. Presentation Layer

The plugin supports two checkout modes:

- **Classic Checkout** — Standard WooCommerce checkout page with server-rendered payment fields
- **Block Checkout** — React-based WooCommerce Block Checkout with custom JavaScript frontend components

Frontend source code lives in `resource/` and is compiled to `assets/`.

### 2. Gateway Layer

Each payment method is a separate WooCommerce payment gateway class extending `WC_Gateway_Antom_Common`:

| Class | File | Payment Method |
|---|---|---|
| `WC_Gateway_Antom_Payments` | `gateways/class-wc-gateway-antom-payments.php` | Cashier Payment (CKP) — aggregates all methods |
| `WC_Gateway_Antom_Card` | `gateways/class-wc-gateway-antom-card.php` | Credit/Debit cards via Antom Elements |
| `WC_Gateway_Antom_Alipay_CN` | `gateways/class-wc-gateway-antom-alipay-cn.php` | Alipay (China) |
| `WC_Gateway_Antom_Alipay_HK` | `gateways/class-wc-gateway-antom-alipay-hk.php` | Alipay (Hong Kong) |
| `WC_Gateway_Antom_Dana` | `gateways/class-wc-gateway-antom-dana.php` | DANA (Indonesia) |
| `WC_Gateway_Antom_GCash` | `gateways/class-wc-gateway-antom-gcash.php` | GCash (Philippines) |
| `WC_Gateway_Antom_Kakao_Pay` | `gateways/class-wc-gateway-antom-kakao-pay.php` | Kakao Pay (Korea) |
| `WC_Gateway_Antom_Naver_Pay` | `gateways/class-wc-gateway-antom-naver-pay.php` | Naver Pay (Korea) |
| `WC_Gateway_Antom_Tng` | `gateways/class-wc-gateway-antom-tng.php` | Touch 'n Go (Malaysia) |
| `WC_Gateway_Antom_Toss_Pay` | `gateways/class-wc-gateway-antom-toss-pay.php` | Toss Pay (Korea) |
| `WC_Gateway_Antom_True_Money` | `gateways/class-wc-gateway-antom-true-money.php` | TrueMoney (Thailand) |

#### Common Gateway (`WC_Gateway_Antom_Common`)

The abstract base class that provides shared functionality:

- `process_payment($order_id)` — Core payment processing
- `payment_notify_handler()` — Webhook notification handler
- `inquiry_handler()` — Payment status inquiry handler
- `process_refund($order_id, $amount, $reason)` — Refund processing
- Currency filtering and display logic
- Settings form fields generation

#### Block Support

Each gateway has a corresponding block support class (in `includes/blocks/`) that enables Block Checkout compatibility via the WooCommerce Blocks integration API.

### 3. Block Checkout Frontend

The `resource/` directory contains React components for each payment method:

- **Block Components** (`resource/blocks/`) — One JS file per payment method, registered as WooCommerce Blocks payment method integrations
- **Shared Components** (`resource/components/`) — Reusable React components for card fields, labels, and warnings
- **Custom Hooks** (`resource/hooks/`) — React hooks for settings and API interactions
- **CSS** (`resource/css/`) — SCSS source files compiled to `assets/css/`

Build toolchain: Webpack (`wp-scripts`) for JavaScript, Sass for CSS.

### 4. SDK Layer

The SDK handles all communication with the Antom API:

| Component | File | Responsibility |
|---|---|---|
| `Antom_Alipay_Client` | `sdk/antom-alipay-client.php` | HTTP client: signature, request, response handling |
| `Antom_Signature_Tool` | `sdk/antom-signature-tool.php` | RSA-SHA256 signature generation and verification |
| `Antom_Http_Rpc_Result` | `sdk/antom-http-rpc-result.php` | RPC response parsing |
| `SDK_Antom_Alipay_Request` | `sdk/sdk-antom-alipay-request.php` | Base request builder |
| `SDK_Antom_Alipay_Online_Request` | `sdk/sdk-antom-alipay-online-request.php` | Online payment request builder |
| `SDK_Antom_Alipay_Inquiry_Request` | `sdk/sdk-antom-alipay-inquiry-request.php` | Payment inquiry request builder |

**Request Flow:**

1. Gateway calls SDK with order data
2. Request builder constructs the API request with required parameters
3. Signature tool generates RSA-SHA256 signature
4. HTTP client sends the signed request to Antom API
5. Response is received and signature-verified
6. Result is parsed and returned to the gateway

### 5. Model Layer

Data models encapsulate the request/response data structure:

- **Order Models** — Order amount, buyer info, environment, payment method, settlement strategy
- **Refund Model** — Refund request/response data

### 6. Admin Layer

The `Antom_Admin` class (singleton) handles:

- Welcome page rendering (for new installations)
- Core settings page rendering and saving
- Order list filters and columns
- Payment method ordering and visibility
- Abnormal order warnings

## Key Flows

### Payment Flow (Digital Wallet)

```
Customer clicks "Place Order"
        │
        ▼
Gateway::process_payment()
        │
        ├─► Build order models (amount, buyer, env, etc.)
        ├─► SDK::create_payment_session()
        │       │
        │       └─► Antom API → returns paymentUrl / formHtml
        │
        └─► Return redirect URL or payment form
                │
                ▼
        Customer completes payment on
        Antom Hosted Checkout page
                │
                ▼
        Antom sends webhook notification
        ──► payment_notify_handler()
                │
                ├─► Verify signature
                ├─► Update order status
                └─► Redirect to order-received page
```

### Card Payment Flow (Antom Elements)

```
Customer enters card details
        │
        ▼
Antom Elements SDK (client-side encryption)
        │
        ▼
AJAX → antom_ajax_create_payment_session()
        │
        ├─► SDK::create_payment_session()
        └─► Returns paymentSession data
                │
                ▼
Customer confirms payment
        │
        ▼
Gateway::process_payment() → SDK → Antom API
        │
        ▼
Payment result processed
```

### Refund Flow

```
Admin clicks "Refund" in WooCommerce
        │
        ▼
Gateway::process_refund()
        │
        ├─► Build refund model
        ├─► SDK → Antom API (refund request)
        └─► Update order with refund status
```

## Plugin Bootstrap

The plugin entry point is `antom-payments-gateway.php`:

1. **Constants defined** — Plugin file path, version, URL
2. **WooCommerce check** — Verifies WooCommerce is active on activation
3. **File loading** (`antom_includes()`):
   - Utilities (options, request checker)
   - Settings and statements
   - Common functions
   - Admin or Frontend class
   - All gateway classes (registered in `antom_get_payment_methods()`)
   - Block support classes
   - Form API
4. **Translation** — Loads text domain for i18n

## Payment Method Registration

Payment methods are defined in `antom_get_payment_methods()` (`includes/antom-payment-gateway-settings.php`). Each method includes:

- `gateway_file` — PHP gateway class file path
- `gateway_class` — WooCommerce gateway class name
- `block_file` — Block support class file path
- `block_support_class` — Block support class name
- `slug` — Unique identifier (e.g., `antom_alipay_cn`)
- `payment_method_type` — Antom API payment method type (e.g., `ALIPAY_CN`)
- `support_currencies` — Array of supported currency codes
- `icon` — Payment method logo URL

The list is filterable via the `antom_payment_gateway_settings` hook.

## Security Architecture

- **Card Data** — All card data is encrypted client-side via Antom Elements SDK; no plaintext card data touches the merchant server
- **API Signing** — All requests signed with merchant's RSA private key; responses verified with Antom's public key
- **Nonce Verification** — AJAX endpoints use WordPress nonce for CSRF protection
- **Input Sanitization** — All user inputs sanitized via WordPress core functions (`sanitize_text_field`, `absint`, etc.)
- **Payment Request ID** — Unique ID per payment to prevent replay attacks

## Configuration Storage

Plugin settings are stored in the WordPress `wp_options` table with the prefix `antom_payment_gateway_`, managed by the singleton `Antom_Payment_Gateways_Options` class.

## See Also

- [Payment Methods](payment-methods.md) — Supported methods and currencies
- [Webhook & API Reference](webhook-api.md) — Webhook and SDK API details
- [Development Guide](development.md) — Build and development