Architecture
The gateway is an edge proxy, not a service. There are no state machines (no domain entities) — the runtime scenarios below describe request-routing paths instead.
1. System Context (C4 L1)
2. Container View (C4 L2)
Two distinct proxy topologies share the same routing intent: Traefik for Docker/prod, local Nginx for native dev.
| Topology | Proxy | Discovery | TLS | Used when |
|---|---|---|---|---|
| Production / Docker | Traefik v3.6 | Docker labels (auto) | Edge Nginx | Containerized deploy |
| Native development | local Nginx | Static nginx.conf route table | None | Services run on host 127.0.0.1:31xx |
3. Component View (C4 L3) — Routing Decision
| Layer | Traefik source | Local Nginx source |
|---|---|---|
| Entrypoint | traefik.yml entryPoints.web/.traefik | listen 80 default_server |
| Routers | Docker labels (auto-discovered) | location /v1/api/<svc>/ blocks |
| Middlewares | middlewares.yml (file provider) | shared proxy_set_header block |
| Upstreams | Docker network IP | upstream <svc>_upstream { 127.0.0.1:31xx } |
| Catch-all | portal router priority 1 | location / → 404 JSON |
4. State Machines Index
N/A — the gateway manages no stateful entities. The only stateful runtime construct is the Traefik circuit breaker, whose state machine is documented in Resilience.
5. Runtime Scenarios
5.1 Standard REST request (production, Traefik)
5.2 Native-dev request (local Nginx)
5.3 Signal WebSocket upgrade
5.4 Portal health discovery
6. Crosscutting Concerns
| Concern | How the gateway handles it |
|---|---|
| AuthN/AuthZ | None at gateway — JWT verified by each service (identity is issuer). Gateway only basic-auths the Traefik dashboard + portal. |
| TLS | Terminated at edge Nginx, not Traefik (no HTTPS entrypoint in traefik.yml). |
| Rate limiting | Traefik rate-limit (200/s) / rate-limit-auth (30/min), per-IP via ipStrategy.depth=1. |
| Resilience | Traefik circuit-breaker + active health checks. See Resilience. |
| Logging | Traefik JSON access logs; Authorization/Cookie dropped. |
| Metrics | Prometheus on :8080. See Observability. |
| IDs / Soft-delete / i18n | N/A — no datastore. |