# trickstercache/trickster architecture

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

- Interactive diagram: https://gitdiagram.com/trickstercache/trickster
- Repository: https://github.com/trickstercache/trickster

## Overview

##### Project type and purpose
- Trickster is a high-performance HTTP reverse proxy/cache and time-series database accelerator, implemented as a single Go binary.
- It sits between dashboard clients (e.g., Grafana) or generic HTTP clients and time-series backends (Prometheus, InfluxDB, ClickHouse) or any HTTP origin.

##### File structure
- Top-level modules:
- cmd/trickster: application entry point
- pkg/proxy: core reverse proxy, routing, request/response engines
- pkg/cache: pluggable cache backends (memory, filesystem, Redis, bbolt)
- pkg/backends: per-provider clients & logic (prometheus, influxdb, clickhouse, generic reverse proxy)
- pkg/config: loader, defaults, reload, flags, TLS settings
- pkg/observability: metrics, logging, tracing exporters & registry
- deploy/: Dockerfiles, Helm charts, Kubernetes manifests
- Patterns: layered architecture (listener → router → engines → cache → backend), plugin registries for caches/backends/auth/tracing.

##### Insights from README
- Trickster supports TLS/HTTP2 frontend termination, configurable caching & negative-caching, collapsed forwarding, byte-range requests, delta proxy cache, step-boundary normalization, fast-forward.
- Exposes Prometheus metrics, health endpoints, supports OpenTelemetry/Zipkin tracing.
- Deployable via Docker, Kubernetes, Helm; configured via YAML.

##### Main components & interactions
a. Components
- Clients: Dashboard UIs or generic HTTP clients
- Frontend Listener & TLS Termination (pkg/daemon, pkg/proxy/tls)
- Router & Path Matching (pkg/proxy/router)
- Authentication (pkg/proxy/authenticator)
- Request Engines (pkg/proxy/engines):
– Delta Proxy Cache
– Byte-range handling
– Collapsed forwarding
– Document & HTTP proxy modes
- Cache Layer (pkg/cache/*):
– In-memory, filesystem, Redis, bbolt, clustered index
- Backend Providers (pkg/backends/*): Prometheus, InfluxDB, ClickHouse, generic reverse proxy
- Observability (pkg/observability): metrics endpoint, logging, tracing exporters (OTLP, Zipkin, stdout)
- Configuration Management (pkg/config): loader, reloadable settings
- Deployment Packaging: Docker image, Helm chart, Kubernetes manifests

b. Relationships / Data Flows
1) Client → Listener/TLS → Router
2) Router → Authenticator → Request Rewriters
3) Request Engines check Cache Layer
– On hit: serve cached response
– On miss/partial hit: forward to Backend Provider
4) Backend Provider pools & ALB logic → Upstream TSDB or HTTP origin
5) Response merges (chunked, timeseries merge) → Cache write-through/negative caching
6) Response → Client
7) Each stage emits metrics & trace spans → Observability exporters
8) Config changes trigger dynamic reload

c. Architectural patterns & principles
- Layered, modular design with clear separation of concerns
- Plugin/registry pattern for extensibility (caches, backends, auth, tracing)
- Stateless proxy service; stateful cache can be external (Redis, bbolt)
- Defensive design: negative caching, health checks

d. Key technologies & libraries
- Go modules, standard net/http, OpenTelemetry
- YAML configuration
- Docker, Helm, Kubernetes

## Diagram (Mermaid)

```mermaid
flowchart TD
    Clients["Dashboard UIs / HTTP Clients"]:::external

    subgraph "Trickster Proxy"
        subgraph "Transport & TLS"
            Listener["Listener"]:::core
            TLS["TLS Termination"]:::core
        end
        subgraph "Routing & Authentication"
            Router["Router & Path Matching"]:::core
            Auth["Authenticator"]:::core
        end
        subgraph "Engines"
            Delta["Delta Proxy Cache"]:::core
            Byte["Byte-Range Engine"]:::core
            Collapse["Collapsed Forwarding"]:::core
            Doc["Document Proxy"]:::core
            HTTP["HTTP Proxy"]:::core
        end
        subgraph "Cache Layer"
            Mem["In-Memory Cache"]:::cache
            FS["Filesystem Cache"]:::cache
            Redis["Redis Cache"]:::cache
            BBolt["bbolt Cache"]:::cache
            Index["Clustered Index"]:::cache
        end
        subgraph "Backend Providers"
            Prom["Prometheus Backend"]:::core
            Influx["InfluxDB Backend"]:::core
            CH["ClickHouse Backend"]:::core
            RP["Generic Reverse Proxy"]:::core
        end
    end

    subgraph "TSDB & External Origins"
        PrometheusExt["Prometheus"]:::external
        InfluxExt["InfluxDB"]:::external
        CHExt["ClickHouse"]:::external
        Origin["HTTP Origin"]:::external
    end

    Observ["Observability & Metrics"]:::observ
    Config["Configuration Management"]:::config

    Clients --> Listener --> TLS --> Router --> Auth
    Auth --> Delta
    Auth --> Byte
    Auth --> Collapse
    Auth --> Doc
    Auth --> HTTP

    Delta --> Mem
    Delta --> FS
    Delta --> Redis
    Delta --> BBolt
    Delta --> Index

    Byte --> Mem
    Byte --> FS
    Byte --> Redis
    Byte --> BBolt
    Byte --> Index

    Collapse --> Mem
    Collapse --> FS
    Collapse --> Redis
    Collapse --> BBolt
    Collapse --> Index

    Doc --> Mem
    Doc --> FS
    Doc --> Redis
    Doc --> BBolt
    Doc --> Index

    HTTP --> Mem
    HTTP --> FS
    HTTP --> Redis
    HTTP --> BBolt
    HTTP --> Index

    Mem -->|miss| Prom
    FS -->|miss| Prom
    Redis -->|miss| Prom
    BBolt -->|miss| Prom
    Index -->|miss| Prom

    Prom --> PrometheusExt
    Influx --> InfluxExt
    CH --> CHExt
    RP --> Origin

    Prom -->|metrics/health| Observ
    Influx -->|metrics/health| Observ
    CH -->|metrics/health| Observ
    RP -->|metrics/health| Observ

    Listener -->|metrics/health| Observ
    TLS -->|metrics/health| Observ
    Router -->|metrics/health| Observ
    Auth -->|metrics/health| Observ
    Delta -->|metrics/health| Observ
    Byte -->|metrics/health| Observ
    Collapse -->|metrics/health| Observ
    Doc -->|metrics/health| Observ
    HTTP -->|metrics/health| Observ

    Config --> Router
    Config --> Delta
    Config --> Prom
    Config --> Mem

    classDef external fill:#ADD8E6,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef cache fill:#FFA500,stroke:#000
    classDef observ fill:#DA70D6,stroke:#000
    classDef config fill:#DDA0DD,stroke:#000

    click Listener "https://github.com/trickstercache/trickster/blob/main/pkg/daemon/setup/listeners.go"
    click TLS "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/tls/tls.go"
    click Router "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/router/router.go"
    click Auth "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/authenticator/authenticator.go"
    click Delta "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/engines/deltaproxycache.go"
    click Byte "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/ranges/byterange/range.go"
    click Collapse "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/engines/progressive_collapse_forwarder.go"
    click Doc "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/engines/document.go"
    click HTTP "https://github.com/trickstercache/trickster/blob/main/pkg/proxy/engines/httpproxy.go"
    click Mem "https://github.com/trickstercache/trickster/blob/main/pkg/cache/memory/memory.go"
    click FS "https://github.com/trickstercache/trickster/blob/main/pkg/cache/filesystem/filesystem.go"
    click Redis "https://github.com/trickstercache/trickster/blob/main/pkg/cache/redis/redis.go"
    click BBolt "https://github.com/trickstercache/trickster/blob/main/pkg/cache/bbolt/bbolt.go"
    click Index "https://github.com/trickstercache/trickster/blob/main/pkg/cache/index/index.go"
    click Prom "https://github.com/trickstercache/trickster/blob/main/pkg/backends/prometheus/prometheus.go"
    click Influx "https://github.com/trickstercache/trickster/blob/main/pkg/backends/influxdb/influxdb.go"
    click CH "https://github.com/trickstercache/trickster/blob/main/pkg/backends/clickhouse/clickhouse.go"
    click RP "https://github.com/trickstercache/trickster/blob/main/pkg/backends/reverseproxy/rp.go"
    click Observ "https://github.com/trickstercache/trickster/blob/main/pkg/observability/metrics/metrics.go"
    click Config "https://github.com/trickstercache/trickster/blob/main/pkg/config/loader.go"
```
