# abdulabdullah/go-guard architecture

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

- Interactive diagram: https://gitdiagram.com/abdulabdullah/go-guard
- Repository: https://github.com/abdulabdullah/go-guard

## Overview

Go-Guard is an HTTP API gateway: it loads and validates configuration, assembles request middleware and route handlers, then proxies matching requests to configured upstreams. The README documents route matching, prefix handling, method restrictions, JWT authentication, token-bucket limiting, CORS, request IDs, recovery, logging, and Prometheus metrics. Source excerpts confirm the server assembly, proxy routing, limiter, and several middleware behaviors; some route-handler wiring is only partially sampled, so uncertain internal sequencing is omitted.

Main entry points: [`cmd/server/main.go`](https://github.com/abdulabdullah/go-guard/blob/main/cmd/server/main.go) (HTTP server), [`pkg/middleware/metrics.go`](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/metrics.go) (Prometheus metrics), [`pkg/proxy/proxy.go`](https://github.com/abdulabdullah/go-guard/blob/main/pkg/proxy/proxy.go) (Route handler), [`pkg/middleware/ratelimit.go`](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/ratelimit.go) (Rate-limit middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Gateway runtime"]
  node_server["HTTP server<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_health["Health probes<br/>[main.go]"]
end

subgraph group_routing["Routing and proxy"]
  node_router["Route dispatcher<br/>[proxy.go]"]
  node_routehandler["Route handler<br/>[proxy.go]"]
end

subgraph group_controls["Request controls"]
  node_ratemw["Rate-limit middleware<br/>[ratelimit.go]"]
  node_limiter["Token-bucket limiter<br/>[limiter.go]"]
  node_jwt["JWT authentication<br/>[jwt.go]"]
  node_cors["CORS middleware<br/>[cors.go]"]
  node_requestid["Request ID<br/>[request_id.go]"]
  node_recovery["Panic recovery<br/>[recovery.go]"]
end

subgraph group_observability["Observability"]
  node_logger["Structured logger<br/>[logger.go]"]
  node_metricsmw["Metrics middleware<br/>[metrics.go]"]
  node_metrics[("Prometheus metrics<br/>[metrics.go]")]
end

node_client(("API client"))
node_upstream["Upstream services"]
node_scraper(("Metrics scraper"))
node_logoutput["Log output"]

node_client -->|"sends requests"| node_server
node_server -->|"loads config"| node_config
node_server -->|"initializes router"| node_router
node_server -->|"registers probes"| node_health
node_server -->|"wraps handler"| node_ratemw
node_server -->|"wraps handler"| node_metricsmw
node_server -->|"wraps handler"| node_logger
node_server -->|"wraps handler"| node_cors
node_server -->|"wraps handler"| node_requestid
node_server -->|"wraps handler"| node_recovery
node_server -->|"creates limiter"| node_limiter
node_server -->|"creates metrics"| node_metrics
node_router -->|"dispatches match"| node_routehandler
node_routehandler -->|"proxies request"| node_upstream
node_routehandler -.->|"applies auth"| node_jwt
node_routehandler -.->|"uses route limiter"| node_limiter
node_ratemw -->|"checks allowance"| node_limiter
node_ratemw -->|"records blocks"| node_metrics
node_jwt -->|"records denials"| node_metrics
node_recovery -->|"records panics"| node_metrics
node_metricsmw -->|"records requests"| node_metrics
node_routehandler -->|"records upstream time"| node_metrics
node_scraper -->|"scrapes endpoint"| node_metrics
node_logger -->|"writes logs"| node_logoutput
node_health -->|"returns status"| node_client

click node_server "https://github.com/abdulabdullah/go-guard/blob/main/cmd/server/main.go"
click node_config "https://github.com/abdulabdullah/go-guard/blob/main/config/config.go"
click node_health "https://github.com/abdulabdullah/go-guard/blob/main/cmd/server/main.go"
click node_router "https://github.com/abdulabdullah/go-guard/blob/main/pkg/proxy/proxy.go"
click node_routehandler "https://github.com/abdulabdullah/go-guard/blob/main/pkg/proxy/proxy.go"
click node_ratemw "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/ratelimit.go"
click node_limiter "https://github.com/abdulabdullah/go-guard/blob/main/pkg/limiter/limiter.go"
click node_jwt "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/jwt.go"
click node_cors "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/cors.go"
click node_requestid "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/request_id.go"
click node_recovery "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/recovery.go"
click node_logger "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/logger.go"
click node_metricsmw "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/metrics.go"
click node_metrics "https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/metrics.go"

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_server,node_config,node_health,node_client toneBlue
class node_router,node_routehandler toneAmber
class node_ratemw,node_limiter,node_jwt,node_cors,node_requestid,node_recovery toneMint
class node_logger,node_metricsmw,node_metrics toneRose
class node_upstream,node_scraper,node_logoutput toneIndigo
```

## Components

### Gateway runtime

- [HTTP server](https://github.com/abdulabdullah/go-guard/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Configuration](https://github.com/abdulabdullah/go-guard/blob/main/config/config.go): `config/config.go`
- [Health probes](https://github.com/abdulabdullah/go-guard/blob/main/cmd/server/main.go): `cmd/server/main.go`

### Routing and proxy

- [Route dispatcher](https://github.com/abdulabdullah/go-guard/blob/main/pkg/proxy/proxy.go): `pkg/proxy/proxy.go`
- [Route handler](https://github.com/abdulabdullah/go-guard/blob/main/pkg/proxy/proxy.go): `pkg/proxy/proxy.go`

### Request controls

- [Rate-limit middleware](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/ratelimit.go): `pkg/middleware/ratelimit.go`
- [Token-bucket limiter](https://github.com/abdulabdullah/go-guard/blob/main/pkg/limiter/limiter.go): `pkg/limiter/limiter.go`
- [JWT authentication](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/jwt.go): `pkg/middleware/jwt.go`
- [CORS middleware](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/cors.go): `pkg/middleware/cors.go`
- [Request ID](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/request_id.go): `pkg/middleware/request_id.go`
- [Panic recovery](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/recovery.go): `pkg/middleware/recovery.go`

### Observability

- [Structured logger](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/logger.go): `pkg/middleware/logger.go`
- [Metrics middleware](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/metrics.go): `pkg/middleware/metrics.go`
- [Prometheus metrics](https://github.com/abdulabdullah/go-guard/blob/main/pkg/middleware/metrics.go): `pkg/middleware/metrics.go`

### Other components

- **API client**
- **Upstream services**
- **Metrics scraper**
- **Log output**

## Connections

- API client → HTTP server: sends requests
- HTTP server → Configuration: loads config
- HTTP server → Route dispatcher: initializes router
- HTTP server → Health probes: registers probes
- HTTP server → Rate-limit middleware: wraps handler
- HTTP server → Metrics middleware: wraps handler
- HTTP server → Structured logger: wraps handler
- HTTP server → CORS middleware: wraps handler
- HTTP server → Request ID: wraps handler
- HTTP server → Panic recovery: wraps handler
- HTTP server → Token-bucket limiter: creates limiter
- HTTP server → Prometheus metrics: creates metrics
- Route dispatcher → Route handler: dispatches match
- Route handler → Upstream services: proxies request
- Route handler → JWT authentication: applies auth
- Route handler → Token-bucket limiter: uses route limiter
- Rate-limit middleware → Token-bucket limiter: checks allowance
- Rate-limit middleware → Prometheus metrics: records blocks
- JWT authentication → Prometheus metrics: records denials
- Panic recovery → Prometheus metrics: records panics
- Metrics middleware → Prometheus metrics: records requests
- Route handler → Prometheus metrics: records upstream time
- Metrics scraper → Prometheus metrics: scrapes endpoint
- Structured logger → Log output: writes logs
- Health probes → API client: returns status