# pgr0ss/pgledger architecture

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

- Interactive diagram: https://gitdiagram.com/pgr0ss/pgledger
- Repository: https://github.com/pgr0ss/pgledger

## Overview

##### Project Type and Purpose
- The README makes it clear that this is a ledger implementation in PostgreSQL—a utility for managing account balances and tracking transfers.
- The focus is on SQL procedures and ledger entries, with a single SQL file containing the core functionality.
- Supplementary Go tests (found under the “go” directory) provide benchmarking and testing facilities. Docker and GitHub actions (CI/CD definitions) further support deployment and automated testing.

##### File Structure
- Top-Level Files/Directories:
- .github – Contains configuration for Dependabot and GitHub workflows (e.g., run-tests.yml), which indicates continuous integration and automated testing.
- docker-compose.yml – Likely used to run the PostgreSQL database (and possibly associated services) in a containerized environment.
- go/ – Holds Go modules, tests (benchmark_test.go, db_test.go, etc.) that are used to verify or benchmark the ledger system’s behavior and performance. The go.mod and go.sum files indicate dependency management.
- pgledger.sql – The core SQL script that implements the ledger functionality.
- Other files (justfile, LICENSE, .gitignore) support development automation, licensing, and version control.

##### Main Components
a. PostgreSQL Database:
- The central component where ledger tables, accounts, transfers, and entries reside.
- Tables such as pgledger_entries, and internal versions for future migration/versioning based on the README’s TODOs.
b. SQL Ledger Implementation (pgledger.sql):
- As the “Core Ledger Logic” component that defines functions to create accounts, record transfers, retrieve balances, and query ledger entries.
c. Go Testing & Benchmarking Services:
- As an “Application Testing Layer” that interacts with the PostgreSQL database to validate functionality and monitor performance.
d. CI/CD Pipeline:
e. Deployment/Containerization:

##### Relationships and Interactions
- That the CI/CD pipeline automatically runs these tests upon commits (as defined in GitHub workflows).
- That the docker-compose file is utilized to deploy/run the PostgreSQL container, which is the runtime environment for executing the ledger operations.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project is designed with a clear separation between the database layer (SQL ledger) and its external testing/validation (Go-based tests and performance checks).
- Single Responsibility: The SQL file focuses solely on ledger functionality while Go is leveraged to provide test harnesses.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD & Deployment Layer
    A["CI/CD Pipeline (GitHub Actions & Dependabot)"]:::cicd
    B["Infrastructure Containerization (Docker Compose)"]:::infra
    A -->|"triggers"| B

    %% Testing & Benchmarking Layer
    C["Go Testing & Benchmarking (Go)"]:::go

    %% Database Layer
    D["Core SQL Ledger Implementation (pgledger.sql)"]:::sql
    E["PostgreSQL Database (Ledger Tables & Functions)"]:::db
    D -->|"creates"| E

    %% Interactions between layers
    A -->|"triggers_tests"| C
    C -->|"executes_ledger_ops"| D
    C -->|"queries_validates"| E

    %% Click Events
    click A "https://github.com/pgr0ss/pgledger/tree/main/.github/"
    click B "https://github.com/pgr0ss/pgledger/blob/main/docker-compose.yml"
    click C "https://github.com/pgr0ss/pgledger/tree/main/go/"
    click D "https://github.com/pgr0ss/pgledger/blob/main/pgledger.sql"
    click E "https://github.com/pgr0ss/pgledger/blob/main/pgledger.sql"

    %% Class Definitions for Styling
    classDef cicd fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef infra fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef go fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef sql fill:#90caf9,stroke:#333,stroke-width:2px;
    classDef db fill:#a18cd1,stroke:#333,stroke-width:2px;
```
