Skip to Content
ArchitectureInfrastructure Overview

Infrastructure Overview

Gatelithix Gateway runs on Google Cloud Platform with strict PCI DSS 4.0.1 segmentation between the core project and the PCI CDE zone. All services are deployed as stateless Cloud Run containers.

Architecture Diagram

Service Overview

ServiceProjectMin InstancesMax InstancesIngressMemoryPurpose
API GatewayCore110Internal + LB512MiPublic API, AuthN/AuthZ, rate limits, routing
Token VaultPCI15Internal Only256MiPAN encryption/tokenization, PCI CDE
Stripe ConnectorCore05Internal Only256MiStripe PSP integration
NMI ConnectorCore05Internal Only256MiNMI PSP integration
FluidPay ConnectorCore05Internal Only256MiFluidPay PSP integration
Admin PortalCore03Internal + LB256MiMerchant management dashboard
Docs SiteCore02Internal + LB256MiDeveloper documentation

Network Architecture

VPC Design

The infrastructure uses two separate VPCs connected via VPC peering:

  • Core VPC (core-vpc): 10.0.0.0/20 primary, 10.0.16.0/24 database, 10.0.17.0/24 Redis, 10.0.32.0/28 serverless connector
  • PCI VPC (pci-vpc): 10.1.0.0/20 primary, 10.1.16.0/24 database, 10.1.17.0/24 Redis, 10.1.32.0/28 serverless connector

Firewall Rules

A deny-all baseline is inherited from the VPC module. Explicit allow rules permit only minimum required traffic:

RuleDirectionSource/DestinationPortPurpose
core-vpc-allow-pci-egressEgress10.1.0.0/20443Core to PCI CDE cross-zone calls
pci-vpc-allow-core-ingressIngress10.0.0.0/20443Accept calls from core VPC
core-vpc-allow-psp-egressEgress0.0.0.0/0443Connectors to PSP APIs
pci-vpc-allow-psp-egressEgress0.0.0.0/0443PCI to PSP APIs (tagged)
pci-vpc-allow-restricted-apisEgress199.36.153.4/30443Google restricted API access

VPC Peering

Bidirectional peering (core-to-pci and pci-to-core) connects the two VPCs. Custom route exchange is disabled — only auto-subnet routes are shared. This ensures the PCI zone cannot reach arbitrary core resources and vice versa; traffic is limited to Cloud Run service-to-service calls via Serverless VPC Connectors.

Data Flow

A typical payment request flows through the system as follows:

  1. Client sends HTTPS request to api.gatelithix.com (port 443)
  2. Cloud Load Balancer terminates TLS, applies Cloud Armor WAF rules (OWASP CRS: SQLi, XSS, LFI, RFI, RCE), rate limiting (1000 req/min per IP)
  3. API Gateway authenticates the request (Auth0 JWT or API key), validates idempotency key, checks rate limits in Redis
  4. Gateway creates a PaymentIntent in Core Cloud SQL and determines the target connector via the routing engine
  5. If the request includes raw card data, Gateway proxies to the Token Vault via VPC peering to tokenize the PAN
  6. Vault encrypts the PAN using Cloud KMS HSM, stores the encrypted PAN in PCI Cloud SQL, and returns a gateway token
  7. Gateway calls the selected Connector (Stripe, NMI, or FluidPay) with the token or processor token
  8. Connector calls the PSP API and returns a normalized response
  9. Gateway updates the PaymentIntent status and publishes a payment.events message to Pub/Sub
  10. Pub/Sub triggers merchant webhook delivery via the webhook-outbound subscription

PCI CDE Boundary

In Scope (PCI Project)

ComponentJustification
Token Vault (Cloud Run)Processes, encrypts, and stores PANs
PCI Cloud SQLStores encrypted cardholder data
Cloud KMS HSMHSM-backed encryption keys for PAN encryption and fingerprinting
PCI VPCNetwork boundary for CDE segmentation
PCI Secret ManagerStores PCI database credentials

Out of Scope (Core Project)

ComponentJustification
API GatewayNever sees raw PANs (proxies to vault for tokenization)
ConnectorsUse gateway tokens or processor tokens, never raw PANs
Core Cloud SQLStores payment intents, merchants, billing — no cardholder data
RedisCaches idempotency keys and rate limits — no cardholder data
Pub/SubEvent messages contain payment intent IDs, never PANs
Admin Portal / DocsNo cardholder data access

Segmentation Controls

  • Separate GCP projects: Core and PCI workloads run in isolated GCP projects with independent IAM policies
  • VPC peering with deny-all: Default firewall denies all traffic; explicit allow rules for port 443 only
  • INTERNAL_ONLY ingress: Vault Cloud Run service rejects all external traffic
  • Cross-project IAM: Gateway service account is explicitly granted roles/run.invoker on the vault service
  • KMS key restriction: Only the vault service account has cryptoKeyEncrypterDecrypter and signerVerifier roles
ChangelogDatabase Schema