Network Routing

This document describes the journey of an HTTP request from a client through Arda’s network stack to a Component pod running in the Kubernetes cluster.

Request Path Overview

The path from client to Component involves six layers:

1. DNS Resolution — GoDaddy → Platform Root Route 53 → Infrastructure Route 53 → API Gateway IP
2. API Gateway — JWT authorization (Cognito), route matching, VPC Link
3. NLB (Network Load Balancer) — TCP-level load balancing to nginx pods
4. nginx Ingress — HTTP routing, path-based routing to Component services
5. Component Service — Kubernetes service routing to Component pods

Dynamic Configuration

Two controllers maintain the routing table without restarts:

Load Balancer Controller (AWS)

When nginx pods change (scale up/down, rolling update):

1. Controller reads TargetGroupBinding configuration from nginx
2. Reads health status and IP addresses of nginx pods
3. Updates NLB target groups with the current set of healthy nginx pod IPs

nginx Admission Controller

When a Component’s Ingress rules change:

1. Reads the new rules (port, path, host matchers) from the Component’s Ingress resource
2. Updates nginx configuration with the new routing rules
3. Reloads nginx pods with the updated configuration — no service interruption

Request Flow (Query Time)

Client
  --> DNS: *.io.arda.cards? --> GoDaddy (NS redirect to arda-root Route 53)
  --> DNS: *.<infra>.io.arda.cards? --> arda-root Route 53 (NS redirect to <infra> Route 53)
  --> DNS: <purpose>.<infra>.io.arda.cards? --> <infra> Route 53 (A record: API Gateway IP)

  --> HTTPS: <purpose>.<infra>.io.arda.cards/<route>
        --> API Gateway: route match /<route>?
        --> VPC Link (TCP:80)
              --> NLB
                    --> Listener (TCP:80) --> target group
                    --> Target Group --> nginx pod IP

              --> nginx pod (TCP:80)
                    --> Component pod (http://<ip>:80/<route>)
                    <-- response
              <-- response
        <-- response
  <-- response

Infrastructure Components

Component	Technology	Responsibility
DNS	Route 53 (3 levels) + GoDaddy	Name resolution
API Gateway	AWS HTTP API Gateway	JWT auth, route matching, VPC Link
VPC Link	AWS VPC Link	Secure tunnel from API Gateway to VPC
NLB	AWS Network Load Balancer	TCP-level load balancing
nginx	Kubernetes nginx Ingress Controller	HTTP path routing within the cluster
Component	Kubernetes Deployment + Service	Business logic

Security Considerations

• All external traffic enters through the API Gateway, which enforces OAuth 2.0 JWT validation via Cognito before forwarding to the VPC Link
• The NLB is accessible only within the VPC; no direct public access
• nginx pods operate on port 80 (HTTP) inside the VPC; TLS termination occurs at the API Gateway
• For mTLS configuration between Amplify BFF and API Gateway, see mTLS