# askrella/sauron architecture

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

- Interactive diagram: https://gitdiagram.com/askrella/sauron
- Repository: https://github.com/askrella/sauron

## Overview

##### Project type and purpose
- This is an Infrastructure-as-Code project using Terraform to provision a production-ready, self-hosted monitoring cluster on Hetzner Cloud, fronted by Cloudflare.
- It bundles a full monitoring stack (Grafana, Prometheus, Loki, Tempo, Thanos, Node-Exporter, Promtail) running as Docker containers on each VM.

##### File structure
- Top-level “terraform” directory with subfolders “cluster”, “cloudflare”, “hetzner_server” – each is a Terraform module responsible for parts of the infra.
- “terraform/cloudflare” holds DNS and Load Balancing resources.
- “terraform/hetzner_server” provisions the VMs and private networking.

##### Extract insights from the README
- Describes a multi-node setup (recommendation: 3+ nodes).
- Private IPv6 network on Hetzner, Caddy on each node for TLS & routing.
- Cloudflare Load Balancer & DNS publish the endpoints.
- Hetzner Object Store as S3 backend for Thanos long-term storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients"]:::external

    %% Terraform Layer
    subgraph "Terraform (IaC)" 
        direction TB
        TF["Terraform Orchestrator"]:::terraform
        CFMod["Cloudflare Module"]:::terraform
        HZProv["Hetzner Provisioning"]:::terraform
        ClusterMod["Cluster Module"]:::terraform
    end

    %% External Services
    subgraph "Cloudflare" 
        direction TB
        DNS["DNS"]:::cloudflare
        LB["Load Balancer"]:::cloudflare
    end

    %% Hetzner Infrastructure
    subgraph "Hetzner Cloud" 
        direction TB
        VPC["Private IPv6 Network"]:::hetzner
        ObjStore["Hetzner Object Store"]:::storage
        VMCluster["VM Cluster"]:::hetzner
    end

    %% VM Cluster and Containers
    subgraph "VM Cluster" 
        direction TB
        subgraph "VM Node" 
            direction TB
            Caddy["caddy:443"]:::container
            Prom["prometheus:9090"]:::container
            NodeExp["node-exporter:9100"]:::container
            CAD["cAdvisor:8080"]:::container
            subgraph "Thanos Suite"
                direction TB
                ThSide["thanos-sidecar"]:::container
                ThComp["thanos-compactor"]:::container
                ThStore["thanos-store-gateway"]:::container
                ThRule["thanos-ruler"]:::container
                ThQuer["thanos-querier"]:::container
            end
            Graf["grafana:3000"]:::container
            Loki["loki:3100"]:::container
            PTail["promtail"]:::container
            Tempo["tempo"]:::container
            Maria["mariadb-galera"]:::storage
        end
    end

    %% Relationships
    Clients -->|DNS lookup| DNS
    DNS -->|resolves AAAA| LB
    LB -->|HTTPS| Caddy
    Caddy -->|proxy| Prom
    Caddy -->|proxy| Graf
    Caddy -->|proxy| Loki
    Caddy -->|proxy| Tempo

    Prom -->|scrapes| NodeExp
    Prom -->|scrapes| CAD
    Prom -->|sidecar write| ThSide
    ThSide -->|store data| ThStore
    ThStore -->|persist| ObjStore
    Graf -->|query| ThQuer
    ThQuer -->|retrieve aggregated| Prom

    PTail -->|ship logs| Loki
    Tempo -->|ingest traces| Tempo

    %% Control plane arrows
    TF -->|provision via API| CFMod
    TF -->|provision via API| HZProv
    TF -->|invoke| ClusterMod
    CFMod --> DNS
    CFMod --> LB
    HZProv --> VMCluster
    ClusterMod --> VMCluster

    %% Network
    VMCluster --- VPC
    Prom -->|dashed| ObjStore
    classDef terraform fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef cloudflare fill:#B3D1FF,stroke:#036,stroke-width:1px
    classDef hetzner fill:#CCFFCC,stroke:#093,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#888,stroke-width:1px
    classDef container fill:#FFCC99,stroke:#E65C00,stroke-width:1px
    classDef storage fill:#D1B3FF,stroke:#660099,stroke-width:1px

    %% Click Events
    click TF "https://github.com/askrella/sauron/blob/main/terraform/main.tf"
    click CFMod "https://github.com/askrella/sauron/blob/main/terraform/cloudflare/cloudflare.tf"
    click HZProv "https://github.com/askrella/sauron/blob/main/terraform/hetzner_server/server.tf"
    click ClusterMod "https://github.com/askrella/sauron/blob/main/terraform/cluster/README.md"
    click Caddy "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/caddy.tf"
    click Prom "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/prometheus.tf"
    click NodeExp "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/node-exporter.tf"
    click CAD "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/cadvisor.tf"
    click ThSide "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/thanos.tf"
    click Graf "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/grafana.tf"
    click Loki "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/loki.tf"
    click PTail "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/promtail.tf"
    click Tempo "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/tempo.tf"
    click Maria "https://github.com/askrella/sauron/blob/main/terraform/cluster/docker/mariadb.tf"
```
