MPAC Docs

Appearance

Technical Architecture ​

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

Overview ​

This section documents the technical architecture of the MPAC platform, covering service communication patterns, database design, security mechanisms, and performance/scalability strategies. The architecture is designed to support 400,000+ concurrent devices, 80M daily transactions, and 15,000 RPS sustained throughput while maintaining 99.9% availability and comprehensive security controls.

Architecture Documents ​

1. Communication Patterns ​

Purpose: Define service communication protocols and authentication mechanisms.

Key Topics:

  • Frontend → Backend communication (JWT-based)
  • SmartPOS Device → Backend (OAuth2 private_key_jwt)
  • Service-to-Service (HMAC-SHA256)
  • WebView SDK → Payment Gateway (Bearer tokens)
  • External Provider Webhooks (signature verification)
  • Android Intent-based inter-app communication

Use Cases:

  • Understanding API authentication flows
  • Implementing service integrations
  • Debugging communication issues
  • Security protocol reference

2. Database Architecture ​

Purpose: Define database ownership, schema patterns, and synchronization mechanisms.

Key Topics:

  • Database ownership boundaries (svc-portal, svc-smarttab, mpac-pgw)
  • Multi-tenancy isolation patterns
  • Hybrid enum handling (TEXT + CHECK constraints)
  • Indexing and partitioning strategies
  • Data synchronization (svc-portal → mpac-pgw)

Use Cases:

  • Schema design and migrations
  • Query optimization
  • Multi-tenant data isolation
  • Cross-service data consistency

3. Security Architecture ​

Purpose: Define authentication, authorization, encryption, and compliance requirements.

Key Topics:

  • Authentication methods (Human, Device, S2S)
  • Role-based access control (RBAC)
  • JWT token formats and validation
  • Data encryption (at rest and in transit)
  • PCI DSS compliance measures
  • Audit logging and monitoring

Use Cases:

  • Implementing authentication flows
  • Configuring authorization rules
  • Security audits and compliance
  • Incident response procedures

4. Performance & Scalability ​

Purpose: Define performance targets, scalability strategies, and observability requirements.

Key Topics:

  • Performance targets (latency, throughput, availability)
  • Horizontal scaling strategies
  • Database optimization (read replicas, connection pooling, partitioning)
  • Caching strategies (Redis, application-level)
  • Monitoring and observability (mpac-obs stack)

Use Cases:

  • Performance tuning and optimization
  • Capacity planning and scaling
  • Troubleshooting performance issues
  • SLA monitoring and alerting

Key Design Principles ​

1. Stateless Architecture ​

All backend services are stateless to enable horizontal scaling. Session state is stored in Redis, and WebSocket connections are managed by dedicated connection servers.

2. Multi-Tenancy Isolation ​

All operational tables include tenant scoping (merchant_id, store_id) with automatic filtering at the middleware level to prevent cross-tenant data leakage.

3. Defense in Depth ​

Security controls are implemented at multiple layers:

  • Network (VPC, security groups, WAF)
  • Transport (TLS 1.2+)
  • Application (JWT validation, HMAC signatures)
  • Data (encryption at rest, field-level encryption)
  • Audit (comprehensive logging)

4. Observability First ​

All services emit structured logs, metrics, and traces using OpenTelemetry standards, with centralized collection via the mpac-obs stack (Prometheus, Loki, Tempo, Grafana).

5. Eventual Consistency ​

The system accepts eventual consistency for non-critical data (merchant/store sync, reporting data) while maintaining strong consistency for critical operations (payments, authentication).

Technology Stack ​

Backend Services ​

  • svc-portal: Python 3.11+, FastAPI, SQLAlchemy 2.0 (async)
  • svc-smarttab: Go 1.24, Gin
  • mpac-pgw: Go 1.24, Gin, GORM

Databases ​

  • Primary: PostgreSQL 15+ (AWS RDS)
  • Cache: Redis 7+ (ElastiCache)
  • Message Queue: NATS JetStream (planned)

Observability (mpac-obs) ​

  • Metrics: Prometheus 3.8
  • Logs: Loki 3.6
  • Traces: Tempo 2.9
  • Collector: Alloy 1.12
  • Visualization: Grafana 12.3

Infrastructure ​

  • Cloud: AWS (ECS Fargate, RDS, ElastiCache, S3, CloudFormation)
  • Load Balancing: Application Load Balancer (ALB)
  • API Gateway: Kong or Krakend (planned)

System Capacity ​

Current Scale Requirements ​

  • Concurrent Devices: 400,000+ SmartPOS terminals
  • Daily Transactions: 80M payments
  • Peak Throughput: 15,000 RPS sustained
  • Multi-Tenancy: PSP → Merchant → Store hierarchy
  • Availability: 99.9% uptime (8.76h downtime/year)

Resource Allocation ​

  • ECS Tasks: 2-50 per service (auto-scaling)
  • Database Connections: 200 max per service (via pgBouncer)
  • Redis Memory: 12 GB per cluster
  • Storage: Partitioned by month, 12-month retention
  • Bandwidth: <100 Mbps for WebSocket fleet

Integration Points ​

Internal Service Communication ​

  • Frontend ↔ Backend: REST APIs with JWT authentication
  • svc-smarttab ↔ mpac-pgw: HMAC-authenticated REST APIs
  • svc-portal ↔ mpac-pgw: Data sync via REST APIs
  • Business App ↔ Credit Card App: Android Intent-based

External Integrations ​

  • Payment Providers: Webhooks with signature verification
  • Observability: OTLP protocol (gRPC/HTTP)
  • Alerting: PagerDuty, Slack
  • Authentication: OAuth2, JWKS

Cross-References ​

  • AWS Infrastructure - ECS deployment architecture
  • API Reference - Complete endpoint documentation
  • WebSocket Protocol - Real-time device communication
  • Load Testing - Performance test scenarios
  • Security Testing - Penetration testing procedures
  • Integration Testing - Service integration tests

Quick Reference ​

Performance Targets ​

  • P50 Latency: <200ms
  • P95 Latency: <500ms
  • P99 Latency: <1000ms
  • Availability: 99.9%
  • Error Rate: <0.5%

Authentication Token TTLs ​

  • Human JWT: 15 minutes
  • Device JWT: 60-120 seconds
  • Payment Token: 5 minutes
  • HMAC: Request-scoped (5-minute window)

Database Patterns ​

  • Multi-tenancy: Always filter by merchant_id/store_id
  • Enums: TEXT with CHECK constraint
  • Partitioning: Monthly for high-volume tables
  • Indexes: Tenant-scoped composite indexes

Security Controls ​

  • Authentication: JWT (RS256/ES256), HMAC-SHA256
  • Authorization: Role-based (RBAC)
  • Encryption: TLS 1.2+, AES-256 at rest
  • Compliance: PCI DSS Level 1

Previous: SettlementNext: Communication PatternsUp: Main PRD

MPAC — MP-Solution Advanced Cloud Service

MP Solution Inc.