# elct9620/pdf64 architecture

> Architecture diagram of the GitHub repository elct9620/pdf64, 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/elct9620/pdf64
- Repository: https://github.com/elct9620/pdf64

## Overview

##### Project Overview and Purpose
- PDF64 is a command-line/server tool (with a Docker container option) that exposes a RESTful API to convert PDF files into Base64 encoded images.
- It supports options like adjusting image density/quality, merges pages, and handles password-protected PDFs. It leverages external tools (ImageMagick, QPDF, and Ghostscript) to perform these conversions.

##### Key Components
a. Client Layer:
- External clients (e.g., web applications or curl commands as shown in the README) that make HTTP requests to the API.
b. API/HTTP Server:
- The main entry point found in cmd/main.go that launches the HTTP server.
- RESTful API endpoints, particularly under /v1/convert (as implemented by the controllers).
c. Application Layer:
- Under the internal/app directory (e.g., http.go) which likely sets up the HTTP handling/middleware.
d. Controller Layer:
- Under internal/controller/v1, with files like convert.go and service.go. These handle the request routing, parameter validation, and delegation of operations.
e. Use Case / Business Logic Layer:
- Under internal/usecase (with builder.go, convert.go, service.go) which defines the orchestration and flow for file conversion.
f. Service Layer:
- Found in internal/service, including:
- imagemagick_convert_service (for converting PDFs with ImageMagick)
- qpdf_decrypt_service (for handling password-protected PDFs using QPDF)
g. Domain/Entity Layer:
- Located in internal/entity (defining file-related data structures) that might be used across different layers.
h. Builder/Utility Functions:
- In internal/builder for file handling/building logic as part of the conversion process.
i. API Schemas:
- In pkg/apis/v1, showing the API definitions (e.g., request/response models, error handling).
j. External Tools:
- Components representing the integration with ImageMagick, Ghostscript, and QPDF might be drawn as external services/tools that the service layer calls.

##### Relationships and Interactions
- The Client sends an HTTP POST to the API server (cmd/main) which is set up by the Application layer.
- The API server invokes the Controller layer (internal/controller/v1) to parse and route the conversion requests.
- Controllers then call upon the Use Case layer (internal/usecase) which organizes the business logic and orchestrates the conversion workflow.
- Based on inputs (such as density, quality, merge flag, password), the Use Case layer interacts with the appropriate Service layer:
- The imagemagick_convert_service is invoked to process standard conversions.
- The qpdf_decrypt_service is used for password-protected PDFs.
- The Builder module (internal/builder) works alongside to prepare files for conversion or to compile final images.
- Throughout, the system likely relies on the predefined data models and API schemas from pkg/apis for standardizing request/response formats.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project design cleanly divides responsibilities among different layers (HTTP/API, Controllers, Use Cases, Services, Entities).
- Separation of Concerns: Each directory (controller, service, usecase, builder) handles distinct aspects of the conversion process.
- Modularity: The project’s internal organization (with separate directories for handling PDF conversion and decryption) showcases modularity and ease of testing (as evident by the accompanying test files).
- Containerization: The presence of a Dockerfile emphasizes deployment within containers, which may also be shown as part of the deployment architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        cl["External Clients"]
    end

    %% HTTP/API Server Layer
    subgraph "HTTP/API Server"
        s1["Main"]
        s2["HTTP Handler"]
    end

    %% Controller Layer
    subgraph "Controller Layer"
        c1["Controllers"]
    end

    %% Use Case Layer
    subgraph "Use Case Layer"
        u1["Use Case"]
    end

    %% Service Layer
    subgraph "Service Layer"
        sv1["Imagemagick Service"]
        sv2["QPDF Service"]
    end

    %% Builder/Utility Layer
    subgraph "Builder/Utility Layer"
        b1["Builder/Utility"]
    end

    %% Domain/Entity Layer
    subgraph "Domain/Entity Layer"
        e1["Domain Entities"]
    end

    %% API Schemas
    subgraph "API Schemas"
        a1["API Schemas"]
    end

    %% External Tools
    subgraph "External Tools"
        ex1["ImageMagick"]
        ex2["Ghostscript"]
        ex3["QPDF"]
    end

    %% Docker Containerization
    d1["Docker"]

    %% Connections
    cl -->|"HTTP POST"| s1
    s1 -->|"launches"| s2
    s2 -->|"routes"| c1
    c1 -->|"validates"| u1
    u1 -->|"invokes"| sv1
    u1 -->|"handles"| sv2
    sv1 -->|"prepares"| b1
    sv2 -->|"prepares"| b1
    b1 -->|"builds"| e1
    s2 -->|"uses"| a1
    cl -->|"formats"| a1
    sv1 -->|"calls"| ex1
    sv1 -->|"calls"| ex2
    sv2 -->|"calls"| ex3
    s1 -.->|"containerized"| d1

    %% Click Events
    click s1 "https://github.com/elct9620/pdf64/blob/main/cmd/main.go"
    click s2 "https://github.com/elct9620/pdf64/blob/main/internal/app/http.go"
    click c1 "https://github.com/elct9620/pdf64/tree/main/internal/controller/v1"
    click u1 "https://github.com/elct9620/pdf64/tree/main/internal/usecase"
    click sv1 "https://github.com/elct9620/pdf64/blob/main/internal/service/imagemagick_convert_service.go"
    click sv2 "https://github.com/elct9620/pdf64/blob/main/internal/service/qpdf_decrypt_service.go"
    click b1 "https://github.com/elct9620/pdf64/blob/main/internal/builder/file.go"
    click e1 "https://github.com/elct9620/pdf64/blob/main/internal/entity/file.go"
    click a1 "https://github.com/elct9620/pdf64/tree/main/pkg/apis/v1"
    click d1 "https://github.com/elct9620/pdf64/tree/main/Dockerfile"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef controller fill:#ccf,stroke:#333,stroke-width:2px;
    classDef usecase fill:#cfc,stroke:#333,stroke-width:2px;
    classDef service fill:#fcf,stroke:#333,stroke-width:2px;
    classDef builder fill:#cff,stroke:#333,stroke-width:2px;
    classDef entity fill:#ff9,stroke:#333,stroke-width:2px;
    classDef schema fill:#f99,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px;
    classDef container fill:#efe,stroke:#333,stroke-width:2px;

    class cl client;
    class s1,s2 server;
    class c1 controller;
    class u1 usecase;
    class sv1,sv2 service;
    class b1 builder;
    class e1 entity;
    class a1 schema;
    class ex1,ex2,ex3 external;
    class d1 container;
```
