# thejkishore/reverse-proxy-go architecture

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

- Interactive diagram: https://gitdiagram.com/thejkishore/reverse-proxy-go
- Repository: https://github.com/thejkishore/reverse-proxy-go

## Overview

This Go service is a reverse-proxy API gateway. Client requests enter the proxy handler, resolve against dynamically loaded route definitions, pass through a filter pipeline, select an upstream target, and receive the upstream response. The README documents routing, load balancing, security, resilience, transformation, tracing, audit, WebSocket, and administration capabilities. Sampled code confirms request context, upstream forwarding, route administration, and storage behavior; several filter implementations and wiring were not sampled, so those branches reflect documented capabilities without asserting internal call order.

Main entry points: [`internal/filter/filter_chain.go`](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/filter/filter_chain.go) (Filter chain), [`internal/registry/route_registry.go`](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/registry/route_registry.go) (Route registry), [`cmd/gateway/main.go`](https://github.com/thejkishore/reverse-proxy-go/blob/main/cmd/gateway/main.go) (Gateway bootstrap), [`internal/api/admin_handler.go`](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/admin_handler.go) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Gateway API"]
  node_main["Gateway bootstrap<br/>[main.go]"]
  node_proxy_api["Proxy handler<br/>[proxy_handler.go]"]
  node_admin_api["Admin API<br/>[admin_handler.go]"]
  node_health_api["Health endpoints<br/>[health_handler.go]"]
  node_openapi_api["OpenAPI export<br/>[openapi_handler.go]"]
  node_audit_api["Audit endpoints<br/>[audit_handler.go]"]
end

subgraph group_routing["Route Management"]
  node_registry["Route registry<br/>[route_registry.go]"]
  node_loader["Route loader<br/>[route_loader.go]"]
  node_matchers["Route matchers<br/>[route_matcher.go]"]
  node_route_models["Route definitions"]
end

subgraph group_request["Request Pipeline"]
  node_filter_chain["Filter chain<br/>[filter_chain.go]"]
  node_filter_context["Request context<br/>[filter_context.go]"]
  node_security["Security filters<br/>[jwt_auth_filter.go]"]
  node_resilience["Resilience filters"]
  node_cache["Response cache<br/>[cache_filter.go]"]
  node_observability["Tracing and audit<br/>[tracing_filter.go]"]
  node_transform["Header and body transforms"]
end

subgraph group_upstream["Upstream Delivery"]
  node_proxy_filter["Proxy filter<br/>[proxy_filter.go]"]
  node_balancer["Load balancers<br/>[load_balancer.go]"]
  node_upstream_client["Upstream client<br/>[upstream_client.go]"]
  node_websocket["WebSocket relay"]
end

subgraph group_state["Persistence"]
  node_route_store[("Route storage<br/>[route_storage.go]")]
  node_postgres_routes[("PostgreSQL routes")]
  node_azure_routes[("Azure Table routes")]
  node_audit_store[("Audit storage")]
end

node_client(("API client"))
node_backend(("Upstream services"))
node_postgres[("PostgreSQL")]
node_azure[("Azure Table Storage")]

node_client -->|"sends request"| node_proxy_api
node_client -->|"manages routes"| node_admin_api
node_client -->|"checks health"| node_health_api
node_client -->|"requests spec"| node_openapi_api
node_main -->|"wires handler"| node_proxy_api
node_main -->|"wires handler"| node_admin_api
node_main -->|"wires handler"| node_health_api
node_main -->|"initializes"| node_registry
node_main -->|"starts refresh"| node_loader
node_proxy_api -->|"resolves route"| node_registry
node_admin_api -->|"updates routes"| node_registry
node_admin_api -->|"persists changes"| node_route_store
node_loader -->|"loads routes"| node_route_store
node_loader -->|"refreshes routes"| node_registry
node_registry -->|"matches request"| node_matchers
node_registry -->|"dispatches route"| node_filter_chain
node_filter_chain -->|"shares state"| node_filter_context
node_filter_chain -->|"runs policies"| node_security
node_filter_chain -->|"runs safeguards"| node_resilience
node_filter_chain -->|"checks cache"| node_cache
node_filter_chain -->|"records telemetry"| node_observability
node_filter_chain -->|"applies transforms"| node_transform
node_filter_chain -->|"dispatches proxy"| node_proxy_filter
node_proxy_filter -->|"selects target"| node_balancer
node_proxy_filter -->|"forwards request"| node_upstream_client
node_upstream_client -->|"sends HTTP"| node_backend
node_websocket -.->|"relays frames"| node_backend
node_upstream_client -->|"stores response"| node_filter_context
node_filter_context -->|"returns response"| node_proxy_api
node_openapi_api -->|"reads routes"| node_registry
node_openapi_api -.->|"fetches specs"| node_backend
node_route_store -->|"implemented by"| node_postgres_routes
node_route_store -.->|"implemented by"| node_azure_routes
node_postgres_routes -->|"reads and writes"| node_postgres
node_azure_routes -.->|"reads and writes"| node_azure
node_main -->|"configures storage"| node_audit_store
node_observability -->|"writes audit logs"| node_audit_store
node_audit_api -->|"reads audit logs"| node_audit_store
node_audit_store -->|"persists entries"| node_postgres

click node_main "https://github.com/thejkishore/reverse-proxy-go/blob/main/cmd/gateway/main.go"
click node_proxy_api "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/proxy_handler.go"
click node_admin_api "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/admin_handler.go"
click node_health_api "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/health_handler.go"
click node_openapi_api "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/openapi_handler.go"
click node_registry "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/registry/route_registry.go"
click node_loader "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/registry/route_loader.go"
click node_matchers "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/routing/route_matcher.go"
click node_route_models "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/model/route_definition.go"
click node_filter_chain "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/filter/filter_chain.go"
click node_filter_context "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/filter/filter_context.go"
click node_security "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/security/jwt_auth_filter.go"
click node_resilience "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/circuitbreaker/circuit_breaker_filter.go"
click node_cache "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/cache/cache_filter.go"
click node_observability "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/tracing/tracing_filter.go"
click node_transform "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/transform/transform_filter.go"
click node_proxy_filter "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/proxy_filter.go"
click node_balancer "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/loadbalancer/load_balancer.go"
click node_upstream_client "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/upstream_client.go"
click node_websocket "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/websocket_forwarder.go"
click node_route_store "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/route_storage.go"
click node_postgres_routes "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/postgres_route_storage.go"
click node_azure_routes "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/azure_table_route_storage.go"
click node_audit_store "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/audit/postgres_audit_storage.go"
click node_audit_api "https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/audit_handler.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_main,node_proxy_api,node_admin_api,node_health_api,node_openapi_api,node_audit_api,node_client toneBlue
class node_registry,node_loader,node_matchers,node_route_models,node_postgres,node_azure toneAmber
class node_filter_chain,node_filter_context,node_security,node_resilience,node_cache,node_observability,node_transform toneMint
class node_proxy_filter,node_balancer,node_upstream_client,node_websocket toneRose
class node_route_store,node_postgres_routes,node_azure_routes,node_audit_store,node_backend toneIndigo
```

## Components

### Gateway API

- [Gateway bootstrap](https://github.com/thejkishore/reverse-proxy-go/blob/main/cmd/gateway/main.go): `cmd/gateway/main.go`
- [Proxy handler](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/proxy_handler.go): `internal/api/proxy_handler.go`
- [Admin API](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/admin_handler.go): `internal/api/admin_handler.go`
- [Health endpoints](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/health_handler.go): `internal/api/health_handler.go`
- [OpenAPI export](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/openapi_handler.go): `internal/api/openapi_handler.go`
- [Audit endpoints](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/api/audit_handler.go): `internal/api/audit_handler.go`

### Route Management

- [Route registry](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/registry/route_registry.go): `internal/registry/route_registry.go`
- [Route loader](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/registry/route_loader.go): `internal/registry/route_loader.go`
- [Route matchers](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/routing/route_matcher.go): `internal/routing/route_matcher.go`
- [Route definitions](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/model/route_definition.go): `internal/model/route_definition.go`

### Request Pipeline

- [Filter chain](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/filter/filter_chain.go): `internal/filter/filter_chain.go`
- [Request context](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/filter/filter_context.go): `internal/filter/filter_context.go`
- [Security filters](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/security/jwt_auth_filter.go): `internal/security/jwt_auth_filter.go`
- [Resilience filters](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/circuitbreaker/circuit_breaker_filter.go): `internal/circuitbreaker/circuit_breaker_filter.go`
- [Response cache](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/cache/cache_filter.go): `internal/cache/cache_filter.go`
- [Tracing and audit](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/tracing/tracing_filter.go): `internal/tracing/tracing_filter.go`
- [Header and body transforms](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/transform/transform_filter.go): `internal/transform/transform_filter.go`

### Upstream Delivery

- [Proxy filter](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/proxy_filter.go): `internal/proxy/proxy_filter.go`
- [Load balancers](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/loadbalancer/load_balancer.go): `internal/loadbalancer/load_balancer.go`
- [Upstream client](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/upstream_client.go): `internal/proxy/upstream_client.go`
- [WebSocket relay](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/proxy/websocket_forwarder.go): `internal/proxy/websocket_forwarder.go`

### Persistence

- [Route storage](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/route_storage.go): `internal/storage/routes/route_storage.go`
- [PostgreSQL routes](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/postgres_route_storage.go): `internal/storage/routes/postgres_route_storage.go`
- [Azure Table routes](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/routes/azure_table_route_storage.go): `internal/storage/routes/azure_table_route_storage.go`
- [Audit storage](https://github.com/thejkishore/reverse-proxy-go/blob/main/internal/storage/audit/postgres_audit_storage.go): `internal/storage/audit/postgres_audit_storage.go`

### Other components

- **API client**
- **Upstream services**
- **PostgreSQL**
- **Azure Table Storage**

## Connections

- API client → Proxy handler: sends request
- API client → Admin API: manages routes
- API client → Health endpoints: checks health
- API client → OpenAPI export: requests spec
- Gateway bootstrap → Proxy handler: wires handler
- Gateway bootstrap → Admin API: wires handler
- Gateway bootstrap → Health endpoints: wires handler
- Gateway bootstrap → Route registry: initializes
- Gateway bootstrap → Route loader: starts refresh
- Proxy handler → Route registry: resolves route
- Admin API → Route registry: updates routes
- Admin API → Route storage: persists changes
- Route loader → Route storage: loads routes
- Route loader → Route registry: refreshes routes
- Route registry → Route matchers: matches request
- Route registry → Filter chain: dispatches route
- Filter chain → Request context: shares state
- Filter chain → Security filters: runs policies
- Filter chain → Resilience filters: runs safeguards
- Filter chain → Response cache: checks cache
- Filter chain → Tracing and audit: records telemetry
- Filter chain → Header and body transforms: applies transforms
- Filter chain → Proxy filter: dispatches proxy
- Proxy filter → Load balancers: selects target
- Proxy filter → Upstream client: forwards request
- Upstream client → Upstream services: sends HTTP
- WebSocket relay → Upstream services: relays frames
- Upstream client → Request context: stores response
- Request context → Proxy handler: returns response
- OpenAPI export → Route registry: reads routes
- OpenAPI export → Upstream services: fetches specs
- Route storage → PostgreSQL routes: implemented by
- Route storage → Azure Table routes: implemented by
- PostgreSQL routes → PostgreSQL: reads and writes
- Azure Table routes → Azure Table Storage: reads and writes
- Gateway bootstrap → Audit storage: configures storage
- Tracing and audit → Audit storage: writes audit logs
- Audit endpoints → Audit storage: reads audit logs
- Audit storage → PostgreSQL: persists entries