# cybertec-postgresql/patroni-windows-packaging architecture

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

- Interactive diagram: https://gitdiagram.com/cybertec-postgresql/patroni-windows-packaging
- Repository: https://github.com/cybertec-postgresql/patroni-windows-packaging

## Overview

This repo is not an “application” with request/response flows; it’s a **Windows packaging + installer automation project** for running **Patroni (PostgreSQL HA manager)** on Windows.

- **Build/release packaging pipeline** (PowerShell scripts + Inno Setup + GitHub Actions)
- **Install-time behavior** (what gets installed, where, and how services are registered)
- **Runtime topology on Windows** (Windows services: etcd, patroni, vip; and how they interact with PostgreSQL and with each other across nodes)

##### CI/CD and release automation
- `.github/workflows/test.yml` and `.github/workflows/release.yml`
- “Test” and “Release” pipelines producing artifacts.
- `.github/dependabot.yml`
- Optional: show dependency update automation if relevant.

##### Build scripts (local developer build)
- `make.ps1`, `clean.ps1`, `globals.ps1`
- These are part of the build toolchain (inputs to produce release artifacts).

##### Installer definition
- `installer/patroni.iss`
- Inno Setup script defining what files are bundled and what installer does.

##### Runtime payload (what gets installed)
Everything under `src/` is the runtime payload/config/scripts:
- Configs: `src/patroni.yaml`, `src/etcd.yaml`, `src/vip.yaml`
- Windows service wrapper configs: `src/patroni_service.xml`, `src/etcd_service.xml`, `src/vip_service.xml`
- Install/uninstall: `src/install.ps1`, `src/uninstall.ps1`
- CLI helper: `src/patronictl.bat`

##### Documentation
- `doc/setup.md`, `README.md`

**Goal:** Show how source files become the downloadable release (ZIP/installer).

- Developer workstation
- Runs `make.ps1` / `clean.ps1` (and uses `globals.ps1`)
- GitHub Actions
- `test.yml` (validates repo)
- `release.yml` (builds and publishes)
- Inno Setup compiler
- Consumes `installer/patroni.iss`
- Output artifacts
- “Release ZIP” (per README)
- (Possibly) “Installer EXE” (implied by Inno Setup usage)

- `src/*` + `installer/patroni.iss` → Inno Setup → Release artifact
- GitHub Actions release job → GitHub Releases page

**Labeling tips**
- Make it explicit that this repo produces an **installable bundle**, not a running server.

**Goal:** Show what the installer does to the machine.

- “Windows Server / Windows Node”
- Installer artifact (ZIP extraction or Inno Setup EXE)
- `install.ps1`
- Registers services using the `*_service.xml` definitions
- Installs configs `*.yaml`
- Places helper `patronictl.bat`
- Windows Service Control Manager (SCM)
- Receives service registration actions
- `uninstall.ps1` (reverse path)

- Installer → lays down files (configs, service XMLs, scripts)
- `install.ps1` → Windows SCM (create/register/start services)
- `uninstall.ps1` → Windows SCM (stop/remove services) + filesystem cleanup

**Important: show “service wrapper” explicitly**
- “Service Wrapper (configured by XML)” → launches actual process (etcd/patroni/vip)

**Goal:** Represent the actual HA system the packaging enables.

- **etcd service**
- Distributed coordination / DCS
- **patroni service**
- HA controller; talks to etcd; controls PostgreSQL
- **postgresql service/process** (external dependency)
- Managed by Patroni
- **vip service**
- Manages/announces a virtual IP (VIP) for primary routing (implementation details abstracted)

##### Cross-node / cluster components
- Multiple Windows nodes (Node A, Node B, Node C)
- etcd cluster communication between nodes
- Patroni instances communicate via etcd (leader election, state)
- Clients connect to VIP (or primary) to reach current leader PostgreSQL

- Patroni ⇄ etcd (state store, leader election, membership)
- Patroni → PostgreSQL (start/stop/promote/configure; health checks)
- VIP service ← Patroni state (or watches leader state indirectly) → network VIP assignment
- Client applications → VIP → active PostgreSQL primary

**Make the “control plane vs data plane” explicit**
- Control plane: Patroni + etcd + VIP coordination
- Data plane: application traffic to PostgreSQL (preferably through VIP)

##### Architectural patterns to highlight (specific to this project)
- **Infrastructure packaging pattern**: repo produces installer artifacts, not a long-running app.
- **Service-wrapper-based Windows daemons**: `*_service.xml` indicates processes are run as Windows services via a wrapper.
- **HA orchestration**: Patroni + DCS (etcd) + VIP failover routing.
- **Immutable-ish payload**: `src/*.yaml` suggests templated/default configs shipped with installer.

- `make.ps1`, `clean.ps1`, `globals.ps1`
- GitHub Actions: `test.yml`, `release.yml`
- Inno Setup: `installer/patroni.iss`
- Payload: `install.ps1`, `uninstall.ps1`, `patronictl.bat`
- Configs: `etcd.yaml`, `patroni.yaml`, `vip.yaml`
- Service definitions: `etcd_service.xml`, `patroni_service.xml`, `vip_service.xml`

Runtime (conceptual but essential to system truth):
- Windows SCM
- Service Wrapper (driven by XML)
- etcd / Patroni / VIP services
- PostgreSQL (external but required for Patroni’s mission)
- Clients (connect via VIP)

##### Don’t overthink it: “separate into as many components as possible”
For this repo, “detail” means not just “Patroni on Windows”, but explicitly showing:
- the **packaging layer** (PowerShell + Inno Setup + CI)
- the **installation layer** (install/uninstall scripts + service registration)
- the **runtime layer** (Windows services + cluster interactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: Build & Release (Repository -> Artifact)
%% =========================
subgraph "Diagram 1: Build & Release (Repository -> Artifact)"
direction TB

subgraph "Repository (Git)"
direction TB
RepoSrc["Runtime payload (src/*)"]:::repo
RepoISS["Installer definition (Inno Setup .iss)"]:::repo
Docs["Docs (README + setup guide)"]:::docs
end

subgraph "Developer Workstation"
direction TB
Dev["Developer"]:::actor
Make["make.ps1 (Build orchestrator)"]:::build
Clean["clean.ps1 (Cleanup)"]:::build
Globals["globals.ps1 (Shared globals)"]:::build
InnoLocal["Inno Setup Compiler"]:::buildtool
end

subgraph "GitHub (CI/CD)"
direction TB
Dependabot["Dependabot (Dependency updates)"]:::cicd
GHA_Test["GitHub Actions: test.yml"]:::cicd
GHA_Release["GitHub Actions: release.yml"]:::cicd
end

subgraph "Release Outputs"
direction TB
ArtifactZIP[("Release ZIP")]:::artifact
ArtifactEXE[("Installer EXE")]:::artifact
GHReleases["GitHub Releases"]:::external
end

RepoSrc -. "inputs" .-> Make
RepoISS -. "inputs" .-> Make
Globals -. "used_by" .-> Make
Clean -. "cleans" .-> RepoSrc

Make -->|"invokes"| InnoLocal
RepoISS -->|"consumed_by"| InnoLocal
RepoSrc -->|"bundled_payload"| InnoLocal
InnoLocal -->|"produces"| ArtifactEXE
InnoLocal -->|"packages"| ArtifactZIP

RepoSrc -. "checked_by" .-> GHA_Test
RepoISS -. "checked_by" .-> GHA_Test
GHA_Test -->|"gates"| GHA_Release
GHA_Release -->|"builds"| ArtifactZIP
GHA_Release -->|"builds"| ArtifactEXE
GHA_Release -->|"publishes"| GHReleases
Dependabot -. "PR_updates" .-> RepoSrc
end

%% =========================
%% Diagram 2: Install-time (On a Windows node)
%% =========================
subgraph "Diagram 2: Install-time Architecture (Windows Node)"
direction TB

subgraph "Installer Artifact"
direction TB
InstallerEXE["Installer EXE / ZIP bundle"]:::artifact
end

subgraph "Windows Server / Node"
direction TB

subgraph "Installed Payload (from src/)"
direction TB
SrcRoot["Installed payload root (src/)"]:::repo
InstallPS["install.ps1"]:::install
UninstallPS["uninstall.ps1"]:::install
CtlBAT["patronictl.bat (CLI helper)"]:::install

CfgPatroni["patroni.yaml"]:::config
CfgEtcd["etcd.yaml"]:::config
CfgVIP["vip.yaml"]:::config

SvcXmlPatroni["patroni_service.xml"]:::config
SvcXmlEtcd["etcd_service.xml"]:::config
SvcXmlVIP["vip_service.xml"]:::config
end

SCM["Windows Service Control Manager (SCM)"]:::windows
Wrapper["Service Wrapper (configured by XML)"]:::runtime
end

InstallerEXE -. "lays_down_files" .-> SrcRoot
SrcRoot -. "contains" .-> InstallPS
SrcRoot -. "contains" .-> UninstallPS
SrcRoot -. "contains" .-> CtlBAT
SrcRoot -. "contains" .-> CfgPatroni
SrcRoot -. "contains" .-> CfgEtcd
SrcRoot -. "contains" .-> CfgVIP
SrcRoot -. "contains" .-> SvcXmlPatroni
SrcRoot -. "contains" .-> SvcXmlEtcd
SrcRoot -. "contains" .-> SvcXmlVIP

InstallPS -->|"service_registration+start"| SCM
UninstallPS -->|"stop+remove_services"| SCM
UninstallPS -. "cleanup_files" .-> SrcRoot

SvcXmlPatroni -. "configures" .-> Wrapper
SvcXmlEtcd -. "configures" .-> Wrapper
SvcXmlVIP -. "configures" .-> Wrapper
SCM -->|"runs_as_services"| Wrapper
end

%% =========================
%% Diagram 3: Runtime / Cluster Topology
%% =========================
subgraph "Diagram 3: Runtime / Cluster Topology (Control plane vs Data plane)"
direction TB

subgraph "Control Plane (HA coordination)"
direction TB

subgraph "Windows Node A"
direction TB
SCM_A["Windows SCM"]:::windows
Wrap_A["Service Wrapper"]:::runtime
Etcd_A[("etcd service")]:::runtime
Patroni_A["patroni service"]:::runtime
VIP_A["vip service"]:::runtime
PG_A["PostgreSQL (external dependency)"]:::external

SCM_A -->|"manages"| Wrap_A
Wrap_A -->|"launches"| Etcd_A
Wrap_A -->|"launches"| Patroni_A
Wrap_A -->|"launches"| VIP_A
Patroni_A -->|"controls(start/stop/promote)"| PG_A
end

subgraph "Windows Node B"
direction TB
SCM_B["Windows SCM"]:::windows
Wrap_B["Service Wrapper"]:::runtime
Etcd_B[("etcd service")]:::runtime
Patroni_B["patroni service"]:::runtime
VIP_B["vip service"]:::runtime
PG_B["PostgreSQL (external dependency)"]:::external

SCM_B -->|"manages"| Wrap_B
Wrap_B -->|"launches"| Etcd_B
Wrap_B -->|"launches"| Patroni_B
Wrap_B -->|"launches"| VIP_B
Patroni_B -->|"controls(start/stop/promote)"| PG_B
end

subgraph "Windows Node C"
direction TB
SCM_C["Windows SCM"]:::windows
Wrap_C["Service Wrapper"]:::runtime
Etcd_C[("etcd service")]:::runtime
Patroni_C["patroni service"]:::runtime
VIP_C["vip service"]:::runtime
PG_C["PostgreSQL (external dependency)"]:::external

SCM_C -->|"manages"| Wrap_C
Wrap_C -->|"launches"| Etcd_C
Wrap_C -->|"launches"| Patroni_C
Wrap_C -->|"launches"| VIP_C
Patroni_C -->|"controls(start/stop/promote)"| PG_C
end

Etcd_A <-->|"etcd_cluster_comm"| Etcd_B
Etcd_B <-->|"etcd_cluster_comm"| Etcd_C

Patroni_A <-->|"DCS_coordination"| Etcd_A
Patroni_B <-->|"DCS_coordination"| Etcd_B
Patroni_C <-->|"DCS_coordination"| Etcd_C

VIP_A -. "watches_leader_state" .-> Patroni_A
VIP_B -. "watches_leader_state" .-> Patroni_B
VIP_C -. "watches_leader_state" .-> Patroni_C

VIP_A <-->|"VIP_failover_coordination"| VIP_B
VIP_B <-->|"VIP_failover_coordination"| VIP_C
end

subgraph "Data Plane (Application traffic)"
direction TB
Clients["Client Applications"]:::external
VIPNet["Virtual IP (VIP)"]:::external
PrimaryPG["Active PostgreSQL Primary (one node)"]:::external

Clients -->|"SQL_traffic"| VIPNet
VIPNet -->|"routes_to_primary"| PrimaryPG
end

Patroni_A -. "elects_primary_via_DCS" .-> PrimaryPG
Patroni_B -. "elects_primary_via_DCS" .-> PrimaryPG
Patroni_C -. "elects_primary_via_DCS" .-> PrimaryPG
end

%% =========================
%% Click events (from component_mapping)
%% =========================
click GHA_Test "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/.github/workflows/test.yml"
click GHA_Release "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/.github/workflows/release.yml"
click Dependabot "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/.github/dependabot.yml"
click Make "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/make.ps1"
click Clean "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/clean.ps1"
click Globals "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/globals.ps1"
click RepoISS "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/installer/patroni.iss"
click RepoSrc "https://github.com/cybertec-postgresql/patroni-windows-packaging/tree/master/src/"
click SrcRoot "https://github.com/cybertec-postgresql/patroni-windows-packaging/tree/master/src/"
click InstallPS "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/install.ps1"
click UninstallPS "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/uninstall.ps1"
click CtlBAT "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/patronictl.bat"
click CfgPatroni "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/patroni.yaml"
click CfgEtcd "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/etcd.yaml"
click CfgVIP "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/vip.yaml"
click SvcXmlPatroni "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/patroni_service.xml"
click SvcXmlEtcd "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/etcd_service.xml"
click SvcXmlVIP "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/src/vip_service.xml"
click Docs "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/README.md"
click Docs "https://github.com/cybertec-postgresql/patroni-windows-packaging/blob/master/doc/setup.md"

%% =========================
%% Styles
%% =========================
classDef repo fill:#E3F2FD,stroke:#1E88E5,stroke-width:1px,color:#0D47A1
classDef cicd fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
classDef build fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#E65100
classDef buildtool fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px,color:#BF360C
classDef artifact fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C
classDef install fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#7A5C00
classDef config fill:#E0F7FA,stroke:#00838F,stroke-width:1px,color:#004D40
classDef runtime fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#B71C1C
classDef windows fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238
classDef external fill:#EEEEEE,stroke:#616161,stroke-width:1px,color:#212121,stroke-dasharray: 3 3
classDef docs fill:#F5F5F5,stroke:#757575,stroke-width:1px,color:#424242
classDef actor fill:#EDE7F6,stroke:#5E35B1,stroke-width:1px,color:#311B92
```
