# johnfercher/maroto architecture

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

- Interactive diagram: https://gitdiagram.com/johnfercher/maroto
- Repository: https://github.com/johnfercher/maroto

## Overview

Maroto is a Go library for constructing PDFs with a Bootstrap-like row/column layout. The principal workflow is to configure a document, compose pages from rows, columns, and components, then generate and save a PDF. The graph also preserves documented page management and header/footer behavior, plus the rendering backend, code generation, caching, and metrics/reporting capabilities. Some branches are documented or indexed but their implementation was not excerpted, so those links are dashed where the connection is unverified.

Main entry points: [`maroto.go`](https://github.com/johnfercher/maroto/blob/master/maroto.go) (Document Orchestrator), [`internal/providers/gofpdf/provider.go`](https://github.com/johnfercher/maroto/blob/master/internal/providers/gofpdf/provider.go) (Gofpdf Provider), [`metricsdecorator.go`](https://github.com/johnfercher/maroto/blob/master/metricsdecorator.go) (Metrics Decorator), [`pkg/components/page/page.go`](https://github.com/johnfercher/maroto/blob/master/pkg/components/page/page.go) (Pages and Headers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Document Setup"]
  node_config["Config Builder<br/>[builder.go]"]
  node_fontrepo["Custom Fonts<br/>[fontrepository.go]"]
end

subgraph group_layout["Layout and Components"]
  node_maroto["Document Orchestrator<br/>[maroto.go]"]
  node_layoutgrid["Rows and Columns<br/>[row.go]"]
  node_pageflow["Pages and Headers<br/>[page.go]"]
  node_textcomp["Text Components<br/>[text.go]"]
  node_imagecomp["Image Components<br/>[bytesimage.go]"]
  node_codecomp["Barcode Components<br/>[barcode.go]"]
  node_othercomp["Other Components"]
end

subgraph group_render["PDF Rendering"]
  node_coremodel["Core Render Contracts<br/>[components.go]"]
  node_gofpdf["Gofpdf Provider<br/>[provider.go]"]
  node_codegen["Code Generation<br/>[code.go]"]
  node_cellwriter["Cell Styling<br/>[cellwriter.go]"]
  node_imagecache[("Image Cache<br/>[cache.go]")]
end

subgraph group_output["Output and Instrumentation"]
  node_pdfdoc["PDF Document<br/>[pdf.go]"]
  node_metrics["Metrics Decorator"]
  node_report["Metrics and Reports<br/>[metrics.go]"]
end

node_author(("PDF Author"))
node_filesystem[("File System")]

node_author -->|"sets options"| node_config
node_author -->|"builds document"| node_maroto
node_config -->|"configures"| node_maroto
node_author -.->|"registers fonts"| node_fontrepo
node_fontrepo -->|"reads font files"| node_filesystem
node_author -->|"composes rows"| node_layoutgrid
node_layoutgrid -->|"adds rows"| node_maroto
node_maroto -.->|"manages pages"| node_pageflow
node_author -->|"adds text"| node_textcomp
node_author -->|"adds images"| node_imagecomp
node_author -->|"adds codes"| node_codecomp
node_author -.->|"adds elements"| node_othercomp
node_textcomp -.->|"renders through"| node_coremodel
node_imagecomp -->|"renders through"| node_coremodel
node_codecomp -->|"renders through"| node_coremodel
node_maroto -->|"renders pages"| node_pageflow
node_pageflow -->|"renders with"| node_gofpdf
node_gofpdf -->|"generates codes"| node_codegen
node_gofpdf -->|"reads and writes"| node_imagecache
node_gofpdf -->|"applies cell styles"| node_cellwriter
node_maroto -->|"creates document"| node_pdfdoc
node_author -->|"decorates generation"| node_metrics
node_metrics -->|"wraps document API"| node_maroto
node_metrics -->|"collects metrics"| node_report
node_author -->|"saves PDF"| node_pdfdoc
node_author -->|"saves report"| node_report
node_pdfdoc -.->|"writes PDF"| node_filesystem
node_report -.->|"writes report"| node_filesystem

click node_config "https://github.com/johnfercher/maroto/blob/master/pkg/config/builder.go"
click node_fontrepo "https://github.com/johnfercher/maroto/blob/master/pkg/fontrepository/fontrepository.go"
click node_maroto "https://github.com/johnfercher/maroto/blob/master/maroto.go"
click node_layoutgrid "https://github.com/johnfercher/maroto/blob/master/pkg/components/row/row.go"
click node_pageflow "https://github.com/johnfercher/maroto/blob/master/pkg/components/page/page.go"
click node_textcomp "https://github.com/johnfercher/maroto/blob/master/pkg/components/text/text.go"
click node_imagecomp "https://github.com/johnfercher/maroto/blob/master/pkg/components/image/bytesimage.go"
click node_codecomp "https://github.com/johnfercher/maroto/blob/master/pkg/components/code/barcode.go"
click node_othercomp "https://github.com/johnfercher/maroto/tree/master/pkg/components"
click node_coremodel "https://github.com/johnfercher/maroto/blob/master/pkg/core/components.go"
click node_gofpdf "https://github.com/johnfercher/maroto/blob/master/internal/providers/gofpdf/provider.go"
click node_codegen "https://github.com/johnfercher/maroto/blob/master/internal/code/code.go"
click node_cellwriter "https://github.com/johnfercher/maroto/blob/master/internal/providers/gofpdf/cellwriter/cellwriter.go"
click node_imagecache "https://github.com/johnfercher/maroto/blob/master/internal/cache/cache.go"
click node_pdfdoc "https://github.com/johnfercher/maroto/blob/master/pkg/core/pdf.go"
click node_metrics "https://github.com/johnfercher/maroto/blob/master/metricsdecorator.go"
click node_report "https://github.com/johnfercher/maroto/blob/master/pkg/metrics/metrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_fontrepo toneBlue
class node_maroto,node_layoutgrid,node_pageflow,node_textcomp,node_imagecomp,node_codecomp,node_othercomp,node_filesystem toneAmber
class node_coremodel,node_gofpdf,node_codegen,node_cellwriter,node_imagecache toneMint
class node_pdfdoc,node_metrics,node_report toneRose
class node_author toneIndigo
```

## Components

### Document Setup

- [Config Builder](https://github.com/johnfercher/maroto/blob/master/pkg/config/builder.go): `pkg/config/builder.go`
- [Custom Fonts](https://github.com/johnfercher/maroto/blob/master/pkg/fontrepository/fontrepository.go): `pkg/fontrepository/fontrepository.go`

### Layout and Components

- [Document Orchestrator](https://github.com/johnfercher/maroto/blob/master/maroto.go): `maroto.go`
- [Rows and Columns](https://github.com/johnfercher/maroto/blob/master/pkg/components/row/row.go): `pkg/components/row/row.go`
- [Pages and Headers](https://github.com/johnfercher/maroto/blob/master/pkg/components/page/page.go): `pkg/components/page/page.go`
- [Text Components](https://github.com/johnfercher/maroto/blob/master/pkg/components/text/text.go): `pkg/components/text/text.go`
- [Image Components](https://github.com/johnfercher/maroto/blob/master/pkg/components/image/bytesimage.go): `pkg/components/image/bytesimage.go`
- [Barcode Components](https://github.com/johnfercher/maroto/blob/master/pkg/components/code/barcode.go): `pkg/components/code/barcode.go`
- [Other Components](https://github.com/johnfercher/maroto/tree/master/pkg/components): `pkg/components`

### PDF Rendering

- [Core Render Contracts](https://github.com/johnfercher/maroto/blob/master/pkg/core/components.go): `pkg/core/components.go`
- [Gofpdf Provider](https://github.com/johnfercher/maroto/blob/master/internal/providers/gofpdf/provider.go): `internal/providers/gofpdf/provider.go`
- [Code Generation](https://github.com/johnfercher/maroto/blob/master/internal/code/code.go): `internal/code/code.go`
- [Cell Styling](https://github.com/johnfercher/maroto/blob/master/internal/providers/gofpdf/cellwriter/cellwriter.go): `internal/providers/gofpdf/cellwriter/cellwriter.go`
- [Image Cache](https://github.com/johnfercher/maroto/blob/master/internal/cache/cache.go): `internal/cache/cache.go`

### Output and Instrumentation

- [PDF Document](https://github.com/johnfercher/maroto/blob/master/pkg/core/pdf.go): `pkg/core/pdf.go`
- [Metrics Decorator](https://github.com/johnfercher/maroto/blob/master/metricsdecorator.go): `metricsdecorator.go`
- [Metrics and Reports](https://github.com/johnfercher/maroto/blob/master/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`

### Other components

- **PDF Author**
- **File System**

## Connections

- PDF Author → Config Builder: sets options
- PDF Author → Document Orchestrator: builds document
- Config Builder → Document Orchestrator: configures (evidence: `maroto.go`)
- PDF Author → Custom Fonts: registers fonts
- Custom Fonts → File System: reads font files (evidence: `pkg/fontrepository/fontrepository.go`)
- PDF Author → Rows and Columns: composes rows
- Rows and Columns → Document Orchestrator: adds rows
- Document Orchestrator → Pages and Headers: manages pages
- PDF Author → Text Components: adds text
- PDF Author → Image Components: adds images
- PDF Author → Barcode Components: adds codes
- PDF Author → Other Components: adds elements
- Text Components → Core Render Contracts: renders through
- Image Components → Core Render Contracts: renders through (evidence: `pkg/components/image/bytesimage.go`)
- Barcode Components → Core Render Contracts: renders through (evidence: `pkg/components/code/barcode.go`)
- Document Orchestrator → Pages and Headers: renders pages (evidence: `maroto.go`)
- Pages and Headers → Gofpdf Provider: renders with
- Gofpdf Provider → Code Generation: generates codes (evidence: `internal/providers/gofpdf/provider.go`)
- Gofpdf Provider → Image Cache: reads and writes (evidence: `internal/providers/gofpdf/provider.go`)
- Gofpdf Provider → Cell Styling: applies cell styles (evidence: `internal/providers/gofpdf/provider.go`)
- Document Orchestrator → PDF Document: creates document (evidence: `maroto.go`)
- PDF Author → Metrics Decorator: decorates generation
- Metrics Decorator → Document Orchestrator: wraps document API (evidence: `metricsdecorator.go`)
- Metrics Decorator → Metrics and Reports: collects metrics (evidence: `metricsdecorator.go`)
- PDF Author → PDF Document: saves PDF
- PDF Author → Metrics and Reports: saves report
- PDF Document → File System: writes PDF
- Metrics and Reports → File System: writes report
