enhancement: add a gateway load balancer for horizontally scaled APIs

[CoreyLeath-code]

Finding

The local Compose demo exposes a single driver-location-api instance directly on host port 8000. The repository models event-driven domain flows, but the current HTTP entry point has no local Layer-7 load balancer or multi-replica demonstration.

Requested work

Add a production-quality HTTP load-balancing layer at the API gateway boundary while preserving the event-driven architecture.

Scope

• Place NGINX or an equivalent Layer-7 proxy before stateless API replicas; keep Kafka, Redis Streams, RabbitMQ, and workers as asynchronous infrastructure rather than proxy targets.
• Update Compose so only the load balancer is host-exposed and docker compose up --scale driver-location-api=3 (or the compatible service name) can demonstrate horizontal API scaling.
• Add/verify lightweight health and readiness endpoints before making an instance eligible for traffic.
• Ensure shared state is externalized or documented; requests must not rely on process-local state across replicas.
• Propagate forwarded headers and request IDs without bypassing authentication or rate limiting.
• Add automated NGINX config validation, proxy routing, multiple-backend observation, unhealthy-replica resilience, and Compose/CI validation.
• Add reproducible load-test and fault-demonstration commands, with results explicitly pending until measured.
• Integrate existing Kubernetes Service/HPA manifests only where they are real and non-conflicting; document local proxy versus Kubernetes Service/Ingress behavior.

Acceptance criteria

• Three healthy API replicas can serve through one host-exposed endpoint.
• Repeated proxy requests demonstrably reach multiple replicas in an automated test.
• Taking one replica down does not take down healthy API traffic.
• The event-bus adapter topology remains unchanged.
• Existing tests and CI remain enforced; no test is skipped to accept the change.
• README documents architecture, balancing choice, readiness, fault behavior, observability, and test commands.
• No benchmark figures or production claims are invented.

Evidence

• docker-compose.yml contains a single driver-location-api service and maps 8000:8000.
• The existing Compose health check targets /driver-location/health.
• The README identifies Docker/Kubernetes assets and broker-backed asynchronous components, but no local proxy/replica layer.
• No open issue mentioning NGINX, load balancing, or horizontal scaling exists as of 2026-08-12.

Dependencies / decisions

The implementation must preserve the API-to-domain-service-to-event-broker model and avoid making a reverse proxy responsible for asynchronous delivery.