# sako-ranj/psycopg3-python architecture

> Architecture diagram of the GitHub repository sako-ranj/psycopg3-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sako-ranj/psycopg3-python
- Repository: https://github.com/sako-ranj/psycopg3-python

## Overview

##### Project type and purpose
- This is a lightweight, command-line image database manager written in Python.
- It provides two main modes: “insert” (read images from a local folder, process them, then store them in PostgreSQL) and “display” (fetch binary image data from the database and render or save it).

##### File structure
- Top-level files:
- config.py – holds database credentials and the path to the image directory
- db_operations.py – encapsulates all PostgreSQL interactions using psycopg3 and asyncio
- image_operations.py – uses PIL to load and transform images to/from binary form
- main.py – the CLI entry point that parses the “insert” or “display” command and orchestrates operations
- requirements.txt – lists asyncio, psycopg3, PIL
- README.md – explains setup and usage

##### Extract architectural hints from the README
- Two clear use cases: insert all images vs. display all images.
- Dependencies: Python 3.7+, PostgreSQL, PIL, psycopg3 (async).
- No web server or UI—pure CLI.

##### Main components and their interactions
a. Components
- CLI Layer (main.py)
- Configuration Module (config.py)
- Image Service (image_operations.py)
- Database Service (db_operations.py)
- File System (local image directory)
- PostgreSQL Database
b. Interactions
1. User invokes “python main.py insert” or “display” → CLI Layer
2. CLI loads config.py → reads DATABASE_CONFIG + IMAGE_PATH
3. For “insert”:
- Image Service scans IMAGE_PATH, uses PIL to read each image and convert to bytes.
- Database Service receives image bytes + metadata → opens async connection → issues INSERT commands.
4. For “display”:
- Database Service queries the images table → returns binary blobs.
- Image Service takes each blob, uses PIL to recreate image files or display inline.
5. All DB calls use psycopg3’s async API, ensuring non-blocking I/O.

##### Architectural patterns and design principles
- Layered Architecture: Separate CLI, service logic (image & DB), configuration, and external resources (filesystem & DB).
- Single Responsibility:
- config.py only holds settings
- image_operations.py only handles image I/O and conversions
- db_operations.py only handles database CRUD
- Asynchronous I/O: Uses asyncio + psycopg3 for scalable DB operations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        main["main.py (CLI)"]:::orchestration
        config["config.py (Settings)"]:::orchestration
        image["image_operations.py (PIL service)"]:::logic
        dbs["db_operations.py (async psycopg3)"]:::logic
        requirements["requirements.txt"]:::docs
        readme["README.md"]:::docs
    end

    %% External Resources
    subgraph "External Resources"
        fs["Image Directory"]:::external
        db["PostgreSQL Database"]:::external
    end

    %% Insert Flow
    main -->|"insert command"| config
    main -->|"insert command"| image
    image -->|"scan & read images"| fs
    image -->|"image bytes + metadata"| dbs
    dbs -->|"INSERT image_blob"| db

    %% Display Flow
    main -->|"display command"| dbs
    dbs -->|"SELECT image_blob"| db
    db -->|"binary blobs"| dbs
    dbs -->|"recreate images"| image
    image -->|"render/display"| main

    %% Click Events
    click main "https://github.com/sako-ranj/psycopg3-python/blob/main/main.py"
    click config "https://github.com/sako-ranj/psycopg3-python/blob/main/config.py"
    click image "https://github.com/sako-ranj/psycopg3-python/blob/main/image_operations.py"
    click dbs "https://github.com/sako-ranj/psycopg3-python/blob/main/db_operations.py"
    click requirements "https://github.com/sako-ranj/psycopg3-python/blob/main/requirements.txt"
    click readme "https://github.com/sako-ranj/psycopg3-python/blob/main/README.md"

    %% Styles
    classDef orchestration fill:#AED6F1,stroke:#1F618D,color:#1B4F72;
    classDef logic fill:#ABEBC6,stroke:#229954,color:#1D8348;
    classDef external fill:#F5CBA7,stroke:#BA4A00,color:#922B21;
    classDef docs fill:#F2F3F4,stroke:#CACFD2,color:#566573;
```
