docs(gateway): add gateway-ready conventions, service communication docs, and reference compose [AYG-74]

amostt · Aygentic · amostt · commit 528eb3f70b91 · 2026-03-01T03:45:31.000+08:00
Add Gateway-Ready Conventions and Service-to-Service Communication
sections to README covering service discoverability endpoints,
routing conventions, cross-cutting concerns table, managed platform
guidance, {SERVICE_NAME}_URL env var pattern, shared HTTP client
usage with correlation ID propagation, and ServiceError pattern for
unconfigured services.

Create reference compose.gateway.yml with Traefik 3.6, TLS/ACME,
HTTP-to-HTTPS redirect, rate limiting middleware (commented), and
example service labels — clearly marked as reference-only for
self-hosted deployments.

Fixes AYG-74
Related to AYG-64

🤖 Generated by Aygentic

Co-Authored-By: Aygentic &lt;noreply@aygentic.com&gt;
diff --git a/README.md b/README.md
@@ -330,6 +330,119 @@ Run `alembic upgrade head` for Alembic migrations and `supabase db push` for Sup
 
 ---
 
+## Gateway-Ready Conventions
+
+This template is **gateway-ready, not gateway-inclusive** — every service follows conventions that make it routable through any API gateway (Traefik, Kong, AWS ALB, Alibaba Cloud API Gateway) without shipping one.
+
+### Service Discoverability
+
+Every service exposes standard endpoints that gateways use for health checking and service registration:
+
+| Endpoint | Purpose | Auth Required |
+|----------|---------|---------------|
+| `GET /version` | Returns `service_name`, `version`, `commit`, `build_time`, `environment` | No |
+| `GET /healthz` | Liveness probe — is the process running? | No |
+| `GET /readyz` | Readiness probe — can the service handle traffic? | No |
+
+### Routing Conventions
+
+All API routes use the `/api/v1` prefix (configured via `API_V1_STR` in `backend/app/core/config.py`). The service name belongs in the deployment URL, not the API path:
+
+```
+✓  https://user-service.example.com/api/v1/users
+✗  https://gateway.example.com/user-service/api/v1/users
+```
+
+Path-based gateway routing is possible but not the default convention.
+
+### Cross-Cutting Concerns
+
+| Concern | Template Responsibility | Gateway Responsibility |
+|---------|------------------------|------------------------|
+| Authentication | Clerk JWT verification per-service | Optional JWT pre-validation |
+| Rate limiting | None (defer to gateway) | Per-client rate limits |
+| API key management | None (Clerk handles user auth) | Machine-to-machine API keys |
+| CORS | Per-service `BACKEND_CORS_ORIGINS` | Aggregate CORS if fronting multiple services |
+| TLS termination | None (platform provides) | Certificate management |
+| Request routing | Responds to all requests on its port | Routes by domain/path to services |
+| Load balancing | None (platform provides) | Distributes across service instances |
+
+### Managed Platforms
+
+Teams deploying to managed platforms (Railway, Cloud Run, Fly.io, Alibaba Cloud) use the platform's built-in routing and load balancing — Traefik is not needed. The gateway-ready conventions (health endpoints, `/api/v1` prefix, structured error responses) still apply, as platforms rely on these for health checking and service discovery.
+
+For self-hosted deployments, see [`compose.gateway.yml`](compose.gateway.yml) for a reference Traefik 3.6 configuration.
+
+---
+
+## Service-to-Service Communication
+
+Service communication uses a deliberately simple pattern: environment variables pointing to URLs. No service registry, no DNS-based discovery, no service mesh. This works because container platforms (Railway, Cloud Run, Fly.io) provide stable internal URLs for services within the same project.
+
+### Service Discovery
+
+Each service dependency is configured via an environment variable following the `{SERVICE_NAME}_URL` pattern:
+
+```env
+# .env
+USER_SERVICE_URL=https://user-service.railway.internal
+BILLING_SERVICE_URL=https://billing-service.railway.internal
+```
+
+Add one `{SERVICE_NAME}_URL` variable per dependency. When a URL is not configured, the calling code should fail fast with a clear error (see [Error Handling](#error-handling-for-unconfigured-services) below).
+
+### Shared HTTP Client
+
+All inter-service calls use the shared `HttpClient` (`backend/app/core/http_client.py`), which automatically:
+
+- Propagates `X-Correlation-ID` and `X-Request-ID` headers
+- Applies configurable timeout, retry (with exponential backoff), and circuit breaker policies
+- Logs retries and exhausted retries with target URL and attempt count
+
+```python
+from app.api.deps import HttpClientDep
+from app.core.config import settings
+
+async def get_user(http: HttpClientDep, user_id: str):
+    response = await http.get(f"{settings.USER_SERVICE_URL}/api/v1/users/{user_id}")
+    response.raise_for_status()
+    return response.json()
+```
+
+### Correlation ID Propagation
+
+Every incoming request is assigned a `request_id` (UUID v4) by the request middleware (`backend/app/core/middleware.py`). The middleware also reads the `X-Correlation-ID` header from the incoming request:
+
+- **If `X-Correlation-ID` is present** and matches the expected format (alphanumeric, hyphens, underscores, dots; max 128 characters): it is used as the `correlation_id`
+- **If `X-Correlation-ID` is absent or invalid**: the `request_id` is used as the `correlation_id`
+
+Both values are bound to structlog context variables and automatically propagated to outgoing HTTP calls via the shared `HttpClient`. This creates a trace that spans multiple services — all logs for a single user action share the same `correlation_id`.
+
+### Error Handling for Unconfigured Services
+
+When a service URL is not configured, fail immediately with a descriptive `ServiceError` rather than making a request to an empty URL:
+
+```python
+from app.api.deps import HttpClientDep
+from app.core.config import settings
+from app.core.errors import ServiceError
+
+async def get_user(http: HttpClientDep, user_id: str):
+    if not settings.USER_SERVICE_URL:
+        raise ServiceError(
+            status_code=503,
+            message="User service not configured",
+            code="SERVICE_NOT_CONFIGURED",
+        )
+    response = await http.get(f"{settings.USER_SERVICE_URL}/api/v1/users/{user_id}")
+    response.raise_for_status()
+    return response.json()
+```
+
+This returns a structured `503 SERVICE_UNAVAILABLE` response with the `SERVICE_NOT_CONFIGURED` error code, making it clear that the issue is a missing configuration — not a downstream service failure.
+
+---
+
 ## Environment Variables
 
 Configuration is loaded from `.env` (development) or passed as container environment variables (staging/production). Copy `.env.example` to `.env` to get started.
diff --git a/compose.gateway.yml b/compose.gateway.yml
@@ -0,0 +1,139 @@
+# =============================================================================
+# REFERENCE ONLY — NOT PART OF THE TEMPLATE
+# =============================================================================
+#
+# This file documents a self-hosted Traefik 3.6 gateway configuration for teams
+# that manage their own reverse proxy instead of using a managed gateway.
+#
+# Teams deploying to managed platforms (Railway, Cloud Run, Fly.io) should use
+# the platform's built-in routing and load balancing instead of running a
+# self-hosted Traefik instance.
+#
+# This is for teams wanting a self-hosted Traefik gateway on a VPS or
+# bare-metal server with automatic TLS via Let's Encrypt.
+#
+# HOW TO USE:
+#   1. Create the external network: docker network create traefik-public
+#   2. Set ACME_EMAIL and DOMAIN in your .env (or export them)
+#   3. Start the gateway:           docker compose -f compose.gateway.yml up -d
+#   4. Add the example service labels (see bottom of this file) to your own
+#      compose.yml services, then bring them up on the same traefik-public network
+#
+# THIS FILE IS NEVER USED BY THE TEMPLATE DIRECTLY.
+# It is documentation — a reference for self-hosted gateway deployments.
+# =============================================================================
+
+services:
+
+  traefik:
+    image: traefik:3.6
+    restart: always
+    ports:
+      # HTTP — receives Let's Encrypt TLS challenges and redirects to HTTPS
+      - "80:80"
+      # HTTPS — TLS-terminated traffic
+      - "443:443"
+    volumes:
+      # Docker socket (read-only) — Traefik reads labels from running containers
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      # Persistent volume for Let's Encrypt certificates
+      - traefik-certificates:/certificates
+    command:
+      # --- Docker provider ---
+      # Enable Docker label-based service discovery
+      - --providers.docker
+      # Only route containers that explicitly set traefik.enable=true
+      - --providers.docker.exposedbydefault=false
+      # Scope discovery to services tagged with traefik.constraint-label=traefik-public
+      - --providers.docker.constraints=Label(`traefik.constraint-label`, `traefik-public`)
+
+      # --- Entrypoints ---
+      - --entrypoints.http.address=:80
+      - --entrypoints.https.address=:443
+
+      # --- HTTP → HTTPS redirect (global, via entrypoint configuration) ---
+      - --entrypoints.http.http.redirections.entryPoint.to=https
+      - --entrypoints.http.http.redirections.entryPoint.scheme=https
+      - --entrypoints.http.http.redirections.entryPoint.permanent=true
+
+      # --- TLS / Let's Encrypt (ACME) ---
+      # TLS-ALPN-01 challenge — requires port 443 to be publicly reachable.
+      # If port 443 is firewalled or shared, switch to the HTTP-01 challenge:
+      #   - --certificatesresolvers.le.acme.httpchallenge=true
+      #   - --certificatesresolvers.le.acme.httpchallenge.entrypoint=http
+      - --certificatesresolvers.le.acme.tlschallenge=true
+      # Your email for Let's Encrypt renewal notifications
+      - --certificatesresolvers.le.acme.email=${ACME_EMAIL?Variable ACME_EMAIL not set}
+      # Store certificates in the mounted volume
+      - --certificatesresolvers.le.acme.storage=/certificates/acme.json
+
+      # --- Observability ---
+      - --accesslog
+      - --log
+    labels:
+      - traefik.enable=true
+      - traefik.docker.network=traefik-public
+
+      # https-redirect middleware — named alias so service routers can reference it
+      # The global redirect is enforced by the entrypoint command args above;
+      # this label makes the middleware available by name for per-router use.
+      - traefik.http.middlewares.https-redirect.redirectscheme.scheme=https
+      - traefik.http.middlewares.https-redirect.redirectscheme.permanent=true
+
+      # --- Rate limiting middleware (reference — not active by default) ---
+      # To enable rate limiting on a service, add these labels to that service
+      # and reference the middleware name in its router labels:
+      #   traefik.http.middlewares.rate-limit.ratelimit.average=100
+      #   traefik.http.middlewares.rate-limit.ratelimit.burst=50
+      #   traefik.http.middlewares.rate-limit.ratelimit.period=1m
+      # Then apply it to a router:
+      #   traefik.http.routers.<name>-https.middlewares=rate-limit
+    networks:
+      - traefik-public
+
+# =============================================================================
+# EXAMPLE BACKEND SERVICE (commented out — for reference only)
+# =============================================================================
+# Copy these labels into your compose.yml backend service.
+# Replace STACK_NAME, DOMAIN, the image reference, and the container port
+# to match your workload. The network and constraint-label entries are
+# required for Traefik to discover and route to your service.
+#
+#  backend:
+#    image: your-org/your-backend:latest
+#    restart: always
+#    networks:
+#      - traefik-public
+#      - default
+#    labels:
+#      - traefik.enable=true
+#      - traefik.docker.network=traefik-public
+#      - traefik.constraint-label=traefik-public
+#
+#      # Container port the backend listens on
+#      - traefik.http.services.${STACK_NAME:-app}-backend.loadbalancer.server.port=8000
+#
+#      # HTTP router — redirects to HTTPS via the https-redirect middleware
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-http.rule=Host(`api.${DOMAIN:-localhost}`)
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-http.entrypoints=http
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-http.middlewares=https-redirect
+#
+#      # HTTPS router — serves TLS-terminated traffic with Let's Encrypt cert
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-https.rule=Host(`api.${DOMAIN:-localhost}`)
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-https.entrypoints=https
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-https.tls=true
+#      - traefik.http.routers.${STACK_NAME:-app}-backend-https.tls.certresolver=le
+#
+#      # Optionally apply rate limiting (requires rate-limit middleware above):
+#      # - traefik.http.routers.${STACK_NAME:-app}-backend-https.middlewares=rate-limit
+# =============================================================================
+
+networks:
+  # Shared external network — must be created before running this file:
+  #   docker network create traefik-public
+  traefik-public:
+    external: true
+
+volumes:
+  # Stores Let's Encrypt certificates across container restarts
+  traefik-certificates:
