# gotenberg/gotenberg architecture

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

- Interactive diagram: https://gitdiagram.com/gotenberg/gotenberg
- Repository: https://github.com/gotenberg/gotenberg

## Overview

##### Main Components

a) API Layer
- Entry point for HTTP requests
- Located in pkg/modules/api
- Should be shown as the frontend interface

b) Core Service Modules
As separate components:
- Chromium (HTML/Markdown to PDF conversion)
- LibreOffice (Office documents to PDF conversion)
- PDF Engines (PDF manipulation)
- QPDF
- PDFtk
- PDFcpu
- Exiftool (metadata handling)

c) Supporting Modules
- Webhook module (async operations)
- Prometheus module (metrics)
- Logging module

##### Architecture Pattern
- Modular architecture (evident from pkg/modules structure)
- Stateless nature (as mentioned in README)
- Docker containerization

**[External Clients] → [Docker Container]**

- ↓
- [API Gateway (3000)]

- ↓
- [Request Processing]

- ┌────────┼────────┐
- ↓        ↓        ↓
- [Chromium] [LibreOffice] [PDF Engines]

- ┼────────┘

- ↓
- [File Processing]

- ┌────────┼────────┐
- ↓        ↓        ↓
- [Webhook] [Prometheus] [Logging]

##### Important Details

a) Component Interactions:
- How the API routes requests to appropriate modules
- File processing workflows
- Points where PDF generation occurs

b) Configuration Elements:
- Docker container boundary
- Port exposures (3000)
- Volume mounts for temporary files

c) Monitoring & Observability:
- Prometheus metrics flow
- Logging pathways
- Webhook notification system

##### Technical Specifications

Details in annotations:
- Go-based implementation
- Docker containerization
- PDF processing capabilities
- Supported input formats (HTML, Markdown, Office documents)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Docker["Docker Container"]
        direction TB
        Entry["Main Entry Point"]:::entry
        API["API Gateway (Port 3000)"]:::api
        
        subgraph Core["Core Processing"]
            direction TB
            ReqProc["Request Processing"]:::core
            FileProc["File Processing"]:::core
        end
        
        subgraph Converters["Conversion Engines"]
            direction TB
            Chrome["Chromium"]:::converter
            Libre["LibreOffice"]:::converter
            subgraph PDF["PDF Engines"]
                direction TB
                QPDF["QPDF"]:::pdf
                PDFtk["PDFtk"]:::pdf
                PDFcpu["PDFcpu"]:::pdf
            end
            Exif["Exiftool"]:::converter
        end
        
        subgraph Support["Support Services"]
            direction TB
            Hook["Webhook"]:::support
            Prom["Prometheus"]:::support
            Log["Logging"]:::support
        end
    end
    
    Client["External Clients"]:::external
    
    %% Connections
    Client --> API
    API --> ReqProc
    ReqProc --> Chrome
    ReqProc --> Libre
    ReqProc --> PDF
    ReqProc --> Exif
    Chrome --> FileProc
    Libre --> FileProc
    PDF --> FileProc
    Exif --> FileProc
    FileProc --> Hook
    FileProc --> Prom
    FileProc --> Log
    Entry --> API
    
    %% Styles
    classDef external fill:#f66,stroke:#333,stroke-width:2px
    classDef api fill:#9cf,stroke:#333,stroke-width:2px
    classDef core fill:#fc9,stroke:#333,stroke-width:2px
    classDef converter fill:#9f9,stroke:#333,stroke-width:2px
    classDef pdf fill:#ff9,stroke:#333,stroke-width:2px
    classDef support fill:#f9f,stroke:#333,stroke-width:2px
    classDef entry fill:#ccc,stroke:#333,stroke-width:2px
    
    %% Click Events
    click API "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/api"
    click Chrome "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/chromium"
    click Libre "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/libreoffice"
    click PDF "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/pdfengines"
    click QPDF "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/qpdf"
    click PDFtk "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/pdftk"
    click PDFcpu "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/pdfcpu"
    click Exif "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/exiftool"
    click Hook "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/webhook"
    click Prom "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/prometheus"
    click Log "https://github.com/gotenberg/gotenberg/tree/main/pkg/modules/logging"
    click Entry "https://github.com/gotenberg/gotenberg/blob/main/cmd/gotenberg/main.go"
    click Docker "https://github.com/gotenberg/gotenberg/tree/main/build/Dockerfile"
    
    %% Legend
    subgraph Legend
        direction TB
        L1["External System"]:::external
        L2["API Component"]:::api
        L3["Core Component"]:::core
        L4["Converter"]:::converter
        L5["PDF Engine"]:::pdf
        L6["Support Service"]:::support
        L7["Entry Point"]:::entry
    end
```
