# cybertec-postgresql/pgwatch architecture

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

- Interactive diagram: https://gitdiagram.com/cybertec-postgresql/pgwatch
- Repository: https://github.com/cybertec-postgresql/pgwatch

## Overview

Based on our analysis of the file tree and the README, “pgwatch” is a PostgreSQL monitoring solution that comprises a backend monitoring agent (largely written in Go), an API layer, and a web-based user interface (developed with React/TypeScript) that enables administrative tasks as well as dashboard interactions. In addition, the project supplies Docker configurations and compose files to facilitate a complete setup that includes external visualization via Grafana and a management interface via pgAdmin.

##### Main Components
- Backend Monitoring Agent: This is the heart of pgwatch. It handles metrics collection from PostgreSQL instances and includes various internal modules (e.g., metrics collection, sinks, sources, logging, reaper).
- API & Web Server: Under the “internal/webserver” and “api” directories, this component serves REST/HTTP endpoints used by the web interface for configuration, authentication (JWT) and metrics display.
- Web UI: Located in “internal/webui”, this part is a full-fledged React application offering the administrative and operational user interface for configuration and live monitoring.
- Configuration and Metrics Database: The project uses a PostgreSQL database for storing configuration and metrics data. Also, the Docker files reference database initialization and bootstrap scripts.
- External Tools and Dashboards: Grafana is used for visualization (with dedicated dashboards provided in the “grafana” directory), and pgAdmin for database management. These are integrated and deployed via Docker Compose.
- Docker & Deployment Infrastructure: Dockerfiles, various Docker Compose YAML files, and testing scripts orchestrate the entire multi-container deployment.

##### Relationships and Interactions
- The Monitoring Agent interacts with PostgreSQL instances to fetch performance metrics via built-in “sources” and “metrics” modules.
- Collected data is sent to the internal Metrics Database where it is stored and made available for analysis.
- The API/web server exposes endpoints that the Web UI (React) consumes and that also facilitate remote configuration.
- Grafana queries the Metrics Database to display dashboards and metrics, while pgAdmin offers management capabilities.
- Docker Compose files coordinate the deployment of these components; they set up networks among the pgwatch agent, the database, Grafana, and pgAdmin.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clear separation exists between data acquisition (monitoring agent and database interactions), business logic (API/web server), and presentation (Web UI and dashboards).
- Micro-modularization: The backend is subdivided into logically separated modules (for logging, metrics, sinks, sources, reaper, etc.) that help in organizing code for maintenance and scalability.
- Containerization: The project leverages Docker extensively for isolated deployments and environment consistency.
- External Integration: The design emphasizes integration with external monitoring and database management tools (Grafana and pgAdmin).

##### Relevant Technologies
- Go: The core implementation for the backend monitoring agent, API, and internal modules.
- React/TypeScript: Powers the frontend web UI.
- PostgreSQL: Used both as the monitored database and as the internal configuration/metrics store.
- Docker & Docker Compose: Scripts and configurations are provided for building, testing, and orchestrating all services.
- Grafana: For visualization and dashboarding of metrics.
- Additional configuration and testing tools (e.g., GitHub Actions for CI/CD, goreleaser for release management, and linting tools).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External input
    PS["PostgreSQL Instances"]:::database

    %% Backend Components
    subgraph "Backend Components"
        subgraph "Monitoring Agent"
            A1["cmd/pgwatch (Monitoring Agent)"]:::backend
            A2["internal/metrics"]:::backend
            A3["internal/sinks"]:::backend
            A4["internal/sources"]:::backend
            A5["internal/reaper"]:::backend
            A6["internal/log"]:::backend
        end
        subgraph "API/Web Server"
            B1["api (API Endpoints)"]:::backend
            B2["internal/webserver (API Implementation)"]:::backend
        end
    end

    %% Data Storage
    subgraph "Data Storage"
        D1["internal/db (Config & Metrics DB)"]:::database
        D2["docker/bootstrap (DB Initialization)"]:::database
    end

    %% Frontend Layer
    subgraph "Frontend"
        F1["internal/webui (Web UI)"]:::frontend
    end

    %% External Tools and Dashboards
    subgraph "External Tools"
        E1["grafana (Grafana Dashboards)"]:::external
        E2["pgAdmin (DB Management)"]:::external
        E3["pgAdmin Config"]:::external
    end

    %% Deployment and Infrastructure
    subgraph "Deployment"
        DP1["docker (Docker Deployment Scripts)"]:::deployment
        DP2["docker-compose (Docker Compose Configs)"]:::deployment
    end

    %% Connections
    PS -- "collectsMetrics" --> A4
    A1 -- "orchestrates" --> A2
    A1 -- "orchestrates" --> A3
    A1 -- "orchestrates" --> A4
    A1 -- "orchestrates" --> A5
    A1 -- "orchestrates" --> A6

    A1 -- "sendsMetrics" --> D1

    B1 -- "calls" --> B2
    B1 -- "APIcalls" --> F1

    D1 -- "queryMetrics" --> E1
    D1 -- "manageDB" --> E2
    E3 -- "config" --> E2

    DP1 -- "deploys" --> A1
    DP1 -- "deploys" --> B1
    DP1 -- "deploys" --> D1
    DP1 -- "deploys" --> F1
    DP1 -- "deploys" --> E1
    DP1 -- "deploys" --> E2

    DP2 -- "orchestrates" --> A1
    DP2 -- "orchestrates" --> B1
    DP2 -- "orchestrates" --> D1
    DP2 -- "orchestrates" --> F1
    DP2 -- "orchestrates" --> E1
    DP2 -- "orchestrates" --> E2

    %% Click Events
    click A1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/cmd/pgwatch"
    click A2 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/metrics"
    click A3 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/sinks"
    click A4 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/sources"
    click A5 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/reaper"
    click A6 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/log"
    click B1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/api"
    click B2 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/webserver"
    click F1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/webui"
    click D1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/internal/db"
    click D2 "https://github.com/cybertec-postgresql/pgwatch/tree/master/docker/bootstrap"
    click E1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/grafana"
    click E2 "https://github.com/cybertec-postgresql/pgwatch/tree/master/docker/bootstrap/pgadmin_pass"
    click E3 "https://github.com/cybertec-postgresql/pgwatch/blob/master/docker/bootstrap/pgadmin_servers.json"
    click DP1 "https://github.com/cybertec-postgresql/pgwatch/tree/master/docker"
    click DP2 "https://github.com/cybertec-postgresql/pgwatch/blob/master/docker/docker-compose*.yml"

    %% Styles
    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef frontend fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef deployment fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
