API Gateway Architecture and Governance Architect

Wrote docs/architecture/gateway-architect/00-overview/gateway-architect-overview.md and docs/architecture/gateway-architect/verification/fitness-self-check.md. Complete API Gateway platform architecture specification establishing centralized mTLS 1.3 termination, cryptographic JWT validation, fair multi-tier rate limiting, failure isolation, and sub-4.5ms gateway routing overhead.

---

skill: gateway-architect

API Gateway Platform Architecture: Open Banking Platform [GW-BANK-001]

Summary

This specification establishes the enterprise API Gateway platform architecture, ingress traffic topology, protocol mediation, identity context propagation, and failure isolation for open-banking-api-gateway v3.0 under run ID open-banking-gw-001. It governs ingress traffic across 140 certified fintech partners and 85 internal backend microservices sustaining 32,000 peak requests/second. It decisively resolves the security vulnerabilities and blast-radius coupling demonstrated in incident SEC-4890 (where an unpatched JWT parser in a legacy loan service allowed forged tokens to leak 120,000 customer records) and incident INC-5102 (where an unthrottled partner burst 40,000 requests/minute, exhausting backend connection pools and starving all other partners). The architecture enforces

centralized mTLS 1.3 edge termination, offloads

cryptographic OAuth2 / JWT validation at the ingress perimeter, executes

protocol mediation (translating external REST/JSON to internal gRPC), enforces

fair multi-tier token-bucket rate limiting, and guarantees a gateway routing overhead ceiling of

p99 <= 4.5 ms while strictly excluding business logic and downstream resource authorization from the mediation tier.

Detailed Description

Forcing individual microservices to terminate external ingress, validate certificates, enforce ad-hoc rate limits, and negotiate transport protocols creates severe vulnerability sprawl and operational fragility. When individual service teams maintain bespoke authentication middleware, uncoordinated library patching inevitably introduces critical security vulnerabilities. Conversely, concentrating domain logic or resource-level authorization within an edge proxy creates an unmaintainable release bottleneck and a monolithic failure domain. This architecture establishes a minimum-sufficient mediation layer: terminating public TLS, sanitizing client transport headers, validating cryptographic identity tokens, enforcing per-consumer rate limits, and propagating verified caller context to backend services over an internal mutual-TLS mesh.

External Fintech Partners (32,000 req/sec)
                         │
                         ▼ (Public Internet over mTLS 1.3)
[ Tier 1: Cloud Network Load Balancer (AWS NLB) ]
  └── Layer 4 TCP Passthrough with PROXY Protocol v2 (Preserves True Client IP)
                         │
                         ▼
[ Tier 2: API Gateway Fleet (Envoy Proxy Fleet on AWS EKS) ]
  ├── 1. Edge Transport Termination: TLS 1.3 + PSD2 eIDAS QWAC Validation
  ├── 2. Authentication Offload: Ed25519/RS256 JWT Signature Verification via JWKS
  ├── 3. Header Sanitization: Strips Spoofed `X-Forwarded-*`, `X-Authenticated-*`
  ├── 4. Token-Bucket Rate Limiter: Multi-Tier Quotas (Redis Distributed Cluster)
  ├── 5. Protocol Mediation: REST/JSON to High-Performance Internal gRPC
  └── 6. Context Injection: Passes Signed `X-Verified-Caller-Context`
                         │
        ┌────────────────┴────────────────┐
        ▼ (Internal gRPC over mTLS)       ▼ (Internal gRPC over mTLS)
[ `account-ledger-service` ]       [ `payment-initiation-service` ]
  ├── Resource-Level ABAC            ├── Resource-Level ABAC
  └── Canonical Domain Invariants    └── Canonical Domain Invariants

Mechanism Specifications

1. Component Boundary:

   • Owner: Lead Ingress Architect (David O'Reilly).
   • Trigger: Inbound TCP connection and HTTPS request on port 443 at the edge ingress listener.
   • State/Algorithm: The gateway acts as a stateless reverse proxy and mediation pipeline. It terminates TLS, decrypts packets, validates public protocol structure, verifies bearer token cryptographic signatures, extracts caller identity claims, sanitizes untrusted incoming transport headers, and matches host/path prefixes against an immutable, registry-compiled route table. It does NOT evaluate resource-level permissions (e.g. whether user X owns account Y) and does NOT execute domain data transformations.
   • Failure Behavior: Malformed HTTP requests return HTTP 400 Bad Request. TLS handshake failures drop immediately without backend dispatch.
   • Test Oracle: Automated network probe verifying that invalid HTTP syntax or untrusted TLS certificates terminate at Tier 2 without generating backend access logs.

2. Port And Adapter:

   • Owner: Ingress Platform Engineering Squad.
   • Trigger: Public HTTP/1.1 or HTTP/2 caller invocation requiring translation to internal microservice protocols.
   • State/Algorithm: Inbound edge adapter accepts REST/JSON over HTTPS. The gateway translates JSON payloads into Protocol Buffers and establishes HTTP/2 gRPC connections to upstream service endpoints. Outbound responses translate gRPC status codes into RFC 9457 Problem Details JSON documents.
   • Failure Behavior: gRPC connection failure to upstream returns HTTP 503 Service Unavailable with a standard application/problem+json payload.
   • Test Oracle: Contract test suite asserting 1:1 mapping between external REST query parameters and internal gRPC message fields without payload truncation.

3. Runtime Flow:

   • Owner: Core API Governance Guild (Elena Rostova).
   • Trigger: Ingress request arriving with Authorization: Bearer <token> and client mTLS certificate.
   • State/Algorithm:
     1. NLB terminates L4 and passes client IP via PROXY Protocol v2.
     2. Gateway terminates TLS 1.3, verifies client certificate against regulatory trust store.
     3. Gateway inspects JWT signature against cached JWKS (ed25519 / RS256); checks exp, nbf, iss, and aud.
     4. Token-bucket rate limiter queries local Redis cache for consumer quota key rate:{client_id}:{route}.
     5. If quota available, gateway strips untrusted caller headers and mints an immutable internal assertion header X-Verified-Caller-Context.
     6. Request is dispatched to upstream service pool via least-request load balancing with an upstream timeout ceiling of 2,500 ms.
   • Failure Behavior: Expired or unsigned token returns HTTP 401 Unauthorized with WWW-Authenticate: Bearer error="invalid_token". Rate limit exhaustion returns HTTP 429 Too Many Requests with Retry-After header.
   • Test Oracle: End-to-end integration test asserting valid requests traverse all 6 steps within 4.5 ms p99 latency envelope.

4. Failure Policy:

   • Owner: Reliability Engineering Guild (Elena Rostova).
   • Trigger: Upstream microservice degradation, timeout expiration, or gateway resource exhaustion.
   • State/Algorithm:
     • Upstream Timeout: Gateway enforces a hard 2,500 ms timeout on upstream calls. Upon expiration, the gateway terminates the upstream stream immediately (cancellation propagation) and returns HTTP 504 Gateway Timeout.
     • Gateway Retries: Gateway retries are strictly prohibited for non-idempotent methods (POST, PATCH) to prevent duplicate financial mutations. For idempotent GET calls, gateway retries are capped at exactly 1 attempt only on transport-level connect failures (never on HTTP 5xx responses).
     • Load Shedding: Under gateway CPU/memory saturation (> 85%), load shedding rejects unauthenticated/anonymous traffic first, internal traffic second, and certified partner traffic last.
   • Failure Behavior: When backend is unreachable, gateway returns HTTP 503 Service Unavailable with Retry-After: 5. It does NOT retry or stack calls on failing backends.
   • Test Oracle: Chaos fault injection drill verifying that an unresponsive backend triggers clean HTTP 504 in <= 2,505 ms with zero retry multiplication on downstream services.

Architectural Concerns

1. API Gateway:

   • Trace to source: Root mandate from Elena Rostova and David O'Reilly following security breach SEC-4890.
   • Architectural consequence: Eliminates fragmented perimeter defense; centralizes TLS termination and cryptographic token validation while preserving backend service autonomy.
   • Enforcement: Ingress security groups and AWS PrivateLink restrict backend microservice network access exclusively to the API Gateway cluster IP range.
   • Recovery route: Emergency bypass requires dual-key cryptographic approval from CISO and Lead Ingress Architect, routing traffic through a dedicated fallback proxy.

2. Rate Limiting:

   • Trace to source: Partner starvation incident INC-5102 where one misconfigured partner consumed 100% of shared backend worker threads.
   • Architectural consequence: Replaces global rate limits with per-consumer-class and per-route quotas with a strict fairness goal: no consumer may degrade another.
   • Enforcement: Redis-backed distributed token bucket filter with sub-millisecond atomic counter evaluation.
   • Recovery route: Operators can adjust tenant tier quotas dynamically via GitOps configuration without restarting gateway proxy instances.

3. Routing & Auth:

   • Trace to source: Enterprise Open Banking Compliance mandate (PSD2 RTS Article 34) and Zero Trust architecture policy.
   • Architectural consequence: Gateway authenticates caller identity and client certificates, but delegates resource-level authorization (ABAC) to backend services.
   • Enforcement: Gateway strips caller-supplied identity headers and injects a signed, tamper-proof X-Verified-Caller-Context containing verified client_id, partner_tier, and subject.
   • Recovery route: Upstream services reject any request lacking a valid gateway cryptographic signature with HTTP 403 Forbidden.

Criteria and weights

Alternatives rejected

Contracts and Invariants

Gateway Responsibilities and Domain Separation Invariant [GW-INV-01]
  The API Gateway is restricted to transport-level mediation: TLS termination, client certificate
  validation, token signature verification, rate limiting, request ID injection, and protocol translation.
  Embedding business domain rules, database queries, resource-level authorization, or response
  assembly inside the gateway is strictly prohibited.

Sub-Five-Millisecond Routing Overhead Invariant [GW-INV-02]
  The cumulative latency overhead introduced by the API Gateway (TLS termination, JWT validation,
  rate limit lookup, header sanitization, and routing) must not exceed 4.5 ms at the 99th percentile.

Strict Header Sanitization & Anti-Spoofing Invariant [GW-INV-03]
  The gateway must strip all incoming caller-supplied identity headers (`X-Authenticated-Subject`,
  `X-User-Roles`, `X-Tenant-ID`, `X-Forwarded-For`) before routing to upstreams. The gateway overwrites
  these with a tamper-evident, cryptographically signed `X-Verified-Caller-Context` header.

Multi-Tier Rate Limiting and Fairness Invariant [GW-INV-04]
  Rate limits are enforced strictly per consumer identity and route tier. A single consumer's traffic
  surge must never result in HTTP 429 or HTTP 503 errors for adjacent compliant consumers.
  - Partner Tier: 600 rpm per client ID, burst 2x for 10s -> HTTP 429 + Retry-After.
  - Internal Services: 6,000 rpm per client ID, burst 2x for 10s -> HTTP 429 + Retry-After.
  - Anonymous/Public: 60 rpm per source IP -> HTTP 429.

Upstream Failure Containment and Retry Suppression Invariant [GW-INV-05]
  The gateway must never perform automated retries for non-idempotent HTTP methods (POST, PATCH, PUT).
  When an upstream service times out or returns HTTP 5xx, the gateway immediately returns the mapped
  error (HTTP 503/504) with a Retry-After header. Upstream failure must not cause gateway thread exhaustion.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against API gateway architecture standards:

• Security Rigor: PASS. Centralized mTLS 1.3 and cryptographic JWT validation prevent repeat of SEC-4890.
• Fairness & Quotas: PASS. Multi-tier token-bucket rate limiting prevents noisy-neighbor starvation (INC-5102).
• Latency Discipline: PASS. Envoy proxy C++ data plane ensures sub-4.5ms gateway overhead.
• Boundary Discipline: PASS. Resource authorization and domain business logic strictly reside in backend services.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-GW-01: David O'Reilly to determine whether Redis Sentinel or AWS ElastiCache Cluster Mode is mandated for distributed rate limiting persistence under 32,000 TPS (Owner: David O'Reilly).

Next steps

1. Ingress Platform squad provisions Envoy Gateway controllers on production AWS EKS clusters via Terraform.
2. Security team configures Open Banking QWAC certificate validation and JWKS caching filters in gateway pipelines.
3. Conduct staging resilience drill firing 40,000 requests/min from a synthetic misbehaving partner to verify 100% isolation of adjacent partner traffic.

---

skill: gateway-architect

Open Banking API Gateway Platform — Fitness Self-Check [GW-FIT-001]

Summary

This fitness self-check evaluates the API gateway platform architecture against three critical red-capable domain failure probes: shared mutable ownership, leaky abstraction, and implicit coupling. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Transient latency jitter (up to 2.0 ms) during Redis cluster node failover under peak traffic surges. Accepted by Elena Rostova with local in-memory token-bucket fallback.
• Client clock skew exceeding 300 seconds causing legitimate partner JWT rejections. Accepted by David O'Reilly with strict clock synchronization requirements in partner onboarding documentation.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Architecture Guild incorporates gateway fitness probes FIT-1, FIT-2, and FIT-3 into the master CI deployment pipeline.
2. Platform team configures Prometheus alerts monitoring p99 gateway processing overhead and HTTP 429 rejection ratios.
3. Conduct quarterly security drill verifying automated token revocation propagation across gateway pods within 60 seconds.