# yuzo-ai/ebay_auto_listing architecture

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

- Interactive diagram: https://gitdiagram.com/yuzo-ai/ebay_auto_listing
- Repository: https://github.com/yuzo-ai/ebay_auto_listing

## Overview

##### Project type and purpose
- This is a Python‐based command-line automation tool (“open-source tool” category) that reads product data from Google Sheets and uses the eBay API to create listings in either sandbox or production environments.

##### File structure
- Top-level scripts:
- main.py (CLI entry point)
- check_*.py and test_*.py (health checks & unit tests)
- Core modules:
- config.py (default listing settings)
- ebay_env.py (environment switcher: sandbox vs. production)
- ebay_lister.py (wrappers around ebaysdk to create listings)
- google_sheets_reader.py / google_sheets_mock.py (fetch data from Sheets API / mock for testing)
- utils.py (helper functions: image download, retry logic, logging)
- Support files:
- .env.example (environment variable template)
- requirements.txt (.env .gitignore etc.)

##### README for additional insights
- Confirms two external dependencies (Google Sheets API & eBay API)
- Describes environment configuration, data column schema, retry & logging features, per-row and bulk processing

a. Main components (group these as modules or services):
1. User (CLI)
2. Config/Env Loader (.env via python-dotenv + config.py)
3. Google Sheets Reader (google_sheets_reader.py)
4. Data Processor (utils.py – image handling, retries, Item Specifics)
5. eBay Lister (ebay_lister.py + ebaysdk)
6. Environment Switcher (ebay_env.py)
7. Logging Subsystem (built-in logging to console & ebay_listing.log)
8. External Services:
- Google Sheets API
- eBay API (Sandbox & Production endpoints)

b. Relationships and interactions:
- CLI loads Config/Env Loader ➔ populates credentials & defaults
- CLI calls Google Sheets Reader ➔ fetches raw rows
- Raw rows ➔ Data Processor ➔ handles images & builds “Item” payload
- Payload ➔ Environment Switcher determines endpoint ➔ eBay Lister ➔ invokes eBay API
- eBay API response ➔ Logging Subsystem ➔ console & log file
- Retry logic in Data Processor / eBay Lister on failures

c. Architectural patterns & design principles:
- Clear separation of concerns: reader / processor / lister
- Environment-based routing (sandbox vs. production) via strategy pattern
- Pluggable mocks for testing (google_sheets_mock.py)
- Single responsibility modules for credentials, I/O, business logic
- Layered flow: Input ➔ Transform ➔ Output

d. Key technologies and libraries:
- Python 3.8+
- python-dotenv (config loader)
- google-api-python-client, google-auth-* (Sheets integration)
- ebaysdk (eBay API)
- requests (image retrieval)
- built-in logging

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User (CLI)"]:::external

    %% Main Entry
    CLI["main.py"]:::internal

    %% Config & Env Loader
    subgraph "Config & Environment Loader"
        ConfigPy["config.py"]:::config
        EnvExample[".env.example"]:::config
    end

    %% Core Pipeline
    Sheets["google_sheets_reader.py"]:::internal
    MockSheets["google_sheets_mock.py"]:::internal
    Processor["utils.py"]:::internal
    EnvSwitch["ebay_env.py"]:::internal
    Lister["ebay_lister.py"]:::internal

    %% External Services
    GSheetsAPI["Google Sheets API"]:::external
    EbayAPI["eBay API\n(Sandbox & Production)"]:::external

    %% Logging Subsystem
    Logging["Logging Subsystem\n(eBay log & console)"]:::logging

    %% Health Checks
    subgraph "Health-Check Scripts"
        checkEbay["check_ebay_creds.py"]:::internal
        checkGoogleCreds["check_google_creds.py"]:::internal
        checkSheets["check_sheets.py"]:::internal
    end

    %% Unit Tests / Mocks
    subgraph "Unit Tests / Mocks"
        testGoogleSheet["test_google_sheets.py"]:::internal
        testImageUpload["test_image_upload.py"]:::internal
        testMainMock["test_main_with_mock.py"]:::internal
        testMockToken["test_with_mock_token.py"]:::internal
    end

    %% Data Flows
    User --> CLI
    CLI --> ConfigPy
    CLI --> EnvExample
    CLI --> Sheets
    Sheets --> GSheetsAPI
    Sheets --> Processor
    Processor --> EnvSwitch
    EnvSwitch --> Lister
    Lister --> EbayAPI
    EbayAPI --> Logging
    Processor --> Logging

    %% Click Events
    click CLI "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/main.py"
    click ConfigPy "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/config.py"
    click EnvExample "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/.env.example"
    click Sheets "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/google_sheets_reader.py"
    click MockSheets "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/google_sheets_mock.py"
    click Processor "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/utils.py"
    click EnvSwitch "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/ebay_env.py"
    click Lister "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/ebay_lister.py"
    click checkEbay "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/check_ebay_creds.py"
    click checkGoogleCreds "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/check_google_creds.py"
    click checkSheets "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/check_sheets.py"
    click testGoogleSheet "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/test_google_sheets.py"
    click testImageUpload "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/test_image_upload.py"
    click testMainMock "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/test_main_with_mock.py"
    click testMockToken "https://github.com/yuzo-ai/ebay_auto_listing/blob/main/test_with_mock_token.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef config fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef logging fill:#FFD700,stroke:#333,stroke-width:1px;
```
