# pietroagazzi/gater architecture

> Architecture diagram of the GitHub repository pietroagazzi/gater, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pietroagazzi/gater
- Repository: https://github.com/pietroagazzi/gater

## Overview

1. **What this repository is**
   - `gater` is a Go-based API gateway, not a business service. Its job is to accept inbound HTTP requests, match them to configured routes, discover upstream instances, apply resilience rules, and proxy the request onward.

2. **Process entrypoint and composition root**
   - The executable lives in `cmd/gater/main.go`.
   - The `internal/app` package is the composition layer: it assembles configuration, discovery, load balancing, circuit breaking, and the HTTP gateway into one running process.
   - This is the place where the application is wired together before the server starts.

3. **Configuration boundary**
   - Runtime behavior is driven by YAML files in `config/`:
     - `config/routes.yml` defines path prefixes, allowed methods, target service names, and route priority.
     - `config/services.yml` defines per-service resilience settings, especially circuit breaker recovery timeouts.
   - The `internal/config` package parses and validates these files, keeping routing policy and service policy outside the code.

4. **Request routing subsystem**
   - `internal/gateway` is the core HTTP gateway layer.
   - It is responsible for taking an inbound request, selecting the correct route based on path/method/priority, and turning that into a call to the target service.
   - This package is the main boundary between external clients and internal service discovery / upstream transport.

5. **Service discovery subsystem**
   - `internal/discovery` abstracts where service instances come from.
   - There are at least two providers:
     - `consul.go` for dynamic discovery from Consul
     - `static.go` for fixed, local, or test-friendly discovery
   - `factory.go` selects/constructs the provider, which makes discovery pluggable rather than hard-coded.

6. **Load balancing**
   - `internal/loadbalancer/roundrobin.go` chooses among discovered instances.
   - The repository uses deterministic round-robin selection, which aligns with the project’s “deterministic” design goal.
   - This sits between discovery and transport: discovery yields instances, load balancing picks one instance for a request.

7. **Resilience layer**
   - `internal/circuitbreaker` wraps upstream calls with a circuit breaker policy.
   - The README and service config indicate per-service recovery timeouts, so resilience is configured per backend rather than globally.
   - This layer is intended to fail fast when a service is unhealthy instead of retrying indefinitely or blocking requests.

8. **Service model**
   - `internal/service` defines the domain objects used across routing, discovery, and resilience, such as service definitions and instances.
   - These types act as the shared contract between the config parser, discovery provider, and gateway runtime.

9. **Upstream call pipeline**
   - The README describes the architecture as composable `http.RoundTripper` decorators.
   - In practice, the outbound request path is layered: validation/guardrails, circuit breaker, then actual transport to the chosen upstream instance.
   - This means the gateway is designed as a proxy pipeline rather than a monolithic handler.

10. **External dependency on Consul**
   - Consul is the only major external infrastructure component visible in the repo.
   - In local deployment, `docker/consul/` plus `docker-compose.yml` provide a Consul instance and its bootstrap config.
   - In architecture terms, Consul is the dynamic source of truth for service instances when the Consul discovery provider is used.

11. **Local and containerized runtime**
   - The repository is built for container-first operation: `Dockerfile`, `Dockerfile.dev`, and `docker-compose*.yml` support production, development, and test flows.
   - Air hot reload is configured via `.air.toml`, indicating a fast local development loop for the Go process.

12. **Health and operational surface**
   - The README shows a `/health` endpoint, implying the gateway exposes at least a basic liveness/readiness surface.
   - GitHub Actions cover CI, security scanning, and Docker publishing, so the repo includes production-oriented build and release automation.

13. **How the main data flows connect**
   - Startup flow: YAML config → config validation → discovery provider initialization → route/service policy assembly → gateway construction → HTTP server.
   - Request flow: client request → route match → service lookup → instance selection → circuit breaker check → proxied upstream call → response back to client.

14. **Architecture summary for a diagram**
   - The important boxes are: HTTP entrypoint, route/config loader, discovery provider, load balancer, circuit breaker, and upstream services.
   - The key arrows are: configuration into runtime, request path through gateway logic, and service instance resolution through Consul or static definitions.

Main entry points: [`internal/app/app.go`](https://github.com/pietroagazzi/gater/blob/develop/internal/app/app.go) (App wire-up), [`internal/gateway/gateway.go`](https://github.com/pietroagazzi/gater/blob/develop/internal/gateway/gateway.go) (Gateway), [`internal/discovery/factory.go`](https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/factory.go) (Discovery factory), [`internal/service/instance.go`](https://github.com/pietroagazzi/gater/blob/develop/internal/service/instance.go) (Instance model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoint["Entrypoint"]
  node_cmd_gater_main["Main<br/>entrypoint<br/>[main.go]"]
  node_internal_app_app["App wire-up<br/>composition<br/>[app.go]"]
end

subgraph group_config["Config"]
  node_internal_config_config["Config parser<br/>[config.go]"]
  node_config_routes_yml["Routes<br/>route policy<br/>[routes.yml]"]
  node_config_services_yml["Services<br/>service policy<br/>[services.yml]"]
end

subgraph group_runtime["Gateway runtime"]
  node_internal_gateway_gateway["Gateway<br/>http proxy<br/>[gateway.go]"]
  node_internal_service_service["Service model<br/>domain types<br/>[service.go]"]
  node_internal_service_instance["Instance model<br/>domain types<br/>[instance.go]"]
  node_internal_loadbalancer_roundrobin(("Round robin<br/>balancer<br/>[roundrobin.go]"))
  node_internal_circuitbreaker_circuit_breaker{{"Circuit breaker<br/>resilience<br/>[circuit_breaker.go]"}}
end

subgraph group_discovery["Discovery"]
  node_internal_discovery_factory["Discovery factory<br/>provider select<br/>[factory.go]"]
  node_internal_discovery_consul["Consul provider<br/>discovery backend<br/>[consul.go]"]
  node_internal_discovery_static["Static provider<br/>discovery backend<br/>[static.go]"]
end

subgraph group_ops["Operations"]
  node_docker_compose_yml["Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_docker_consul_config_local_json["Consul bootstrap<br/>infra config<br/>[local.json]"]
  node_dockerfile["Dockerfile<br/>container image"]
  node_dockerfile_dev["Dev image<br/>container image<br/>[Dockerfile.dev]"]
end

node_cmd_gater_main -->|"starts"| node_internal_app_app
node_internal_app_app -->|"loads"| node_internal_config_config
node_internal_app_app -->|"wires"| node_internal_discovery_factory
node_internal_app_app -->|"builds"| node_internal_gateway_gateway
node_internal_app_app -->|"adds"| node_internal_circuitbreaker_circuit_breaker
node_internal_config_config -->|"parses"| node_config_routes_yml
node_internal_config_config -->|"parses"| node_config_services_yml
node_internal_gateway_gateway -->|"uses"| node_internal_service_service
node_internal_gateway_gateway -->|"resolves"| node_internal_discovery_factory
node_internal_gateway_gateway -->|"selects"| node_internal_loadbalancer_roundrobin
node_internal_gateway_gateway -->|"guards"| node_internal_circuitbreaker_circuit_breaker
node_internal_discovery_factory -->|"selects"| node_internal_discovery_consul
node_internal_discovery_factory -->|"selects"| node_internal_discovery_static
node_internal_discovery_consul -->|"returns"| node_internal_service_instance
node_internal_discovery_static -->|"returns"| node_internal_service_instance
node_internal_loadbalancer_roundrobin -->|"chooses"| node_internal_service_instance
node_internal_circuitbreaker_circuit_breaker -->|"protects"| node_internal_service_instance
node_docker_compose_yml -->|"boots"| node_docker_consul_config_local_json
node_docker_compose_yml -->|"builds"| node_dockerfile
node_docker_compose_yml -->|"builds"| node_dockerfile_dev

click node_cmd_gater_main "https://github.com/pietroagazzi/gater/blob/develop/cmd/gater/main.go"
click node_internal_app_app "https://github.com/pietroagazzi/gater/blob/develop/internal/app/app.go"
click node_internal_config_config "https://github.com/pietroagazzi/gater/blob/develop/internal/config/config.go"
click node_config_routes_yml "https://github.com/pietroagazzi/gater/blob/develop/config/routes.yml"
click node_config_services_yml "https://github.com/pietroagazzi/gater/blob/develop/config/services.yml"
click node_internal_gateway_gateway "https://github.com/pietroagazzi/gater/blob/develop/internal/gateway/gateway.go"
click node_internal_service_service "https://github.com/pietroagazzi/gater/blob/develop/internal/service/service.go"
click node_internal_service_instance "https://github.com/pietroagazzi/gater/blob/develop/internal/service/instance.go"
click node_internal_discovery_factory "https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/factory.go"
click node_internal_discovery_consul "https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/consul.go"
click node_internal_discovery_static "https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/static.go"
click node_internal_loadbalancer_roundrobin "https://github.com/pietroagazzi/gater/blob/develop/internal/loadbalancer/roundrobin.go"
click node_internal_circuitbreaker_circuit_breaker "https://github.com/pietroagazzi/gater/blob/develop/internal/circuitbreaker/circuit_breaker.go"
click node_docker_compose_yml "https://github.com/pietroagazzi/gater/blob/develop/docker-compose.yml"
click node_docker_consul_config_local_json "https://github.com/pietroagazzi/gater/blob/develop/docker/consul/config/local.json"
click node_dockerfile "https://github.com/pietroagazzi/gater/tree/develop/Dockerfile"
click node_dockerfile_dev "https://github.com/pietroagazzi/gater/blob/develop/Dockerfile.dev"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_gater_main,node_internal_app_app toneBlue
class node_internal_config_config,node_config_routes_yml,node_config_services_yml toneAmber
class node_internal_gateway_gateway,node_internal_service_service,node_internal_service_instance,node_internal_loadbalancer_roundrobin,node_internal_circuitbreaker_circuit_breaker toneMint
class node_internal_discovery_factory,node_internal_discovery_consul,node_internal_discovery_static toneRose
class node_docker_compose_yml,node_docker_consul_config_local_json,node_dockerfile,node_dockerfile_dev toneIndigo
```

## Components

### Entrypoint

Process startup and wiring

- [Main](https://github.com/pietroagazzi/gater/blob/develop/cmd/gater/main.go): entrypoint · Executable startup · `cmd/gater/main.go`
- [App wire-up](https://github.com/pietroagazzi/gater/blob/develop/internal/app/app.go): composition · Assembles runtime dependencies · `internal/app/app.go`

### Config

Externalized routing and service policy

- [Config parser](https://github.com/pietroagazzi/gater/blob/develop/internal/config/config.go): config · Loads and validates runtime config · `internal/config/config.go`
- [Routes](https://github.com/pietroagazzi/gater/blob/develop/config/routes.yml): route policy · Path, method, target, priority · `config/routes.yml`
- [Services](https://github.com/pietroagazzi/gater/blob/develop/config/services.yml): service policy · Per-service resilience settings · `config/services.yml`

### Gateway runtime

Request handling and upstream proxy pipeline

- [Gateway](https://github.com/pietroagazzi/gater/blob/develop/internal/gateway/gateway.go): http proxy · Matches routes and forwards requests · `internal/gateway/gateway.go`
- [Service model](https://github.com/pietroagazzi/gater/blob/develop/internal/service/service.go): domain types · Shared service definitions · `internal/service/service.go`
- [Instance model](https://github.com/pietroagazzi/gater/blob/develop/internal/service/instance.go): domain types · Upstream instance representation · `internal/service/instance.go`
- [Round robin](https://github.com/pietroagazzi/gater/blob/develop/internal/loadbalancer/roundrobin.go): balancer · Deterministic instance selection · `internal/loadbalancer/roundrobin.go`
- [Circuit breaker](https://github.com/pietroagazzi/gater/blob/develop/internal/circuitbreaker/circuit_breaker.go): resilience · Fails fast on unhealthy upstreams · `internal/circuitbreaker/circuit_breaker.go`

### Discovery

Pluggable service instance sources

- [Discovery factory](https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/factory.go): provider select · Builds the discovery backend · `internal/discovery/factory.go`
- [Consul provider](https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/consul.go): discovery backend · Loads instances from Consul · `internal/discovery/consul.go`
- [Static provider](https://github.com/pietroagazzi/gater/blob/develop/internal/discovery/static.go): discovery backend · Fixed instance source · `internal/discovery/static.go`

### Operations

Container and local infrastructure

- [Compose](https://github.com/pietroagazzi/gater/blob/develop/docker-compose.yml): local runtime · Containerized gateway and dependencies · `docker-compose.yml`
- [Consul bootstrap](https://github.com/pietroagazzi/gater/blob/develop/docker/consul/config/local.json): infra config · Local Consul bootstrap data · `docker/consul/config/local.json`
- [Dockerfile](https://github.com/pietroagazzi/gater/tree/develop/Dockerfile): container image · Production build image · `Dockerfile`
- [Dev image](https://github.com/pietroagazzi/gater/blob/develop/Dockerfile.dev): container image · Development container image · `Dockerfile.dev`

## Connections

- Main → App wire-up: starts · Entrypoint creates the composed application
- App wire-up → Config parser: loads · Reads and validates runtime configuration
- App wire-up → Discovery factory: wires · Selects a discovery provider
- App wire-up → Gateway: builds · Constructs the HTTP gateway
- App wire-up → Circuit breaker: adds · Installs resilience into upstream calls
- Config parser → Routes: parses · Route definitions come from YAML
- Config parser → Services: parses · Service policies come from YAML
- Gateway → Service model: uses · Routes resolve to service definitions
- Gateway → Discovery factory: resolves · Looks up instance sources through discovery
- Gateway → Round robin: selects · Chooses an upstream instance
- Gateway → Circuit breaker: guards · Wraps upstream traffic with breaker policy
- Discovery factory → Consul provider: selects · Can build the Consul-backed provider
- Discovery factory → Static provider: selects · Can build the static provider
- Consul provider → Instance model: returns · Converts Consul data into instances
- Static provider → Instance model: returns · Exposes fixed instances
- Round robin → Instance model: chooses · Picks one instance for a request
- Circuit breaker → Instance model: protects · Applies per-upstream resilience
- Compose → Consul bootstrap: boots · Local compose brings up Consul bootstrap data
- Compose → Dockerfile: builds · Compose can run the production image
- Compose → Dev image: builds · Compose can run the dev image
