# pgedge/lolor architecture

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

- Interactive diagram: https://gitdiagram.com/pgedge/lolor
- Repository: https://github.com/pgedge/lolor

## Overview

##### Project type and purpose
- This is a PostgreSQL extension (“lolor”) written in C using PGXS.
- Purpose: override Postgres’s native large-object API (lo_*) so that large objects are stored in user-managed tables (lolor.pg_largeobject and lolor.pg_largeobject_metadata) and can be logically replicated via pgedge/spock.

##### File structure
- Top-level build artifacts and config:
- Makefile (PGXS build)
- .github/workflows/*.yml (CI pipelines)
- docker/ (Dockerfiles, compose, entrypoint, scripts to spin up Postgres clusters for testing)
- src/ (C source: lolor.c, API stubs, large-object management)
- tests/ multi-language test suites:
- tests/go (Go client tests)
- tests/javascript (Node.js tests)
- tests/junit (Java JUnit tests for single- and multi-node replication)
- tests/python (Python client tests)
- SQL/control files: lolor–1.0.sql, lolor.control (Postgres extension metadata)

##### README for additional insights
- Describes extension installation (pgEdge CLI or PGXS), configuration (lolor.node, search_path), function overrides, and replication-set integration via pgedge spock.
- Shows example calls to lo_creat, lo_import, lo_unlink, and queries against lolor schema tables.

##### Elements
- from Build → Postgres (install)
- from Test Clients → Postgres (API calls)
- from Postgres primary → Replication Engine → Postgres replica
- from CI → Docker Compose (orchestrator)
- Blue for build/CI artifacts
- Green for runtime DB components
- Orange for client/test harnesses
- Purple for replication subsystem

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & CI Subsystem
    subgraph "Build & CI Subsystem"
        A1["Makefile"]:::buildCI
        A2["GitHub Actions Workflows"]:::buildCI
        A3["Docker Compose"]:::buildCI
        A4["Entrypoint & Helper Scripts"]:::buildCI
    end

    %% Extension Module
    subgraph "Extension Module (C/PGXS)" 
        B1["src/lolor.c"]:::extension
        B2["src/lolor.h"]:::extension
        B3["src/lolor_inv_api.c"]:::extension
        B4["src/lolor_fsstubs.c"]:::extension
        B5["src/lolor_largeobject.c"]:::extension
        B6["lolor--1.0.sql"]:::extension
        B7["lolor.control"]:::extension
    end

    %% Runtime DB Cluster
    subgraph "Runtime DB Cluster"
        C1["PostgreSQL Server"]:::runtime
        C2["lolor.pg_largeobject"]:::runtime
        C3["lolor.pg_largeobject_metadata"]:::runtime
        C4["Overridden lo_* Functions"]:::runtime
    end

    %% Logical Replication Engine
    subgraph "Logical Replication Engine (pgedge/spock)"
        D1["pgedge.env"]:::replication
        D2["Replication Scripts"]:::replication
        D3["Test Properties for Replication"]:::replication
    end

    %% Test Clients
    subgraph "Client Test Suites"
        E1["Go Tests"]:::client
        E2["JavaScript Tests"]:::client
        E3["Java JUnit Single-Node"]:::client
        E4["Java JUnit Multi-Node"]:::client
        E5["Python Tests"]:::client
    end

    %% Connections
    A2 -->|"triggers build"| A3
    A3 -->|"orchestrates containers"| C1
    A1 -->|"compiles extension"| B1
    A1 --> B2
    A1 --> B3
    A1 --> B4
    A1 --> B5
    A1 --> B6
    A1 --> B7
    B1 -->|"PGXS build produces lolor.so"| C1
    C1 -->|"lo_* calls"| C2
    C1 --> C3
    C1 --> C4
    C1 -->|"WAL replication"| D2
    D2 -->|"applies WAL"| C1
    E1 -->|"libpq calls lo_*"| C1
    E2 -->|"driver calls lo_*"| C1
    E3 -->|"JDBC calls lo_*"| C1
    E4 -->|"JDBC calls lo_*"| C1
    E5 -->|"psycopg2 calls lo_*"| C1

    %% Click Events
    click A1 "https://github.com/pgedge/lolor/tree/main/./Makefile"
    click A2 "https://github.com/pgedge/lolor/blob/main/.github/workflows/workflow.yml"
    click A2 "https://github.com/pgedge/lolor/blob/main/.github/workflows/regression_tests.yml"
    click A3 "https://github.com/pgedge/lolor/blob/main/./docker/docker-compose.yml"
    click A4 "https://github.com/pgedge/lolor/blob/main/./docker/entrypoint.sh"
    click A4 "https://github.com/pgedge/lolor/blob/main/./docker/run-tests.sh"
    click A4 "https://github.com/pgedge/lolor/blob/main/./docker/check-outputs.sh"
    click B1 "https://github.com/pgedge/lolor/blob/main/./src/lolor.c"
    click B2 "https://github.com/pgedge/lolor/blob/main/./src/lolor.h"
    click B3 "https://github.com/pgedge/lolor/blob/main/./src/lolor_inv_api.c"
    click B4 "https://github.com/pgedge/lolor/blob/main/./src/lolor_fsstubs.c"
    click B5 "https://github.com/pgedge/lolor/blob/main/./src/lolor_largeobject.c"
    click B6 "https://github.com/pgedge/lolor/blob/main/./lolor--1.0.sql"
    click B7 "https://github.com/pgedge/lolor/blob/main/./lolor.control"
    click C1 "https://github.com/pgedge/lolor/blob/main/./docker/docker-compose.yml"
    click D1 "https://github.com/pgedge/lolor/blob/main/./docker/pgedge.env"
    click D2 "https://github.com/pgedge/lolor/blob/main/./docker/entrypoint.sh"
    click D3 "https://github.com/pgedge/lolor/blob/main/./docker/test-configs/test.properties.go"
    click D3 "https://github.com/pgedge/lolor/blob/main/./docker/test-configs/test.properties.java"
    click D3 "https://github.com/pgedge/lolor/blob/main/./docker/test-configs/test.properties.java-single"
    click D3 "https://github.com/pgedge/lolor/blob/main/./docker/test-configs/test.properties.py"
    click E1 "https://github.com/pgedge/lolor/blob/main/./tests/go/go.mod"
    click E1 "https://github.com/pgedge/lolor/blob/main/./tests/go/main_test.go"
    click E1 "https://github.com/pgedge/lolor/blob/main/./tests/go/test.properties"
    click E2 "https://github.com/pgedge/lolor/blob/main/./tests/javascript/package.json"
    click E2 "https://github.com/pgedge/lolor/blob/main/./tests/javascript/lo_methods.js"
    click E2 "https://github.com/pgedge/lolor/blob/main/./tests/javascript/lo_methods.test.js"
    click E2 "https://github.com/pgedge/lolor/blob/main/./tests/javascript/config.json"
    click E3 "https://github.com/pgedge/lolor/blob/main/./tests/junit/singlenode/pom.xml"
    click E3 "https://github.com/pgedge/lolor/blob/main/./tests/junit/singlenode/src/test/java/com/pgedge/lolor/*.java"
    click E3 "https://github.com/pgedge/lolor/tree/main/./tests/junit/singlenode/data"
    click E3 "https://github.com/pgedge/lolor/tree/main/./tests/junit/singlenode/expected"
    click E4 "https://github.com/pgedge/lolor/blob/main/./tests/junit/multinode/pom.xml"
    click E4 "https://github.com/pgedge/lolor/blob/main/./tests/junit/multinode/src/test/java/com/pgedge/lolor/*.java"
    click E4 "https://github.com/pgedge/lolor/tree/main/./tests/junit/multinode/data"
    click E4 "https://github.com/pgedge/lolor/tree/main/./tests/junit/multinode/expected"
    click E5 "https://github.com/pgedge/lolor/blob/main/./tests/python/lolor_tests.py"
    click E5 "https://github.com/pgedge/lolor/blob/main/./tests/python/test.properties"

    %% Styles
    classDef buildCI fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef extension fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef runtime fill:#E3F2FD,stroke:#1565C0,color:#1565C0;
    classDef replication fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef client fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00;
```
