# kikk79/zugferd-studio architecture

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

- Interactive diagram: https://gitdiagram.com/kikk79/zugferd-studio
- Repository: https://github.com/kikk79/zugferd-studio

## Overview

ZUGFeRD Studio is a local invoice-to-hybrid-PDF application. Users load a PDF or Word invoice, review and correct extracted fields, then generate and save a ZUGFeRD/Factur-X PDF. The API coordinates extraction, calculation and validation, XML/PDF generation, business-rule checks, and output handling. The graph reflects the documented workflow and sampled calls; unsampled route details and session-storage wiring are not expanded beyond the available evidence.

Main entry points: [`app.py`](https://github.com/kikk79/zugferd-studio/blob/main/app.py) (Local API), [`invoice_logic.py`](https://github.com/kikk79/zugferd-studio/blob/main/invoice_logic.py) (Invoice calculations), [`output.py`](https://github.com/kikk79/zugferd-studio/blob/main/output.py) (Output handling), [`launcher.py`](https://github.com/kikk79/zugferd-studio/blob/main/launcher.py) (Desktop launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["Browser editor<br/>[app.js]"]
end

subgraph group_workflow["Invoice workflow"]
  node_api["Local API<br/>[app.py]"]
  node_extractor["Document extraction<br/>[extractor.py]"]
  node_generator["ZUGFeRD XML and PDF"]
  node_renderer["PDF rendering<br/>[pdf_renderer.py]"]
end

subgraph group_validation["Calculation and validation"]
  node_logic["Invoice calculations<br/>[invoice_logic.py]"]
  node_schematron["Business-rule check<br/>[schematron.py]"]
end

subgraph group_delivery["Output and runtime"]
  node_output["Output handling<br/>[output.py]"]
  node_paths["Runtime paths<br/>[paths.py]"]
  node_launcher["Desktop launcher<br/>[launcher.py]"]
  node_finished_pdf["Saved invoice PDF"]
end

node_user(("Invoice user"))
node_java["Java runtime"]

node_user -->|"opens and edits"| node_frontend
node_frontend -->|"uploads and calculates"| node_api
node_launcher -->|"starts server"| node_api
node_launcher -->|"hands off files"| node_api
node_api -->|"extracts invoice data"| node_extractor
node_extractor -->|"parses amounts"| node_logic
node_api -->|"calculates and validates"| node_logic
node_api -->|"converts or renders PDF"| node_renderer
node_renderer -->|"uses shared totals"| node_logic
node_api -->|"builds hybrid invoice"| node_generator
node_generator -->|"uses shared totals"| node_logic
node_api -->|"checks business rules"| node_schematron
node_schematron -.->|"runs Saxon checks"| node_java
node_api -->|"saves generated PDF"| node_output
node_output -->|"resolves fallback folder"| node_paths
node_output -->|"writes result"| node_finished_pdf

click node_frontend "https://github.com/kikk79/zugferd-studio/blob/main/static/app.js"
click node_api "https://github.com/kikk79/zugferd-studio/blob/main/app.py"
click node_extractor "https://github.com/kikk79/zugferd-studio/blob/main/extractor.py"
click node_logic "https://github.com/kikk79/zugferd-studio/blob/main/invoice_logic.py"
click node_schematron "https://github.com/kikk79/zugferd-studio/blob/main/schematron.py"
click node_generator "https://github.com/kikk79/zugferd-studio/blob/main/zugferd_generator.py"
click node_renderer "https://github.com/kikk79/zugferd-studio/blob/main/pdf_renderer.py"
click node_output "https://github.com/kikk79/zugferd-studio/blob/main/output.py"
click node_paths "https://github.com/kikk79/zugferd-studio/blob/main/paths.py"
click node_launcher "https://github.com/kikk79/zugferd-studio/blob/main/launcher.py"

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_frontend,node_user toneBlue
class node_api,node_extractor,node_generator,node_renderer toneAmber
class node_logic,node_schematron toneMint
class node_output,node_paths,node_launcher,node_finished_pdf toneRose
class node_java toneIndigo
```

## Components

### User interface

- [Browser editor](https://github.com/kikk79/zugferd-studio/blob/main/static/app.js): `static/app.js`

### Invoice workflow

- [Local API](https://github.com/kikk79/zugferd-studio/blob/main/app.py): `app.py`
- [Document extraction](https://github.com/kikk79/zugferd-studio/blob/main/extractor.py): `extractor.py`
- [ZUGFeRD XML and PDF](https://github.com/kikk79/zugferd-studio/blob/main/zugferd_generator.py): `zugferd_generator.py`
- [PDF rendering](https://github.com/kikk79/zugferd-studio/blob/main/pdf_renderer.py): `pdf_renderer.py`

### Calculation and validation

- [Invoice calculations](https://github.com/kikk79/zugferd-studio/blob/main/invoice_logic.py): `invoice_logic.py`
- [Business-rule check](https://github.com/kikk79/zugferd-studio/blob/main/schematron.py): `schematron.py`

### Output and runtime

- [Output handling](https://github.com/kikk79/zugferd-studio/blob/main/output.py): `output.py`
- [Runtime paths](https://github.com/kikk79/zugferd-studio/blob/main/paths.py): `paths.py`
- [Desktop launcher](https://github.com/kikk79/zugferd-studio/blob/main/launcher.py): `launcher.py`
- **Saved invoice PDF**

### Other components

- **Invoice user**
- **Java runtime**

## Connections

- Invoice user → Browser editor: opens and edits (evidence: `README.md`)
- Browser editor → Local API: uploads and calculates (evidence: `static/app.js`)
- Desktop launcher → Local API: starts server (evidence: `launcher.py`)
- Desktop launcher → Local API: hands off files (evidence: `launcher.py`)
- Local API → Document extraction: extracts invoice data (evidence: `app.py`)
- Document extraction → Invoice calculations: parses amounts (evidence: `extractor.py`)
- Local API → Invoice calculations: calculates and validates (evidence: `app.py`)
- Local API → PDF rendering: converts or renders PDF (evidence: `app.py`)
- PDF rendering → Invoice calculations: uses shared totals (evidence: `pdf_renderer.py`)
- Local API → ZUGFeRD XML and PDF: builds hybrid invoice (evidence: `app.py`)
- ZUGFeRD XML and PDF → Invoice calculations: uses shared totals (evidence: `zugferd_generator.py`)
- Local API → Business-rule check: checks business rules (evidence: `app.py`)
- Business-rule check → Java runtime: runs Saxon checks (evidence: `schematron.py`)
- Local API → Output handling: saves generated PDF (evidence: `app.py`)
- Output handling → Runtime paths: resolves fallback folder (evidence: `output.py`)
- Output handling → Saved invoice PDF: writes result (evidence: `output.py`)
