# yrsurya/dockprom architecture

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

- Interactive diagram: https://gitdiagram.com/yrsurya/dockprom
- Repository: https://github.com/yrsurya/dockprom

## Overview

##### Project type and purpose
- This is a Docker-based monitoring “stack” orchestrated via Docker Compose.
- It brings up Prometheus (time-series database + scraper), Grafana (visualization), AlertManager (alert routing), NodeExporter and cAdvisor (metric exporters), Pushgateway (batch/job metrics), and Caddy (reverse proxy + basic-auth).

##### File structure
- Top-level orchestration:
- docker-compose.yml (main compose)
- docker-compose.exporters.yml (optional exporters only)
- Service folders/configs:
- prometheus/ (scrape config, alert.rules)
- alertmanager/ (alertmanager.yml)
- grafana/ (provisioning/dashboards, datasources)
- caddy/ (Caddyfile)
- Helpers/aws: CloudFormation/TaskDefinition JSON and Prometheus config for AWS ECS/EC2 deployments.
- config/: environment variables for Grafana auth.
- screens/: example visualization screenshots.

##### Main components & their roles
- Docker Host & Docker Engine (underlying host VM or physical server)
- Exporters (running as containers on the host network “monitor-net”):
- node_exporter – exposes host metrics (CPU, memory, filesystem)
- cAdvisor – exposes container metrics (resource usage per container)
- Prometheus server – periodically scrapes exporters & Pushgateway, stores metrics, evaluates alert.rules
- Pushgateway – accepts push-style metrics (for batch jobs)
- AlertManager – receives alerts from Prometheus, groups & routes notifications (Slack, email, etc.)
- Grafana – queries Prometheus, renders dashboards (pre-provisioned via grafana/provisioning)
- Caddy – reverse-proxy + basic-auth in front of Prometheus and AlertManager HTTP UIs
- External notifications – e.g., Slack webhook endpoint, email server

##### Relationships & data flows
- node_exporter → (HTTP scrape) → Prometheus
- cAdvisor → Prometheus
- Pushgateway ← (push) ← batch job / ephemeral metrics
- Prometheus → (alert POST) → AlertManager
- Grafana ← (query) ← Prometheus
- User’s browser → Caddy → {Prometheus UI, AlertManager UI, Grafana UI}
- AlertManager → (webhook) → Slack / email

##### Architectural patterns & design principles
- Containerized micro-services: one concern per container
- Clear separation: data collection (exporters), data storage & processing (Prometheus), presentation (Grafana), alert routing (AlertManager), edge routing/auth (Caddy)
- Declarative provisioning: Grafana dashboards and datasources auto-loaded from filesystem
- Infrastructure-as-code for AWS ECS via helpers/aws

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Host Boundary
    subgraph "Docker Host (monitor-net)"
        direction TB
        %% Collectors
        node_exp["node_exporter"]:::collectors
        cadvisor["cAdvisor"]:::collectors
        pushgw["Pushgateway"]:::collectors

        %% Storage & Processing
        prometheus["Prometheus"]:::storage
        tsdb[(TSDB)]:::tsdb

        %% Alerting & Visualization
        alertmgr["AlertManager"]:::alert
        grafana["Grafana"]:::visualization

        %% Proxy
        caddy["Caddy"]:::proxy

        %% Internal Connections
        node_exp -->|"scrape /metrics (HTTP)"| prometheus
        cadvisor -->|"scrape /metrics (HTTP)"| prometheus
        pushgw -->|"push metrics (HTTP)"| prometheus
        prometheus -->|"alert webhook (POST)"| alertmgr
        grafana -->|"query /api/v1/query (HTTP)"| prometheus
        prometheus --> tsdb
        %% User Browser via Caddy
        user["User Browser"]:::external
        user -->|"HTTP" | caddy
        caddy -->|"Proxy to Grafana UI" | grafana
        caddy -->|"Proxy to Prometheus UI" | prometheus
        caddy -->|"Proxy to AlertManager UI" | alertmgr

        %% External Notifications
        slack["Slack / Email"]:::external
        alertmgr -->|"webhook" | slack
    end

    %% Project Files with Click Events
    subgraph "Project Files"
        direction TB
        dc_main["docker-compose.yml"]:::files
        dc_exp["docker-compose.exporters.yml"]:::files
        prom_conf["prometheus/prometheus.yml"]:::files
        prom_rules["prometheus/alert.rules"]:::files
        am_conf["alertmanager/config.yml"]:::files
        gf_dash["grafana/provisioning/dashboards/"]:::files
        gf_ds["grafana/provisioning/datasources/datasource.yml"]:::files
        caddyfile["caddy/Caddyfile"]:::files
        cfg_env["config/"]:::files
        aws_node["helpers/aws/node_exporter_task_definition.json"]:::files
        aws_cad["helpers/aws/cadvisor_ecs_task_definition.json"]:::files
        aws_prom["helpers/aws/prometheus.yml"]:::files
        screens["screens/"]:::files
    end

    %% Click Events
    click dc_main "https://github.com/yrsurya/dockprom/blob/master/docker-compose.yml"
    click dc_exp "https://github.com/yrsurya/dockprom/blob/master/docker-compose.exporters.yml"
    click prom_conf "https://github.com/yrsurya/dockprom/blob/master/prometheus/prometheus.yml"
    click prom_rules "https://github.com/yrsurya/dockprom/blob/master/prometheus/alert.rules"
    click am_conf "https://github.com/yrsurya/dockprom/blob/master/alertmanager/config.yml"
    click gf_dash "https://github.com/yrsurya/dockprom/tree/master/grafana/provisioning/dashboards/"
    click gf_ds "https://github.com/yrsurya/dockprom/blob/master/grafana/provisioning/datasources/datasource.yml"
    click caddyfile "https://github.com/yrsurya/dockprom/tree/master/caddy/Caddyfile"
    click cfg_env "https://github.com/yrsurya/dockprom/tree/master/config/"
    click aws_node "https://github.com/yrsurya/dockprom/blob/master/helpers/aws/node_exporter_task_definition.json"
    click aws_cad "https://github.com/yrsurya/dockprom/blob/master/helpers/aws/cadvisor_ecs_task_definition.json"
    click aws_prom "https://github.com/yrsurya/dockprom/blob/master/helpers/aws/prometheus.yml"
    click screens "https://github.com/yrsurya/dockprom/tree/master/screens/"

    %% Styles
    classDef collectors fill:#D0E8FF,stroke:#357ABD,color:#000;
    classDef storage fill:#DFF0D8,stroke:#3C763D,color:#000;
    classDef visualization fill:#FCF8E3,stroke:#8A6D3B,color:#000;
    classDef alert fill:#F2DEDE,stroke:#A94442,color:#000;
    classDef proxy fill:#EEEEEE,stroke:#777777,color:#000;
    classDef tsdb fill:#FFFFFF,stroke:#000000,color:#000,stroke-dasharray: 5 5;
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#000,stroke-dasharray: 2 2;
    classDef files fill:#F5F5F5,stroke:#CCCCCC,color:#000;
```
