System Architecture
Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28
Overview
This document provides the high-level system architecture for the MPAC SmartPOS Cloud Platform, showing the relationship between client applications, backend services, and infrastructure components.
System Architecture Diagram
┌─────────────────────────────────────────────────────────────────┐
│ Client Layer │
├─────────────────┬──────────────────┬───────────────────────────┤
│ Portal Web UI │ WebView Apps │ Android Terminal Apps │
│ (Admins) │ (In-Terminal) │ (Business, QR, Card) │
└────────┬────────┴────────┬─────────┴──────────┬────────────────┘
│ │ │
│ │ (Direct HTTPS) │
│ │ │
│ ┌────────▼────────┐ │
│ │ mpac-pgw │ │
│ │ (Go/Gin) │ │
│ │ │ │
│ │ Payment Gateway│ │
│ └────────┬────────┘ │
│ │ │
└─────────────────┴────────────────────┘
│
┌──────▼──────┐
│ API Gateway │
│ (Kong/etc.) │
└──────┬──────┘
┌─────────────────┴─────────────────┐
│ │
┌────▼────┐ ┌─────▼─────┐
│svc-portal│ │svc-smarttab│
│(FastAPI) │ │ (Go/Gin) │
│ │ │ │
│Auth, IAM,│ │Orders,Bills│
│Devices, │◄──────────────────────►│Payments, │
│Merchants │ (Service-to-Service) │Customers │
└────┬─────┘ └─────┬──────┘
│ │
│ ┌──────────────┐ │
└───────────►│ mpac-pgw │◄───────┘
│ (Go/Gin) │
└──────┬───────┘
│
┌───────────────────┴───────────────────┐
│ │
┌────▼─────┐ ┌───────▼────────┐
│PostgreSQL│ │ Redis │
│(Primary) │ │ (Cache/Rate │
│ │ │ Limiting) │
└──────────┘ └────────────────┘Architecture Layers
1. Client Layer
Portal Web UI (React/Vite)
- Purpose: Administrative interface for PSP/Merchant/Store management
- Users: System operators, PSP admins, merchant admins, store managers
- Access: Web browser (desktop/tablet)
- Key Features:
- Device fleet management
- Order and payment monitoring
- User administration with RBAC
- Financial reporting and analytics
- Configuration management
WebView Apps (React)
- Purpose: In-terminal web applications for customer interaction
- Deployment: Embedded in Android terminal apps via WebView
- Key Features:
- Menu browsing and ordering
- Payment method selection
- Receipt display
- Customer feedback
Android Terminal Apps (Kotlin)
- Purpose: Native applications running on SmartPOS hardware
- Apps:
- Business App (main POS application)
- QR App (QR payment processing)
- Card App (card payment processing)
- Key Features:
- Order creation and management
- Payment processing (online/offline)
- Hardware integration (printer, scanner, NFC)
- Local data caching
- Background synchronization
2. API Gateway Layer
API Gateway (Kong/AWS API Gateway)
- Purpose: Entry point for Portal and Terminal App requests
- Responsibilities:
- Request routing to backend services
- Authentication and authorization
- Rate limiting and throttling
- Request/response transformation
- SSL termination
- API versioning
Routing Rules:
/auth/*→ svc-portal/devices/*→ svc-portal/merchants/*,/stores/*→ svc-portal/orders/*,/bills/*→ svc-smarttab/payments/*→ svc-smarttab
Direct Access (Bypassing API Gateway):
- WebView Apps →
https://mpac-pgw.domain.com/v1/payment-intents/*- WebView apps embedded in terminals connect directly to mpac-pgw
- Uses bearer token authentication (@cloudsky/mpac-pgw-sdk-js)
- Optimized for low-latency payment processing
Service-to-Service:
- svc-smarttab ↔ mpac-pgw (internal payment processing)
- svc-portal ↔ mpac-pgw (configuration sync)
- Uses HMAC-SHA256 authentication for S2S calls
3. Application Services Layer
svc-portal (Python/FastAPI)
Domain Responsibilities:
- Identity & Access Management (IAM)
- Human authentication (email/password + MFA)
- Device authentication (OAuth2 private_key_jwt)
- JWT token issuance and validation
- Device & Terminal Management
- Device registration and provisioning
- Configuration management
- Hardware inventory
- Merchant & Store Hierarchy
- PSP/Merchant/Store CRUD operations
- Tenant isolation
- User management with RBAC
- App Update Management
- APK versioning and distribution
- Staged rollout strategies
Technology Stack:
- Language: Python 3.11+
- Framework: FastAPI (async)
- ORM: SQLAlchemy 2.0 (async)
- Database: PostgreSQL (primary)
- Cache: Redis
- Migrations: Alembic
svc-smarttab (Go/Gin)
Domain Responsibilities:
- Order & Bill Management
- Order creation and lifecycle
- Bill generation and splitting
- Order status tracking
- Payment Processing
- Multi-payment method support
- Refund processing
- Payment method configuration
- Customer Management
- Customer profiles and history
- Customer segmentation
- Receipt & Invoice Management
- Receipt generation (thermal/digital)
- Tax invoice creation
- Settlement & Reconciliation
- Daily settlement processing
- Financial reporting
- Reporting & Analytics
- Real-time dashboards
- Transaction analytics
Technology Stack:
- Language: Go 1.24
- Framework: Gin
- ORM: GORM
- Database: PostgreSQL (primary)
- Message Queue: NATS
- API Docs: Swagger/OpenAPI
mpac-pgw (Go/Gin)
Domain Responsibilities:
- Payment Gateway Service
- PaymentIntent abstraction layer
- External provider integrations (PromptPay, SCB, KBank, etc.)
- Webhook management
- Idempotency and retry logic
- Rate limiting (1000/min/merchant, 10000/min global)
Technology Stack:
- Language: Go 1.24
- Framework: Gin (migrating from go-kit)
- ORM: GORM
- Database: PostgreSQL
- Cache: Redis (idempotency, rate limiting)
- Authentication: HMAC-SHA256
- Observability: OpenTelemetry
Performance Targets:
- P95 Latency: < 200ms
- P99 Latency: < 500ms
- Availability: 99.95%
4. Data Layer
PostgreSQL (Primary Database)
- Purpose: Persistent relational data storage
- Deployment: Amazon RDS PostgreSQL
- Configuration:
- Primary-replica setup for read scaling
- Multi-AZ deployment for high availability
- Automated backups with point-in-time recovery
- Data Domains:
- User accounts and permissions
- Device inventory and configuration
- Merchant/store hierarchy
- Orders, bills, payments
- Customer profiles
- Transaction history
- Settlement records
Redis (Cache & Session Storage)
- Purpose: Fast in-memory data access
- Deployment: Amazon ElastiCache for Redis
- Use Cases:
- Session storage (JWT blacklisting)
- Rate limiting counters
- Idempotency key storage (mpac-pgw)
- Application caching (frequent queries)
- Real-time metrics aggregation
Service Communication Patterns
Frontend ↔ Backend
- Protocol: HTTPS REST APIs
- Auth: JWT Bearer tokens (Authorization header)
- Format: JSON request/response
- WebSocket: Persistent connections for real-time updates
Service-to-Service (S2S)
- Protocol: HTTP/HTTPS
- Auth: Service-specific API keys or mTLS
- Format: JSON
- Pattern: Direct service calls with circuit breakers
Backend ↔ External Providers
- Protocol: HTTPS
- Auth: Provider-specific (API keys, OAuth2, HMAC)
- Pattern: Async webhooks for callbacks
- Retry Logic: Exponential backoff with max attempts
Data Flow Example: Payment Transaction
┌──────────────┐
│ Terminal App │
└──────┬───────┘
│ 1. Create Order
▼
┌─────────────────┐
│ svc-smarttab │
│ POST /orders │
└─────────┬───────┘
│ 2. Create PaymentIntent
▼
┌─────────────────────────┐
│ mpac-pgw │
│ POST /payment-intents │
└─────────┬───────────────┘
│ 3. Process Payment
▼
┌─────────────────────┐
│ Provider (PromptPay)│
│ /charge │
└─────────┬───────────┘
│ 4. Webhook Callback
▼
┌─────────────────────────┐
│ mpac-pgw │
│ POST /webhooks/:provider│
└─────────┬───────────────┘
│ 5. Update Payment Status
▼
┌─────────────────┐
│ svc-smarttab │
│ PATCH /payments │
└─────────┬───────┘
│ 6. Notify Terminal
▼
┌──────────────┐
│ Terminal App │
│ (WebSocket) │
└──────────────┘Infrastructure Architecture
┌─────────────────────────────────────────────────────┐
│ AWS Cloud │
├─────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────┐ │
│ │ VPC (Multi-AZ) │ │
│ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Public │ │ Private │ │ │
│ │ │ Subnets │ │ Subnets │ │ │
│ │ │ │ │ │ │ │
│ │ │ - ALB │ │ - ECS │ │ │
│ │ │ - NAT GW │ │ - RDS │ │ │
│ │ │ │ │ - ElastiCache│ │ │
│ │ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ Additional Services: │
│ - S3 (APK storage, backups) │
│ - CloudFront (CDN for static assets) │
│ - Route 53 (DNS management) │
│ - CloudWatch (Logs & Metrics) │
│ - Secrets Manager (Credentials) │
│ - ECS Fargate (Container orchestration) │
└─────────────────────────────────────────────────────┘Security Architecture
Network Security
- VPC Isolation: Private subnets for application/database layers
- Security Groups: Least-privilege firewall rules
- TLS/SSL: End-to-end encryption (TLS 1.3)
- WAF: Web Application Firewall for DDoS protection
Application Security
- Authentication: JWT with short TTL (15-min human, 60-120s device)
- Authorization: Role-based access control (RBAC)
- Secrets Management: AWS Secrets Manager, no hardcoded credentials
- Input Validation: Strict schema validation on all endpoints
Compliance
- PCI DSS: Tokenization for card data, no storage of CVV
- GDPR: Data privacy controls, consent management
- Audit Logging: Comprehensive audit trail for all operations
Observability Stack (mpac-obs)
Components
- Metrics: Prometheus for time-series metrics
- Logs: Loki for log aggregation
- Traces: Tempo for distributed tracing
- Dashboards: Grafana for visualization
- Collection: Alloy (OTLP collector)
Integration
- OTLP Ingestion: Port 4317 (gRPC) / 4318 (HTTP)
- Service Discovery: Auto-discovery from ECS tags
- Data Retention: 14 days (configurable)
- Correlations: Trace-to-logs, trace-to-metrics
See Also
Related Documents:
- Product Overview - Platform capabilities
- Scale Requirements - Performance targets
- Communication Patterns - Detailed integration patterns
- Database Architecture - Data modeling
Deployment:
- AWS Infrastructure - Detailed AWS resources
- Deployment Strategy - Blue-green deployment
Security:
- Security Architecture - Comprehensive security design
Navigation: ↑ Back to Index | ← Previous: Scale Requirements | Next: Business Domains →