Architecture Overview

System Topology

The MPAC platform consists of three systems, each deployed in its own isolated VPC in ap-northeast-1 (Tokyo). Systems communicate exclusively over public HTTPS endpoints. Environments (dev/staging/prod) are separated by AWS account, not region.

Domain Naming

System	Subdomain	Example URLs (dev)
mpac-smartpos	(primary)	api.mpac-cloud-dev.com, portal.mpac-cloud-dev.com
mpac-pgw	pgw	api.pgw.mpac-cloud-dev.com
mpac-obs	obs	grafana.obs.mpac-cloud-dev.com, otlp.obs.mpac-cloud-dev.com

Base domains: mpac-cloud.com (prod), mpac-cloud-dev.com (dev), mpac-cloud-stg.com (staging).

Multi-Tenant Hierarchy

ClientPartner is the top-level entity (API client). Each ClientPartner has multiple Merchants, each with multiple Stores. Stores have StoreProviderConfig entries for per-store payment provider credentials.

PaymentIntent State Machine

Three processing modes:

• pgw_processed - QR payments via provider APIs
• external - Credit card via external app
• manual - Cash payments

Clean Architecture (mpac-pgw)

pgw/internal/
├── api/              # HTTP handlers, middleware, router
├── domain/           # Business entities, interfaces, services
│   ├── payment/      # PaymentIntent + Transaction + state machine
│   ├── clientpartner/# API client entity
│   ├── merchant/     # Business entity under ClientPartner
│   ├── store/        # Store + StoreProviderConfig
│   └── provider/     # QRProvider interface + registry
├── infrastructure/   # Database, cache, provider adapters
├── config/           # Viper config management
├── telemetry/        # OpenTelemetry setup
└── pkg/              # Shared utilities (errors, ULID, constants)

Authentication

• Server-to-server: HMAC-SHA256 with the byte representation of the hex-encoded SHA-256 of the secret key (64 ASCII bytes)
• Client/SDK: payment_token for client-side operations

See API Authentication Guide for details.

Observability Flow

All telemetry is correlated via trace_id, span_id, and service label.