# geocoug/pg-upsert architecture

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

- Interactive diagram: https://gitdiagram.com/geocoug/pg-upsert
- Repository: https://github.com/geocoug/pg-upsert

## Overview

##### Main Components
- Command-Line Interface (CLI): Represented by files like __main__.py and cli.py that provide the entry point and argument parsing for users.
- Core Upsert Engine: Encapsulated in files such as upsert.py, which encapsulate the logic for validating constraints and performing the upsert.
- PostgreSQL Interaction Layer: Modules like postgres.py that abstract the database interactions (executing integrity checks, connecting via a URI or an existing connection, etc.).
- User Interface & Confirmation: The ui.py component handles the interactive prompts and displays change summaries before committing changes.
- Utilities: Additional helper functions in utils.py.
- Configuration & Dependency Management: The project supports both YAML configuration files and command-line parameters. Also mention that pyproject.toml and Dockerfile are present for build and deployment settings.
- Testing Infrastructure: The tests directory contains unit tests and sample schema SQL files which are essential for validating behavior.
- CI/CD & Documentation: Note the .github/workflows (for continuous integration), mkdocs.yml, docs, and README.md which document the project and automate the deployment pipelines.

##### Interactions and Relationships
- The Utilities module provides support across the core components (e.g., logging, parsing etc.) so indicate a shared dependency.
- Surround these core modules with peripheral systems – such as the Docker setup for testing and deployment, and the CI/CD pipelines (referenced in the .github/workflows) – to show how they ensure code quality and deployment readiness.

##### Final Assembly
- In the center, arrange the application’s core modules in a logical order that mirrors the call flow (from CLI/config parsing, to interactive UI, to the upsert engine, then database communication).
- On the right or in a separate section, show integration points such as testing pipelines, CI/CD workflows, documentation (mkdocs and docs), and Docker deployment.
- A small subsection that mentions how configuration management is handled (configuration files vs. command-line arguments).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Subgraph
    subgraph "User Interfaces"
        subgraph "CLI Module"
            CLI_Main["Main (__main__.py)"]:::cli
            CLI_PARSER["CLI Parser (cli.py)"]:::cli
        end
        API["Python API Access"]:::api
    end

    %% Configuration & Dependency Management
    CONFIG["Configuration & Dependency Management"]:::config

    %% Core Operations Subgraph
    subgraph "Core Operations"
        CORE["Upsert Engine (upsert.py)"]:::core
        UI["Interactive UI (ui.py)"]:::core
        DB["Database Connector (postgres.py)"]:::core
    end

    %% External Systems Subgraph
    subgraph "External Systems"
        TEST_DIR["Tests Directory"]:::ext
        TEST_DATA["Test Data (schema SQL)"]:::ext
        CI_CD["CI/CD & Documentation"]:::ext
    end

    %% Connections from User Interfaces to Core
    CLI_Main -->|"parse"| CORE
    CLI_PARSER -->|"parse"| CORE
    API -->|"calls"| CORE

    %% Configuration flows into Core
    CONFIG -->|"overrides"| CORE

    %% Core Upsert interactions
    CORE -->|"execute"| DB
    DB -->|"response"| CORE
    CORE -->|"confirm"| UI
    UI -->|"input"| CORE

    %% Utilities shared dependency (dotted lines)
    CLI_Main --- UTILS
    CLI_PARSER --- UTILS
    CORE --- UTILS
    UI --- UTILS
    DB --- UTILS

    %% External Systems interactions
    TEST_DIR -->|"tests"| CORE
    TEST_DATA -->|"testdata"| CORE
    TEST_DIR --> CI_CD
    TEST_DATA --> CI_CD
    CI_CD -->|"deploys"| CORE

    %% Declare Utilities node separately
    UTILS["Utilities (utils.py)"]:::util

    %% Click Events
    click CLI_Main "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/__main__.py"
    click CLI_PARSER "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/cli.py"
    click CORE "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/upsert.py"
    click DB "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/postgres.py"
    click UI "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/ui.py"
    click UTILS "https://github.com/geocoug/pg-upsert/blob/main/src/pg_upsert/utils.py"
    click CONFIG "https://github.com/geocoug/pg-upsert/blob/main/pyproject.toml"
    click TEST_DIR "https://github.com/geocoug/pg-upsert/tree/main/tests"
    click TEST_DATA "https://github.com/geocoug/pg-upsert/tree/main/tests/data"
    click CI_CD "https://github.com/geocoug/pg-upsert/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef util fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef ext fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
