loadbalancer/docs/architecture.md

Architecture

This project runs Traefik Proxy as a Dockerized TCP load balancer.

Components

• compose.yaml: defines the Traefik container, published port, host-based configuration volume, container hardening, and healthcheck.
• config/traefik.yml: static Traefik configuration for entrypoints, file provider, ping, and logging.
• config/dynamic/tcp-services.yml: dynamic TCP router and backend load-balancer service.

Data flow

1. A client opens a TLS connection to the Docker host on 443/tcp.
2. Docker forwards the connection to Traefik on container port 8443/tcp.
3. Traefik matches the TCP router using HostSNI(*).
4. Traefik forwards the unchanged TCP stream to one configured backend IP address and port.
5. The selected backend terminates TLS and presents its own SSL certificate.

Persistence

Traefik configuration is stored in the host ./config directory and mounted read-only at /etc/traefik.

No certificates, private keys, application data, or Docker socket are mounted into the Traefik container.

Deployment topology

Traefik runs as one Docker container on the load-balancer host. Backends are external to this Compose stack and must be reachable from the container through their configured IP addresses and ports. The Compose service defines host.docker.internal through Docker's host-gateway feature for backends that listen on the Docker host itself.

See docs/adr/0001-traefik-tcp-tls-passthrough.md for the design decision.