# jacksontj/promxy architecture

> Architecture diagram of the GitHub repository jacksontj/promxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacksontj/promxy
- Repository: https://github.com/jacksontj/promxy

## Overview

##### Project Type and Purpose
- Promxy is a backend proxy service (no UI) written in Go.
- Its purpose is to expose a single Prometheus‐compatible `/api/v1` endpoint that federates/shards queries across multiple Prometheus servers (ServerGroups), merges results, and returns unified timeseries data. It also supports remote_write export of metrics.

##### File Structure Analysis
- cmd/
- promxy/ (main binary, config, demo files)
- remote_write_exporter/ (standalone exporter binary)
- pkg/ – core Go libraries, organized by function:
- config, logging, middleware (headers, instrumentation)
- promclient & promhttputil (HTTP client logic, query parsing)
- servergroup (definition of Prometheus clusters)
- proxyquerier & proxystorage (scatter-gather + merge logic)
- server (HTTP API handler, TLS config)
- remote & alertbackfill (remote_read/write queueing, alert rule merging)
- deploy/ – Dockerfiles, docker-compose, Kubernetes & Helm charts.
- test/ – integration & PromQL tests.

##### README Insights
- Promxy uses a “scatter-gather” approach: every query is issued to all configured servers, then merged.
- ServerGroup concept: logical grouping of identical Prometheus instances.
- Supports alerting/recording rules via remote_write.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["External Clients (Grafana, curl, PromQL clients)"]:::external

    %% Ingress & Middleware Layer
    subgraph "Ingress & Middleware"
        HTTPServer["HTTP Server & TLS (pkg/server/api.go)"]:::internal
        Middleware["Middleware (headers, instrumentation)"]:::internal
    end

    %% Config Loader & ServerGroup Manager
    subgraph "Config & ServerGroup"
        ConfigLoader["Config Loader (pkg/config/config.go)"]:::internal
        ConfigReload["Hot-Reload (pkg/config/reloadable.go)"]:::internal
        ServerGroupManager["ServerGroup Manager (pkg/servergroup/servergroup.go)"]:::internal
        ServerGroupConfig["ServerGroup Config (pkg/servergroup/config.go)"]:::internal
    end

    %% Query Orchestration & Merge
    subgraph "Query Orchestrator"
        PromClient["Prometheus HTTP Client & Query Parsing (pkg/promclient/)"]:::internal
        PromHTTPUtilMerge["PromHTTP Util Merge (pkg/promhttputil/merge.go)"]:::internal
        PromHTTPUtilLabel["PromHTTP Util LabelQuery (pkg/promhttputil/labelquery.go)"]:::internal
        QueryOrchestrator["Scatter-Gather Orchestrator (pkg/proxyquerier/querier.go)"]:::internal
        MergeEngine["Merge Engine & Timeseries Storage Stub (pkg/proxystorage/proxy.go)"]:::internal
    end

    %% Remote & Alerting
    subgraph "Remote & Alertbackfill"
        RemoteClient["Remote Read/Write Client (pkg/remote/client.go)"]:::internal
        RemoteQueue["Queue Manager (pkg/remote/queue_manager.go)"]:::internal
        RemoteRead["Remote Read (pkg/remote/read.go)"]:::internal
        RemoteWrite["Remote Write (pkg/remote/write.go)"]:::internal
        AlertBackfill["Alert Backfill (pkg/alertbackfill/backfill.go)"]:::internal
        AlertRule["Alert Rule Merge (pkg/alertbackfill/rule.go)"]:::internal
    end

    %% Binaries
    subgraph "Binaries"
        PromxyMain["Main Binary (cmd/promxy/main.go)"]:::internal
        RemoteExporter["Remote Write Exporter (cmd/remote_write_exporter/main.go)"]:::internal
    end

    %% Deployment
    subgraph "Deployment Artifacts"
        DockerPromxy["Dockerfile.promxy"]:::deployment
        DockerCompose["docker-compose.yml"]:::deployment
        HelmChart["Helm Charts (deploy/k8s/helm-charts/promxy/)"]:::deployment
        K8sManifest["Kubernetes Manifest (deploy/k8s/promxy.yaml)"]:::deployment
    end

    %% Tests
    subgraph "Tests"
        Test1["PromQL Test (test/promql_test.go)"]:::internal
        Test2["Bench Test (test/promql_bench_test.go)"]:::internal
    end

    %% External Services
    subgraph "Prometheus Backends" 
        direction TB
        BackendGroup1["ServerGroup A (N Prometheus)"]:::external
        BackendGroup2["ServerGroup B (M Prometheus)"]:::external
    end

    RemoteTSDB["Remote TSDB (optional)"]:::external

    %% Data Flows
    Clients -->|requests| HTTPServer
    HTTPServer -->|middleware| Middleware
    HTTPServer -->|load config| ConfigLoader
    HTTPServer -->|route query| QueryOrchestrator
    ConfigLoader -->|reloads| ConfigReload
    ConfigReload -->|updates| ServerGroupManager
    ServerGroupManager -->|provides endpoints| QueryOrchestrator

    QueryOrchestrator -->|scatter queries| PromClient
    PromClient -->|HTTP calls| BackendGroup1
    PromClient -->|HTTP calls| BackendGroup2
    BackendGroup1 -->|responses| PromHTTPUtilMerge
    BackendGroup2 -->|responses| PromHTTPUtilMerge
    PromHTTPUtilMerge -->|merge time series| MergeEngine
    MergeEngine -->|return unified data| HTTPServer
    HTTPServer -->|response| Clients

    AlertRule -->|push rules| RemoteExporter
    RemoteExporter -->|remote_write| RemoteTSDB

    %% Optional remote flows
    QueryOrchestrator --> RemoteClient
    RemoteClient --> RemoteQueue
    RemoteQueue --> RemoteRead
    RemoteQueue --> RemoteWrite

    %% Binaries to Deployment
    PromxyMain --> DockerPromxy
    PromxyMain --> HelmChart
    RemoteExporter --> DockerCompose
    RemoteExporter --> K8sManifest

    %% Tests referencing modules
    Test1 --> PromClient
    Test2 --> QueryOrchestrator

    %% Click Events
    click HTTPServer "https://github.com/jacksontj/promxy/blob/master/pkg/server/api.go"
    click Middleware "https://github.com/jacksontj/promxy/blob/master/pkg/middleware/headers.go"
    click ConfigLoader "https://github.com/jacksontj/promxy/blob/master/pkg/config/config.go"
    click ConfigReload "https://github.com/jacksontj/promxy/blob/master/pkg/config/reloadable.go"
    click ServerGroupManager "https://github.com/jacksontj/promxy/blob/master/pkg/servergroup/servergroup.go"
    click ServerGroupConfig "https://github.com/jacksontj/promxy/blob/master/pkg/servergroup/config.go"
    click PromClient "https://github.com/jacksontj/promxy/tree/master/pkg/promclient/"
    click PromHTTPUtilMerge "https://github.com/jacksontj/promxy/blob/master/pkg/promhttputil/merge.go"
    click PromHTTPUtilLabel "https://github.com/jacksontj/promxy/blob/master/pkg/promhttputil/labelquery.go"
    click QueryOrchestrator "https://github.com/jacksontj/promxy/blob/master/pkg/proxyquerier/querier.go"
    click MergeEngine "https://github.com/jacksontj/promxy/blob/master/pkg/proxystorage/proxy.go"
    click RemoteClient "https://github.com/jacksontj/promxy/blob/master/pkg/remote/client.go"
    click RemoteQueue "https://github.com/jacksontj/promxy/blob/master/pkg/remote/queue_manager.go"
    click RemoteRead "https://github.com/jacksontj/promxy/blob/master/pkg/remote/read.go"
    click RemoteWrite "https://github.com/jacksontj/promxy/blob/master/pkg/remote/write.go"
    click AlertBackfill "https://github.com/jacksontj/promxy/blob/master/pkg/alertbackfill/backfill.go"
    click AlertRule "https://github.com/jacksontj/promxy/blob/master/pkg/alertbackfill/rule.go"
    click PromxyMain "https://github.com/jacksontj/promxy/blob/master/cmd/promxy/main.go"
    click RemoteExporter "https://github.com/jacksontj/promxy/blob/master/cmd/remote_write_exporter/main.go"
    click DockerPromxy "https://github.com/jacksontj/promxy/blob/master/deploy/docker/Dockerfile.promxy"
    click DockerCompose "https://github.com/jacksontj/promxy/blob/master/deploy/docker/docker-compose.yml"
    click HelmChart "https://github.com/jacksontj/promxy/tree/master/deploy/k8s/helm-charts/promxy/"
    click K8sManifest "https://github.com/jacksontj/promxy/blob/master/deploy/k8s/promxy.yaml"
    click Test1 "https://github.com/jacksontj/promxy/blob/master/test/promql_test.go"
    click Test2 "https://github.com/jacksontj/promxy/blob/master/test/promql_bench_test.go"

    %% Styles
    classDef internal fill:#D6E9FE,stroke:#2B6CB0,color:#1A365D
    classDef external fill:#C6F6D5,stroke:#2F855A,color:#22543D
    classDef deployment fill:#FEEBC8,stroke:#DD6B20,color:#C05621
```
