# donue-labs/gotenberg architecture

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

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

## Overview

##### Project type and purpose
- Gotenberg is a backend-only, containerized HTTP microservice (written in Go) that exposes a REST API for converting documents (HTML, Markdown, Word, Excel, etc.) into PDF.
- It follows a plugin-style, modular monolith architecture: a single service exposing multiple “modules” (Chromium, LibreOffice, PDF engines, ExifTool, Webhook, Prometheus).

##### Top-level components (to include
- Clients – any HTTP clients (curl, Postman, other microservices) that call Gotenberg’s endpoints.
- API Layer – the Go HTTP server (Gin/Gonic or net/http) handling routing, middleware (logging, metrics, CORS, body size limits), and request validation.
- Core Service – the Gotenberg binary running inside a Docker container.  Inside it:
– Context & Env manager (pkg/gotenberg/context.go, env.go)
– Supervisor (pkg/gotenberg/supervisor.go) orchestrates module execution and cleanup
– FileSystem abstraction (pkg/gotenberg/fs.go) for temp directories and file management
– Logging & metrics (pkg/gotenberg/logging.go, metrics.go)
– Plugin registry (pkg/gotenberg/modules.go) loading each module’s routes and handlers
– Chromium (headless browser)
– LibreOffice (headless office suite)
– pdfcpu, qpdf, pdftk (PDF manipulations)
– ExifTool (metadata extraction)
– Webhook (callback client)
– Prometheus (metrics exporter endpoint)
- External binaries or services – for modules that shell out to external tools (e.g. Chrome executable, libreoffice binary, qpdf binary).
- Temporary File Store – ephemeral file system inside the container (or a mounted Docker volume) for staging input/output files.
- Networking – Docker’s internal network (shown when using docker-compose), exposing port 3000 on the host.
- Optional External Systems – Webhook receivers (if the webhook module is used), monitoring system scraping Prometheus metrics.

##### Relationships and data flow
1. Client issues HTTP request → hits API Layer
2. Middleware processes auth/logging/metrics → forwards to core router
3. Router delegates to Supervisor with a context
4. Supervisor loads appropriate module plugin based on the route (e.g. /convert/html uses Chromium module)
5. Module writes input to temp store → invokes binary or Go library → produces PDF in temp store
6. Module streams PDF back via HTTP response or stores it and triggers a Webhook callback
7. Metrics middleware exposes Prometheus metrics on /metrics
8. Unity: Supervisor cleans up temp files, collects logs, updates metrics

##### Architectural patterns & design principles
- Modular Monolith / Plugin Architecture – each conversion engine is isolated in its own package under pkg/modules.
- Supervisor Pattern – central orchestrator handles module lifecycle and error handling.
- Middleware Chain – cross-cutting concerns (logging, metrics, request size limits) applied uniformly.
- Containerization – the entire service and its dependencies run in a single Docker container for consistency.

##### Important technologies & frameworks
- Go (Gin/Gonic or net/http router, go modules)
- Docker & Docker Compose (build/Dockerfile, docker-compose.yml)
- GitHub Actions (CI/CD pipelines under .github/workflows)
- Prometheus client library for metrics
- External executables: Chromium, LibreOffice, qpdf, pdfcpu, pdftk, ExifTool

##### Detail is key
– Include every module you see under pkg/modules.
– Show the temp file system and cleanup step.
– Don’t forget cross-cutting middleware (logging, metrics).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and external systems
    Clients["HTTP Clients"]:::client
    WebhookReceiver["Webhook Receivers"]:::externalService
    Monitoring["Monitoring System"]:::externalService

    %% Docker container boundary
    subgraph "Docker Container: Gotenberg"
      direction TB

      %% API Layer
      subgraph "API Layer"
        direction TB
        Router["Router & Middleware"]:::core
      end

      %% Core Service internals
      subgraph "Core Service"
        direction TB
        ContextEnv["Context & Env Manager"]:::core
        Supervisor["Supervisor"]:::core
        FileStore["Temp File Store"]:::storage
        LoggingMetrics["Logging & Metrics"]:::core
        PluginRegistry["Plugin Registry"]:::core
      end

      %% Modules group
      subgraph "Modules"
        direction TB
        Chromium["Chromium Module"]:::module
        LibreOffice["LibreOffice Module"]:::module
        PDFCPU["PDFCPU Module"]:::module
        QPDF["QPDF Module"]:::module
        PDFTK["PDFTK Module"]:::module
        PDFEngines["PDF Engines Aggregator"]:::module
        ExifTool["ExifTool Module"]:::module
        WebhookMod["Webhook Module"]:::module
        PrometheusMod["Prometheus Module"]:::module
      end
    end

    %% External binaries
    subgraph "External Binaries"
      direction TB
      EXE_Chrome["Chrome Executable"]:::externalBinary
      EXE_LO["LibreOffice Binary"]:::externalBinary
      EXE_QPDF["qpdf Binary"]:::externalBinary
      EXE_PDFCPU["pdfcpu Binary"]:::externalBinary
      EXE_PDFTK["pdftk Binary"]:::externalBinary
      EXE_Exif["ExifTool Executable"]:::externalBinary
    end

    %% Connections
    Clients -->|"HTTP Request"| Router
    Router -->|"context"| Supervisor
    Supervisor -->|"load plugin"| PluginRegistry
    PluginRegistry --> Chromium
    PluginRegistry --> LibreOffice
    PluginRegistry --> PDFCPU
    PluginRegistry --> QPDF
    PluginRegistry --> PDFTK
    PluginRegistry --> PDFEngines
    PluginRegistry --> ExifTool
    PluginRegistry --> WebhookMod
    PluginRegistry --> PrometheusMod

    Chromium -->|"write/read files"| FileStore
    LibreOffice -->|"write/read files"| FileStore
    PDFCPU -->|"write/read files"| FileStore
    QPDF -->|"write/read files"| FileStore
    PDFTK -->|"write/read files"| FileStore
    PDFEngines -->|"write/read files"| FileStore
    ExifTool -->|"write/read files"| FileStore
    WebhookMod -->|"callback"| WebhookReceiver
    PrometheusMod -->|"metrics"| Monitoring

    Chromium --> EXE_Chrome
    LibreOffice --> EXE_LO
    QPDF --> EXE_QPDF
    PDFCPU --> EXE_PDFCPU
    PDFTK --> EXE_PDFTK
    ExifTool --> EXE_Exif

    FileStore --> Supervisor
    Supervisor -->|"cleanup"| FileStore
    Supervisor -->|"logs & metrics"| LoggingMetrics
    LoggingMetrics --> PrometheusMod

    Router --> Clients
    PrometheusMod --> Monitoring

    %% Click events
    click Router "https://github.com/donue-labs/gotenberg/blob/main/cmd/gotenberg/main.go"
    click Router "https://github.com/donue-labs/gotenberg/tree/main/pkg/modules/api/"
    click ContextEnv "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/context.go"
    click ContextEnv "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/env.go"
    click Supervisor "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/supervisor.go"
    click FileStore "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/fs.go"
    click LoggingMetrics "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/logging.go"
    click LoggingMetrics "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/metrics.go"
    click PluginRegistry "https://github.com/donue-labs/gotenberg/blob/main/pkg/gotenberg/modules.go"
    click Chromium "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/chromium/chromium.go"
    click Chromium "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/chromium/browser.go"
    click Chromium "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/chromium/routes.go"
    click Chromium "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/chromium/stream.go"
    click Chromium "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/chromium/tasks.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/libreoffice.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/routes.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/api/api.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/api/freeport.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/health_routes.go"
    click LibreOffice "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/libreoffice/pdfengine/pdfengine.go"
    click PDFCPU "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdfcpu/pdfcpu.go"
    click PDFCPU "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdfcpu/sort.go"
    click QPDF "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/qpdf/qpdf.go"
    click PDFTK "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdftk/pdftk.go"
    click PDFEngines "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdfengines/pdfengines.go"
    click PDFEngines "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdfengines/multi.go"
    click PDFEngines "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/pdfengines/routes.go"
    click ExifTool "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/exiftool/exiftool.go"
    click WebhookMod "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/webhook/webhook.go"
    click WebhookMod "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/webhook/client.go"
    click WebhookMod "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/webhook/middleware.go"
    click PrometheusMod "https://github.com/donue-labs/gotenberg/blob/main/pkg/modules/prometheus/prometheus.go"
    click Clients "https://github.com/donue-labs/gotenberg/blob/main/docker-compose.yml"
    click Clients "https://github.com/donue-labs/gotenberg/tree/main/build/Dockerfile"

    %% Styles
    classDef core fill:#a8ddb5,stroke:#2b7a0b
    classDef module fill:#9ecae1,stroke:#08519c
    classDef storage fill:#f0f0f0,stroke:#636363
    classDef externalBinary fill:#d9d9d9,stroke:#252525,stroke-dasharray: 2 2
    classDef externalService fill:#fdae6b,stroke:#7f2704
    classDef client fill:#deebf7,stroke:#3182bd
```
