# siteworxpro/img-proxy-url-generator architecture

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

- Interactive diagram: https://gitdiagram.com/siteworxpro/img-proxy-url-generator
- Repository: https://github.com/siteworxpro/img-proxy-url-generator

## Overview

##### Main Components
- CLI / Command Runner: The entry point (main.go) dispatches various commands found in the “commands” directory. These include “decrypt”, “generate”, “grpc”, “report”, and “server”. This component will handle user input (command-line arguments) and coordinate with the proper module.
- URL Generator Core: Under the “generator” directory, this is where the core logic for encoding URLs (base64, encryption, plain formatting, signature generation) resides.
- Configuration Loader: The “config” directory houses code to load settings (such as img-proxy keys, salts, host, encryption settings, and plain URL flag) from an INI-like config file.
- Web/API Server: The “commands/server.go” file (and associated logic) starts a web service that can accept HTTP requests (as illustrated by the curl example) and produce generated URLs.
- gRPC Interface: The “grpc” folder contains protocol buffer definitions and server implementations which allow external systems (or even the PHP client portion in grpc/php) to interact with the URL generation functionality via gRPC.
- AWS & Redis Integration: The “aws” and “redis” directories indicate that the system optionally supports interactions with S3 (for example, using s3:// paths) and Redis (likely used for caching or key/value storage).
- Reporting & Logging: The “report” command and “printer” module (log and style utilities) are used for reporting and diagnostics. Additionally, the “templates” directory (containing index.gohtml) may generate output pages for web responses.
- CI/CD and Deployment: Supporting files like the Dockerfile, Taskfile.yaml, GitHub workflows, and other configuration files indicate deployment and continuous integration pipelines.

##### Relationships and Interactions
- The user initiates actions via the CLI or HTTP API.
- The central “main.go” delegates to the appropriate command (generate, decrypt, report, or server).
- Each command reads the configuration (via modules in “config”) to set up environment variables and security parameters (keys, salts, etc.).
- When generating a URL, the “generator” module is invoked. Depending on the configuration and command-line parameters, it performs one of:
- Plain encoding (possibly without signing),
- Generating an HMAC signature,
- Encrypting the URL.
- Web/API or gRPC endpoints then serve as input interfaces that call into the same core generator logic.
- Optional integrations: If AWS S3 or Redis-related functionality is triggered via specific commands or parameters, the corresponding “aws” and “redis” modules are used.
- Logging (via “printer”) and report generation (via “report”) provide feedback and diagnostics, and CI/CD pipelines (in .github) ensure that tests (see “.github/workflows/tests.yml”) and builds occur seamlessly.

##### Architectural Patterns / Design Principles
- Separation of Concerns: Each directory plays a specific role (configuration, generation, interface, logging), making debugging and testing easier.
- Modular Design: The command-based modules let you easily add more functionality (such as new URL transformation techniques or interfaces).
- Multi-Interface Exposure: The same core generation logic is reused across CLI commands, a web server, and gRPC, ensuring consistency across different access methods.

##### Final Recommendation
- Don’t overcomplicate—break the system into as many well-defined components as possible, and then illustrate how they interact.
- Every user input (command-line argument or HTTP/GRPC request) is routed through a configuration and then to the generator engine.
- Error handling via logging (printer/log.go) and any feedback or reporting modules.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Input Layer
    subgraph "CLI / Command Runner"
        CLI_Main["main.go"]:::cli
        CLI_Decrypt["commands/decrypt.go"]:::cli
        CLI_Generate["commands/generate.go"]:::cli
        CLI_GRPC["commands/grpc.go"]:::cli
        CLI_Report["commands/report.go"]:::cli
        CLI_Server["commands/server.go"]:::cli
    end

    subgraph "Web/API Server"
        Web_Server["commands/server.go"]:::web
        Web_Template["templates/index.gohtml"]:::web
    end

    subgraph "gRPC Interface"
        GRPC_Proto["grpc/imgurl.proto"]:::grpc
        GRPC_PB["grpc/imgurl.pb.go"]:::grpc
        GRPC_GrpcPB["grpc/imgurl_grpc.pb.go"]:::grpc
        GRPC_Server["grpc/server.go"]:::grpc
        GRPC_PHP["grpc/php/"]:::grpc
    end

    %% Central Configuration and Core Engine
    subgraph "Configuration Loader"
        Conf_Config["config/config.go"]:::config
        Conf_AWS["config/aws.go"]:::config
        Conf_Generator["config/generator.go"]:::config
        Conf_Redis["config/redis.go"]:::config
    end

    subgraph "URL Generator Core"
        Gen_Base64["generator/base64.go"]:::generator
        Gen_Crypt["generator/crypt.go"]:::generator
        Gen_Format["generator/format.go"]:::generator
        Gen_Plain["generator/plain.go"]:::generator
        Gen_Signature["generator/signature.go"]:::generator
        Gen_URL["generator/url.go"]:::generator
    end

    %% Optional Integrations
    subgraph "AWS Integration"
        AWS_Client["aws/client.go"]:::aws
        AWS_S3["aws/s3.go"]:::aws
    end

    subgraph "Redis Integration"
        Redis_Client["redis/client.go"]:::redis
    end

    %% Reporting & Logging
    subgraph "Reporting & Logging"
        Report_Command["report/command.go"]:::report
        Printer_Log["printer/log.go"]:::report
        Printer_Printer["printer/printer.go"]:::report
        Printer_Styles["printer/styles.go"]:::report
    end

    %% Generated Output
    Generated_URL["Generated URL"]:::output
    ImgProxy["img-proxy Server"]:::external

    %% CI/CD and Deployment (auxiliary)
    subgraph "CI/CD & Deployment"
        CICD_Docker["Dockerfile"]:::cicd
        CICD_Task["Taskfile.yaml"]:::cicd
        CICD_Github[".github/workflows/tests.yml"]:::cicd
    end

    %% Data Flow Connections
    %% User inputs triggering configuration load
    CLI_Main -->|"loads config"| Conf_Config
    Web_Server -->|"loads config"| Conf_Config
    GRPC_Server -->|"loads config"| Conf_Config

    %% Configuration Loader to URL Generator Core
    Conf_Config -->|"configures"| Gen_Base64

    %% URL Generator Core drives Reporting
    Gen_URL -->|"generates URL"| Report_Command

    %% Optional Integrations from URL Generator Core
    Gen_URL -.->|"optional"| AWS_Client
    Gen_URL -.->|"optional"| Redis_Client

    %% Reporting to final output
    Report_Command -->|"reports"| Generated_URL
    Generated_URL -->|"used by"| ImgProxy

    %% Styling Classes
    classDef cli fill:#ffe6f2,stroke:#d94d9a,stroke-width:2px;
    classDef web fill:#e6ffea,stroke:#46a347,stroke-width:2px;
    classDef grpc fill:#e6e6ff,stroke:#4d4dd9,stroke-width:2px;
    classDef config fill:#e6f0ff,stroke:#1a75ff,stroke-width:2px;
    classDef generator fill:#fff2e6,stroke:#ff8c1a,stroke-width:2px;
    classDef aws fill:#ffe6e6,stroke:#ff1a1a,stroke-width:2px;
    classDef redis fill:#e6ffe6,stroke:#33cc33,stroke-width:2px;
    classDef report fill:#fff9e6,stroke:#e6ac00,stroke-width:2px;
    classDef output fill:#ffd6d6,stroke:#d94d4d,stroke-width:2px;
    classDef cicd fill:#f2f2f2,stroke:#737373,stroke-width:2px;
    classDef external fill:#e6f9ff,stroke:#1aa3ff,stroke-width:2px;

    %% Click Events for CLI / Command Runner
    click CLI_Main "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/main.go"
    click CLI_Decrypt "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/decrypt.go"
    click CLI_Generate "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/generate.go"
    click CLI_GRPC "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/grpc.go"
    click CLI_Report "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/report.go"
    click CLI_Server "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/server.go"

    %% Click Events for URL Generator Core
    click Gen_Base64 "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/base64.go"
    click Gen_Crypt "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/crypt.go"
    click Gen_Format "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/format.go"
    click Gen_Plain "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/plain.go"
    click Gen_Signature "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/signature.go"
    click Gen_URL "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/generator/url.go"

    %% Click Events for Configuration Loader
    click Conf_Config "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/config/config.go"
    click Conf_AWS "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/config/aws.go"
    click Conf_Generator "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/config/generator.go"
    click Conf_Redis "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/config/redis.go"

    %% Click Events for Web/API Server
    click Web_Server "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/commands/server.go"
    click Web_Template "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/templates/index.gohtml"

    %% Click Events for gRPC Interface
    click GRPC_Proto "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/grpc/imgurl.proto"
    click GRPC_PB "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/grpc/imgurl.pb.go"
    click GRPC_GrpcPB "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/grpc/imgurl_grpc.pb.go"
    click GRPC_Server "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/grpc/server.go"
    click GRPC_PHP "https://github.com/siteworxpro/img-proxy-url-generator/tree/master/grpc/php/"

    %% Click Events for AWS Integration
    click AWS_Client "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/aws/client.go"
    click AWS_S3 "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/aws/s3.go"

    %% Click Events for Redis Integration
    click Redis_Client "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/redis/client.go"

    %% Click Events for Reporting & Logging
    click Report_Command "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/report/command.go"
    click Printer_Log "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/printer/log.go"
    click Printer_Printer "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/printer/printer.go"
    click Printer_Styles "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/printer/styles.go"

    %% Click Events for CI/CD & Deployment
    click CICD_Docker "https://github.com/siteworxpro/img-proxy-url-generator/tree/master/Dockerfile"
    click CICD_Task "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/Taskfile.yaml"
    click CICD_Github "https://github.com/siteworxpro/img-proxy-url-generator/blob/master/.github/workflows/tests.yml"
```
