# texhackse/latex-zugferd architecture

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

- Interactive diagram: https://gitdiagram.com/texhackse/latex-zugferd
- Repository: https://github.com/texhackse/latex-zugferd

## Overview

##### Project type and purpose
- This is an open-source LaTeX package (“zugferd”) to produce ZUGFeRD-compliant electronic invoices by generating an XML invoice and embedding it into a PDF.
- The README clarifies that it provides both a demo template and interfaces for attaching externally generated XML, and uses the LaTeX3/l3build toolchain to compile and test.

##### File structure
- Top-level source:
- zugferd.dtx (package code + documentation)
- zugferd.ins (installer to extract .sty)
- zugferd-invoice.sty (built style)
- Build/configuration:
- build.lua, config-pdf.lua (l3build scripts)
- .tl_packages, DEPENDS.txt, INSTALL.md
- CI pipelines:
- .github/workflows/l3build.yaml
- .gitlab-ci.yml
- Test assets:
- testfiles/ (LaTeX-to-XML unit tests: .lvt → .tlg)
- testfiles-pdf/ (PDF-to-attachment tests: .pdftex.tpf, .tpf, .pvt)
- support/validate_zugferd.sh (shell validation helper)
- Misc:
- DEMO-rechnung-zugferd.tex (example invoice)

##### README for additional insights
- Confirms core responsibilities: generate XML, attach to PDF, various profiles (BASIC, MINIMUM, XRechnung), no built-in validation.
- Notes reliance on LaTeX3/pdfmeta interfaces (“l3pdfmeta”) and standard TeX engines.

##### Diagramming recommendations
- “Source Repo”
- “CI Pipeline”
- “Build & Test (l3build)”
- “LaTeX Engine + zugferd-invoice.sty”
- “Test Harness”
- “Support Scripts”
- “Output Artifacts”
- Repo → CI → Build → LaTeX Engine → Outputs → Validation
- Build → Test Harness → pass/fail → CI
- Blue for code artifacts
- Green for build/test processes
- Orange for external dependencies
- Gray for utilities & scripts
- Rectangles for processes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository & Documentation
    subgraph "Repository & Documentation"
        Repo["Repository / Version Control"]:::code
        Doc["Documentation (README.md, INSTALL.md)"]:::doc
    end

    %% CI Pipeline
    CI["CI Pipeline"]:::process

    %% Build & Test Engine
    Build["Build & Test Engine (l3build)"]:::process

    %% Package Module
    Package["Package Module (zugferd.dtx, zugferd.ins)"]:::code

    %% LaTeX Engine + Package
    LaTeX["LaTeX Engine + zugferd-invoice.sty"]:::exec

    %% Demo Template
    Demo["Demo Template (DEMO-rechnung-zugferd.tex)"]:::doc

    %% Test Harness
    Test["Test Harness (testfiles/, testfiles-pdf/)"]:::process

    %% Support Utilities
    Support["Support Utilities"]:::util

    %% External Dependencies
    ExtDep["External Dependencies"]:::external

    %% Output Artifacts
    Output["Output Artifacts"]:::artifact

    %% Connections
    Repo -->|"push"| CI
    CI -->|"run l3build"| Build
    Build -->|"extract .sty"| Package
    Build -->|"invoke TeX engine"| LaTeX
    Package -->|"used by"| LaTeX
    Demo -->|"input demo .tex"| LaTeX
    LaTeX -->|"generate PDF+XML"| Output
    Build -->|"run tests"| Test
    Test -->|"pass/fail feedback"| CI
    Output -->|"validate XML"| Support
    Output -->|"publish artifacts"| CI
    ExtDep -->|"provides engine"| LaTeX
    ExtDep -->|"provides l3build"| Build

    %% Click Events
    click Repo "https://github.com/texhackse/latex-zugferd/blob/main/."
    click Doc "https://github.com/texhackse/latex-zugferd/blob/main/README.md"
    click Doc "https://github.com/texhackse/latex-zugferd/blob/main/INSTALL.md"
    click CI "https://github.com/texhackse/latex-zugferd/blob/main/.github/workflows/l3build.yaml"
    click CI "https://github.com/texhackse/latex-zugferd/blob/main/.gitlab-ci.yml"
    click Build "https://github.com/texhackse/latex-zugferd/blob/main/build.lua"
    click Build "https://github.com/texhackse/latex-zugferd/blob/main/config-pdf.lua"
    click Build "https://github.com/texhackse/latex-zugferd/blob/main/.tl_packages"
    click Build "https://github.com/texhackse/latex-zugferd/blob/main/DEPENDS.txt"
    click Build "https://github.com/texhackse/latex-zugferd/blob/main/INSTALL.md"
    click Package "https://github.com/texhackse/latex-zugferd/blob/main/zugferd.dtx"
    click Package "https://github.com/texhackse/latex-zugferd/blob/main/zugferd.ins"
    click LaTeX "https://github.com/texhackse/latex-zugferd/blob/main/zugferd-invoice.sty"
    click Demo "https://github.com/texhackse/latex-zugferd/blob/main/DEMO-rechnung-zugferd.tex"
    click Test "https://github.com/texhackse/latex-zugferd/tree/main/testfiles/"
    click Test "https://github.com/texhackse/latex-zugferd/tree/main/testfiles-pdf/"
    click Support "https://github.com/texhackse/latex-zugferd/blob/main/support/validate_zugferd.sh"
    click Support "https://github.com/texhackse/latex-zugferd/blob/main/support/zugferd-test.ltx"

    %% Styles
    classDef code fill:#D0E1FF,stroke:#333,stroke-width:1px
    classDef process fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef exec fill:#FFE7BA,stroke:#333,stroke-width:1px
    classDef util fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef doc fill:#F4D1FD,stroke:#333,stroke-width:1px
    classDef external fill:#FFD7D7,stroke:#333,stroke-width:1px
    classDef artifact fill:#FFD3D3,stroke:#333,stroke-width:1px
```
