# gipson-dev/labelprinterapp architecture

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

- Interactive diagram: https://gitdiagram.com/gipson-dev/labelprinterapp
- Repository: https://github.com/gipson-dev/labelprinterapp

## Overview

1. **Overall shape**: This is a single-process **Windows desktop application** built with **C++/CMake + Qt 6**. There is no server or cloud boundary; the app’s main responsibility is to turn label definitions and CSV data into **raw ZPL** and send that ZPL directly to a Zebra printer.

2. **Core domain model**: The `core/` folder holds the app’s central data model. `LabelTemplate`, `LabelElement`, and `PrinterSettings` represent the editable label design and printer configuration. These are the objects that move through the rest of the system.

3. **Template persistence boundary**: `TemplateStorage` is the persistence layer for label templates. Templates are stored as **JSON files** under `templates/`, which makes them both user-loadable in the UI and easy to version/control as assets.

4. **CSV ingestion boundary**: `CsvImporter` reads external CSV files into row data for batch printing. The README indicates support for `Quantity`/`Qty` columns, selected rows, and full-file printing, so CSV data is not just imported but also drives print multiplicity.

5. **Variable resolution layer**: `VariableResolver` sits between data input and rendering. It resolves placeholders like `{ItemNumber}`, `{Lot}`, `{Date}`, `{Time}`, `{Serial}`, and `{RecordIndex}` against the current record or print context, so the same template can be reused across single labels, serial ranges, and CSV batches.

6. **ZPL generation pipeline**: `ZplGenerator` converts the template model into **Zebra Programming Language**. This is the key transformation step in the architecture: structured label elements and resolved variables become printer-ready command text. The repo includes `docs/example_generated.zpl` and `label.zpl` as concrete output/reference artifacts.

7. **Printer output boundary**: `ZebraPrinter` is the hardware-facing adapter. It sends the generated raw ZPL to a **Windows printer** configured for Zebra/ZPL output. The app’s printing model is therefore “generate ZPL locally, send it directly to the driver/printer,” not rasterize or spool through a separate print service.

8. **Qt UI composition**: The `ui/` folder contains the interactive front end. `MainWindow` is the shell that exposes the app’s major modes/tabs: Design, Elements, Data, Print, Templates, and Settings. `ElementEditorWidget` edits the properties of the selected label element, and `PreviewWidget` is the visual label canvas.

9. **Editing and preview flow**: User interaction starts in the UI, updates the template model, and immediately feeds preview/rendering and later print generation. Dragging in the preview changes element placement; property edits change typography, barcode/QR options, rotation, alignment, wrapping, margins, and other label settings.

10. **Batch-print flow**: For CSV-driven printing, the flow is: import CSV → optionally map columns to template placeholders → select rows or choose all → resolve variables per row → generate ZPL per label → send to printer. This is the main data path for operational use.

11. **Template library and examples**: The `templates/` folder contains ready-made label definitions such as inventory, shelf/bin, price, serial number, asset QR, and mini shipping labels. `examples/sample_items.csv` provides a sample batch input file. These assets define the “starter content” boundary of the app.

12. **Validation and regression coverage**: `tests/model_zpl_tests.cpp` suggests automated coverage around the model-to-ZPL transformation, which is the most critical non-UI logic in the system. That implies the core rendering/output behavior is intended to be stable independent of the UI.

13. **Build and release tooling**: The repository is packaged as a CMake project with Windows-focused scripts in `scripts/`, plus GitHub Actions workflows for build and release. `windeployqt` support in packaging indicates a Qt desktop distribution that bundles runtime dependencies into `dist/LabelPrinterApp`.

14. **Architecture in one sentence**: The app is a **Qt desktop editor + batch-print tool** where the UI edits a JSON-backed label model, CSV data fills template variables, core services generate ZPL, and a printer adapter streams that ZPL to a Zebra printer.

Main entry points: [`core/ZplGenerator.cpp`](https://github.com/gipson-dev/labelprinterapp/blob/main/core/ZplGenerator.cpp) (ZPL generator), [`core/LabelTemplate.h`](https://github.com/gipson-dev/labelprinterapp/blob/main/core/LabelTemplate.h) (Label model), [`ui/MainWindow.cpp`](https://github.com/gipson-dev/labelprinterapp/blob/main/ui/MainWindow.cpp) (Main window), [`core/VariableResolver.cpp`](https://github.com/gipson-dev/labelprinterapp/blob/main/core/VariableResolver.cpp) (Variable resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["App entry<br/>Qt app<br/>[main.cpp]"]
end

subgraph group_core["Core"]
  node_template_model["Label model<br/>domain model<br/>[LabelTemplate.h]"]
  node_label_element["Label element<br/>domain model<br/>[LabelElement.h]"]
  node_printer_settings["Printer settings<br/>config model<br/>[PrinterSettings.h]"]
  node_template_storage["Template storage<br/>json persistence"]
  node_csv_importer["CSV importer<br/>data ingest<br/>[CsvImporter.cpp]"]
  node_variable_resolver["Variable resolver<br/>placeholder engine"]
  node_zpl_generator["ZPL generator<br/>render pipeline<br/>[ZplGenerator.cpp]"]
  node_zebra_printer["Zebra printer<br/>printer adapter<br/>[ZebraPrinter.cpp]"]
end

subgraph group_ui["UI"]
  node_mainwindow["Main window<br/>Qt shell<br/>[MainWindow.cpp]"]
  node_element_editor["Element editor<br/>property editor"]
  node_preview["Preview canvas<br/>label canvas<br/>[PreviewWidget.cpp]"]
end

subgraph group_assets["Assets"]
  node_templates_dir["Templates<br/>template library"]
  node_sample_csv["Sample CSV<br/>input example<br/>[sample_items.csv]"]
  node_zpl_ref["ZPL reference<br/>output sample"]
  node_label_ref["Label sample<br/>output sample<br/>[label.zpl]"]
end

subgraph group_tooling["Tooling"]
  node_zpl_tests["ZPL tests<br/>test suite"]
  node_build_scripts["Build scripts<br/>packaging<br/>[build-and-test.ps1]"]
end

node_main -->|"launches"| node_mainwindow
node_mainwindow -->|"edits"| node_element_editor
node_mainwindow -->|"shows"| node_preview
node_mainwindow -->|"binds"| node_template_model
node_element_editor -->|"updates"| node_label_element
node_preview -->|"positions"| node_label_element
node_preview -->|"renders"| node_template_model
node_template_storage -->|"reads/writes"| node_templates_dir
node_template_storage -->|"loads"| node_template_model
node_csv_importer -->|"ingests"| node_sample_csv
node_csv_importer -->|"feeds"| node_variable_resolver
node_variable_resolver -->|"fills"| node_template_model
node_variable_resolver -->|"prepares"| node_zpl_generator
node_zpl_generator -->|"converts"| node_template_model
node_zpl_generator -.->|"matches"| node_zpl_ref
node_zpl_generator -.->|"matches"| node_label_ref
node_zpl_generator -->|"outputs"| node_zebra_printer
node_zebra_printer -.->|"packages with"| node_build_scripts
node_zpl_tests -->|"verifies"| node_zpl_generator

click node_main "https://github.com/gipson-dev/labelprinterapp/blob/main/main.cpp"
click node_mainwindow "https://github.com/gipson-dev/labelprinterapp/blob/main/ui/MainWindow.cpp"
click node_element_editor "https://github.com/gipson-dev/labelprinterapp/blob/main/ui/ElementEditorWidget.cpp"
click node_preview "https://github.com/gipson-dev/labelprinterapp/blob/main/ui/PreviewWidget.cpp"
click node_template_model "https://github.com/gipson-dev/labelprinterapp/blob/main/core/LabelTemplate.h"
click node_label_element "https://github.com/gipson-dev/labelprinterapp/blob/main/core/LabelElement.h"
click node_printer_settings "https://github.com/gipson-dev/labelprinterapp/blob/main/core/PrinterSettings.h"
click node_template_storage "https://github.com/gipson-dev/labelprinterapp/blob/main/core/TemplateStorage.cpp"
click node_csv_importer "https://github.com/gipson-dev/labelprinterapp/blob/main/core/CsvImporter.cpp"
click node_variable_resolver "https://github.com/gipson-dev/labelprinterapp/blob/main/core/VariableResolver.cpp"
click node_zpl_generator "https://github.com/gipson-dev/labelprinterapp/blob/main/core/ZplGenerator.cpp"
click node_zebra_printer "https://github.com/gipson-dev/labelprinterapp/blob/main/core/ZebraPrinter.cpp"
click node_templates_dir "https://github.com/gipson-dev/labelprinterapp/tree/main/templates"
click node_sample_csv "https://github.com/gipson-dev/labelprinterapp/blob/main/examples/sample_items.csv"
click node_zpl_ref "https://github.com/gipson-dev/labelprinterapp/blob/main/docs/example_generated.zpl"
click node_label_ref "https://github.com/gipson-dev/labelprinterapp/blob/main/label.zpl"
click node_zpl_tests "https://github.com/gipson-dev/labelprinterapp/blob/main/tests/model_zpl_tests.cpp"
click node_build_scripts "https://github.com/gipson-dev/labelprinterapp/blob/main/scripts/build-and-test.ps1"

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_main toneBlue
class node_template_model,node_label_element,node_printer_settings,node_template_storage,node_csv_importer,node_variable_resolver,node_zpl_generator,node_zebra_printer toneAmber
class node_mainwindow,node_element_editor,node_preview toneMint
class node_templates_dir,node_sample_csv,node_zpl_ref,node_label_ref toneRose
class node_zpl_tests,node_build_scripts toneIndigo
```

## Components

### Application

Desktop entrypoint and build packaging

- [App entry](https://github.com/gipson-dev/labelprinterapp/blob/main/main.cpp): Qt app · Program startup and app bootstrap · `main.cpp`

### Core

Domain model and processing services

- [Label model](https://github.com/gipson-dev/labelprinterapp/blob/main/core/LabelTemplate.h): domain model · Template, element, and printer configuration data · `core/LabelTemplate.h`
- [Label element](https://github.com/gipson-dev/labelprinterapp/blob/main/core/LabelElement.h): domain model · Editable text, barcode, QR, and layout element definition · `core/LabelElement.h`
- [Printer settings](https://github.com/gipson-dev/labelprinterapp/blob/main/core/PrinterSettings.h): config model · Printer-specific output and device configuration · `core/PrinterSettings.h`
- [Template storage](https://github.com/gipson-dev/labelprinterapp/blob/main/core/TemplateStorage.cpp): json persistence · Loads and saves label templates from JSON files · `core/TemplateStorage.cpp`
- [CSV importer](https://github.com/gipson-dev/labelprinterapp/blob/main/core/CsvImporter.cpp): data ingest · Reads row data for batch printing · `core/CsvImporter.cpp`
- [Variable resolver](https://github.com/gipson-dev/labelprinterapp/blob/main/core/VariableResolver.cpp): placeholder engine · Resolves record fields and print-context variables · `core/VariableResolver.cpp`
- [ZPL generator](https://github.com/gipson-dev/labelprinterapp/blob/main/core/ZplGenerator.cpp): render pipeline · Transforms the label model into Zebra Programming Language · `core/ZplGenerator.cpp`
- [Zebra printer](https://github.com/gipson-dev/labelprinterapp/blob/main/core/ZebraPrinter.cpp): printer adapter · Sends raw ZPL directly to the configured Windows printer · `core/ZebraPrinter.cpp`

### UI

Qt desktop interface

- [Main window](https://github.com/gipson-dev/labelprinterapp/blob/main/ui/MainWindow.cpp): Qt shell · Primary tabbed workspace for design, data, print, templates, and settings · `ui/MainWindow.cpp`
- [Element editor](https://github.com/gipson-dev/labelprinterapp/blob/main/ui/ElementEditorWidget.cpp): property editor · Edits the selected label element properties · `ui/ElementEditorWidget.cpp`
- [Preview canvas](https://github.com/gipson-dev/labelprinterapp/blob/main/ui/PreviewWidget.cpp): label canvas · Interactive label layout and visual preview · `ui/PreviewWidget.cpp`

### Assets

Templates, sample data, and reference ZPL

- [Templates](https://github.com/gipson-dev/labelprinterapp/tree/main/templates): template library · Starter label definitions stored as JSON assets · `templates`
- [Sample CSV](https://github.com/gipson-dev/labelprinterapp/blob/main/examples/sample_items.csv): input example · Example batch data for printing · `examples/sample_items.csv`
- [ZPL reference](https://github.com/gipson-dev/labelprinterapp/blob/main/docs/example_generated.zpl): output sample · Example generated Zebra command output · `docs/example_generated.zpl`
- [Label sample](https://github.com/gipson-dev/labelprinterapp/blob/main/label.zpl): output sample · Reference ZPL label artifact · `label.zpl`

### Tooling

Tests and release automation

- [ZPL tests](https://github.com/gipson-dev/labelprinterapp/blob/main/tests/model_zpl_tests.cpp): test suite · Regression coverage for model-to-ZPL generation · `tests/model_zpl_tests.cpp`
- [Build scripts](https://github.com/gipson-dev/labelprinterapp/blob/main/scripts/build-and-test.ps1): packaging · Windows build, test, and release scripting · `scripts/build-and-test.ps1`

## Connections

- App entry → Main window: launches · Starts the desktop UI
- Main window → Element editor: edits · Routes element property editing through the side panel
- Main window → Preview canvas: shows · Hosts the interactive label preview
- Main window → Label model: binds · Operates on the current label template
- Element editor → Label element: updates · Modifies the selected element definition
- Preview canvas → Label element: positions · Supports drag-and-drop element placement
- Preview canvas → Label model: renders · Displays the current template state
- Template storage → Templates: reads/writes · Persists templates as JSON assets
- Template storage → Label model: loads · Materializes templates into domain objects
- CSV importer → Sample CSV: ingests · Reads batch input rows from CSV files
- CSV importer → Variable resolver: feeds · Supplies imported row data for placeholder resolution
- Variable resolver → Label model: fills · Resolves placeholders against the current template context
- Variable resolver → ZPL generator: prepares · Provides resolved values for output generation
- ZPL generator → Label model: converts · Transforms the label model into ZPL commands
- ZPL generator → ZPL reference: matches · Produces output comparable to the documented example
- ZPL generator → Label sample: matches · Produces output comparable to the reference artifact
- ZPL generator → Zebra printer: outputs · Generates raw ZPL for printer delivery
- Zebra printer → Build scripts: packages with · Distribution scripts bundle the Qt app and printer support
- ZPL tests → ZPL generator: verifies · Checks model-to-ZPL rendering behavior