# jazzcore/python-pdfkit architecture

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

- Interactive diagram: https://gitdiagram.com/jazzcore/python-pdfkit
- Repository: https://github.com/jazzcore/python-pdfkit

## Overview

##### Main Components
- API Interface Layer: Represent the public functions exposed by the library (e.g., from_url, from_file, and from_string) that are defined in modules such as pdfkit/api.py and exposed via pdfkit/__init__.py.
- Core Engine: Include the core processing module (pdfkit/pdfkit.py) and its helper routines that build and execute the wkhtmltopdf command. This is the heart of the library where the conversion logic happens.
- Configuration Module: Illustrate the component in pdfkit/configuration.py which is responsible for handling settings like the path to the wkhtmltopdf binary and meta tag prefixes.
- Source Management: Note the utility module (pdfkit/source.py) which could encapsulate how different sources (HTML strings, files, or URLs) are processed prior to conversion.
- Testing and Examples: Show the tests directory (tests/fixtures and tests/pdfkit-tests.py) that is used to validate different configurations and inputs. This is crucial for understanding how the library works under different conditions.

##### Relationships and Interactions
- Link the Core Engine to the Configuration Module, highlighting that before executing wkhtmltopdf the configuration settings must be applied (e.g. choosing the right wkhtmltopdf binary).
- Role of the Testing Suite by showing that it interacts with various modules to verify successful conversion.
- Optionally, capture how the CI components run tests and enforce quality before changes are integrated.

##### Architectural Patterns and Design
- That the design follows a layered approach:
- The API layer abstracts away external details.
- A core conversion layer handles processing and command execution.
- The configuration module decouples environment-specific details.
- That each module has a single responsibility, which aids in isolating testing and debugging.
- Point out that the library is built to be both simple (in its API surface) and extensible (with configuration options and support for multiple CSS files, meta tags, and more).

##### Relevant Technologies and Libraries
- Python is the core language used.
- wkhtmltopdf is the external utility integrated by the library.
- CI/CD tools using GitHub Actions and shell scripts (ci/before-script.sh) are utilized for testing and building.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD Pipeline"
        CI1("GitHub Actions (.github/workflows/main.yaml)"):::cicd
        CI2("Shell Script (ci/before-script.sh)"):::cicd
    end

    subgraph "Testing Suite"
        Tests1("Test Fixtures (tests/fixtures)"):::testing
        Tests2("PDFKit Tests (tests/pdfkit-tests.py)"):::testing
    end

    subgraph "pdfkit Library"
        subgraph "API Interface Layer"
            API1("pdfkit/__init__.py"):::pythonModule
            API2("pdfkit/api.py"):::pythonModule
        end
        Source("Source Management (pdfkit/source.py)"):::pythonModule
        Core("Core Engine (pdfkit/pdfkit.py)"):::pythonModule
        Config("Configuration Module (pdfkit/configuration.py)"):::pythonModule
    end

    External("wkhtmltopdf binary"):::external

    %% CI/CD triggers Testing
    CI1 -->|"runs_tests"| Tests1
    CI1 -->|"runs_tests"| Tests2
    CI2 -->|"runs_tests"| Tests1
    CI2 -->|"runs_tests"| Tests2

    %% Testing validates pdfkit Library
    Tests2 -->|"validates"| API2
    Tests2 -->|"validates"| Core

    %% API calls
    API2 -->|"processes_input"| Source
    Source -->|"prepares_for"| Core

    %% Core interactions
    Core -->|"applies_settings"| Config
    Core -->|"executes"| External

    %% Direct API call (alternative entry point)
    API1 -->|"exposes_API"| Core

    %% Click Events
    click API1 "https://github.com/jazzcore/python-pdfkit/blob/master/pdfkit/__init__.py"
    click API2 "https://github.com/jazzcore/python-pdfkit/blob/master/pdfkit/api.py"
    click Source "https://github.com/jazzcore/python-pdfkit/blob/master/pdfkit/source.py"
    click Core "https://github.com/jazzcore/python-pdfkit/blob/master/pdfkit/pdfkit.py"
    click Config "https://github.com/jazzcore/python-pdfkit/blob/master/pdfkit/configuration.py"
    click Tests1 "https://github.com/jazzcore/python-pdfkit/tree/master/tests/fixtures"
    click Tests2 "https://github.com/jazzcore/python-pdfkit/blob/master/tests/pdfkit-tests.py"
    click CI1 "https://github.com/jazzcore/python-pdfkit/blob/master/.github/workflows/main.yaml"
    click CI2 "https://github.com/jazzcore/python-pdfkit/blob/master/ci/before-script.sh"

    %% Styles
    classDef pythonModule fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef testing fill:#FFFFE0,stroke:#DAA520,stroke-width:2px;
    classDef cicd fill:#FFEFD5,stroke:#CD853F,stroke-width:2px;
```
