# pgsty/pigsty architecture

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

- Interactive diagram: https://gitdiagram.com/pgsty/pigsty
- Repository: https://github.com/pgsty/pigsty

## Overview

##### Project Type and Purpose
- Pigsty is an infrastructure-as-code and cluster orchestration system for PostgreSQL.
- It is designed for deploying self-healing PostgreSQL clusters (with HA components like Patroni, PgBouncer, PgBackrest, HAProxy) plus other modules such as observability (Prometheus/Grafana), object storage (MinIO), additional app modules (e.g., Gitea, Supabase, FerretDB, Mattermost, etc.) and even tools for Docker automation.
- The README clearly describes modularity with a “core” set of modules (PGSQL, INFRA, NODE, ETCD) and many extended modules.

##### File Structure
- The top-level directories and files (such as .gitignore, LICENSE, Makefile, README, ansible.cfg, and various playbooks like install.yml) show that the project is built on automation (using Ansible, Terraform, and Vagrant) and container orchestration (with many docker-compose.yml files found in subdirectories).
- There is extensive use of “roles”, “conf”, “templates”, and even infrastructure definitions (terraform, vagrant) implying heavy reliance on declarative configuration and reproducible deployment across nodes.

##### README for Further Insights
- The README outlines the primary modules: PGSQL, INFRA, NODE, ETCD, and describes how they are composed to deliver HA PostgreSQL clusters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        AdminNode["Administration Node"]:::control
        CLITools["CLI Tools"]:::control
    end

    %% Core Modules
    subgraph "Core Modules"
        PGSQL["PGSQL Cluster (Patroni, PgBouncer, PgBackrest, HAProxy)"]:::core
        INFRA["INFRA Services (Nginx, DNSMasq, Prometheus, Grafana)"]:::core
        NODE["NODE Management (Host Initialization & Config)"]:::core
        ETCD["ETCD Config Store"]:::core
    end

    %% Extended Modules
    subgraph "Extended Modules"
        ExtendedServices["Extended Service Modules (App Containers)"]:::extended
    end

    %% Infrastructure as Code Tools
    subgraph "IaC Tools"
        Terraform["Terraform Specs"]:::iac
        Vagrant["Vagrant Configs"]:::iac
    end

    %% Relationships from Control Plane to Core Modules
    AdminNode -->|"deploys"| PGSQL
    AdminNode -->|"deploys"| INFRA
    AdminNode -->|"deploys"| NODE
    AdminNode -->|"deploys"| ETCD
    CLITools -->|"manages"| PGSQL
    CLITools -->|"manages"| INFRA
    CLITools -->|"manages"| NODE
    CLITools -->|"manages"| ETCD

    %% Interactions within Core Modules
    PGSQL -->|"coordination"| ETCD
    PGSQL -->|"serviceRouting"| INFRA

    %% Interactions with Extended Modules
    ExtendedServices -->|"integrates"| PGSQL
    ExtendedServices -->|"routes"| INFRA

    %% IaC Tools Interaction
    AdminNode -->|"orchestrates"| Terraform
    AdminNode -->|"orchestrates"| Vagrant

    %% Click Events for Administration/Control Node
    click AdminNode "https://github.com/pgsty/pigsty/blob/main/ansible.cfg"
    click CLITools "https://github.com/pgsty/pigsty/tree/main/bin"

    %% Click Events for Core Modules
    click PGSQL "https://github.com/pgsty/pigsty/tree/main/roles/pgsql"
    click INFRA "https://github.com/pgsty/pigsty/tree/main/roles/infra"
    click NODE "https://github.com/pgsty/pigsty/tree/main/roles/node"
    click ETCD "https://github.com/pgsty/pigsty/tree/main/roles/etcd"

    %% Click Event for Extended Modules
    click ExtendedServices "https://github.com/pgsty/pigsty/tree/main/app"

    %% Click Events for IaC Tools
    click Terraform "https://github.com/pgsty/pigsty/tree/main/terraform"
    click Vagrant "https://github.com/pgsty/pigsty/tree/main/vagrant"

    %% Styles
    classDef control fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef extended fill:#cfc,stroke:#333,stroke-width:2px;
    classDef iac fill:#fc9,stroke:#333,stroke-width:2px;
```
