ReceiptDesigner

ReceiptDesigner is a desktop template editor for designing, previewing, testing, and printing thermal receipt layouts.

It is built around a visual PySide6 interface that lets users place text, images, barcodes, QR codes, shapes, lines, and dynamic variables onto a receipt-style canvas, then save the design as a reusable JSON template or send it to an ESC/POS-compatible thermal receipt printer.

The project has been released publicly on GitHub: ByteAndConquer/receipt-designer.

Summary

ReceiptDesigner is meant for workflows where thermal receipt output needs to be consistent, repeatable, and easier to maintain than manually editing text, screenshots, or one-off print commands.

The project combines a visual layout editor, a structured template format, variable substitution, printer profiles, and direct print support for thermal receipt printer workflows.

The focus is specifically on thermal receipt printers, not product label design. The project may use barcodes, QR codes, images, and structured fields, but the target output is receipt-style printing through ESC/POS-oriented workflows.

In less polite terms: it exists because “just print a quick receipt” is how you accidentally summon a tiny document-formatting demon.

Why I built it

ReceiptDesigner started as a practical answer to a very specific problem: I needed an easier way to test thermal receipt printers.

I wanted to compare a few different printers and see which one worked best for my needs, but the available software did not really support the kind of ad-hoc testing I wanted to do. I needed something flexible enough to quickly design a receipt, send it to different printers, and compare the results using the same layout and settings.

Templates became an important part of that. By using reusable templates, I can send the same design to multiple printers and evaluate differences in output, formatting, spacing, readability, barcode behavior, QR code handling, and overall print quality.

Over time, the idea expanded beyond printer testing into a general-purpose thermal receipt utility.

ReceiptDesigner can support practical one-off and repeatable uses such as:

• Testing different thermal receipt printers with the same template
• Comparing print output across printer models or connection types
• Printing Wi-Fi QR codes or temporary credentials
• Creating quick shopping lists
• Printing recurring monthly bill checklists
• Making simple weekly or monthly task lists
• Building reusable receipt-style templates for small workflows
• Creating structured printouts without needing a full POS system

Receipt workflows often sit at an awkward intersection between design, structured data, hardware, and operational reliability.

A useful thermal receipt tool needs to care about things like:

• Precise layout
• Printer constraints
• Dynamic fields
• Repeatable formatting
• Barcode and QR output
• Template portability
• Missing asset behavior
• Printer configuration
• Error reporting
• Safe save and recovery behavior

ReceiptDesigner is designed around those practical concerns. It is not just a drawing surface. It is a tool for building print-ready, data-aware templates that can be reused, tested, and adapted across thermal receipt printers and everyday utility workflows.

What it does

ReceiptDesigner provides a desktop interface for building reusable thermal receipt templates.

Core capabilities include:

• Visual thermal receipt layout editing
• Text, image, barcode, QR code, shape, and line elements
• Dynamic template variables using {{var:variable_name}} syntax
• Built-in date and time variables
• Template save/load as JSON
• Autosave and crash recovery
• Undo/redo support
• Alignment, grouping, z-order, locking, nudging, and duplication tools
• Layers, properties, variables, and toolbox panels
• Print preview
• Printer profile management
• ESC/POS-compatible printing over network, USB, or serial connections

The goal is to make receipt-style layouts easier to build, revise, reuse, and print without requiring users to hand-edit raw printer commands or rebuild the same layout over and over like some sort of thermal-paper penance.

Key features

Visual template editor

The application provides a canvas-based editor for arranging thermal receipt elements visually. Users can add and modify text, images, barcodes, QR codes, shapes, and lines.

The editor includes supporting panels for layers, properties, variables, and tools so the layout can be adjusted without directly editing the underlying JSON.

Dynamic variables

Templates can include user-defined variables with syntax like:

{{var:customer_name}}
{{var:order_number}}
{{var:item_count}}

Values are managed through the Variables panel and saved with the template.

ReceiptDesigner also supports built-in system variables such as:

{{date}}
{{time}}
{{datetime}}
{{year}}
{{month}}
{{month_name}}
{{day}}
{{weekday}}
{{hour}}
{{minute}}
{{second}}

This makes templates reusable instead of hardcoding every little value like a goblin with a deadline.

Images and portable paths

Images can be added to templates from disk. Images stored inside the same template folder can be saved with relative paths, making the template folder portable.

Images outside the template folder remain absolute paths. Missing images display a placeholder rather than breaking the whole template.

That behavior matters because file paths will betray you the moment a folder is moved. This project plans for that betrayal.

Barcodes and QR codes

ReceiptDesigner supports barcode and QR elements for thermal receipt workflows.

The project uses:

• python-barcode for one-dimensional barcode generation
• qrcode for QR codes
• Optional treepoem and Ghostscript support for advanced 2D barcode formats such as PDF417, DataMatrix, and Aztec

Autosave and crash recovery

Unsaved work is periodically autosaved to a temporary file. Writes are handled atomically to reduce the risk of corrupting saved data if the app is interrupted.

On relaunch after a crash or forced close, the app can prompt to restore recovered work.

This is the kind of feature nobody notices until the one time it saves them from screaming into a folder.

Printer profiles

ReceiptDesigner supports multiple printer profiles and remembers the active profile by name across sessions.

Supported printer connection paths include:

• Network printing, commonly raw socket printing on port 9100
• USB printing through pyusb
• Serial printing through pyserial
• ESC/POS printing through python-escpos
• Dry-run style test paths for safer development and validation

Printer configuration supports common ESC/POS and device settings, including host, port, serial port, baud rate, USB identifiers, timeout, darkness, threshold, cut mode, and related options.

Recent files

The app tracks recently opened templates and normalizes paths to reduce duplicates caused by casing or slash differences.

If a recent file no longer exists, the user can remove it from the list instead of keeping a haunted shortcut to nowhere.

Template format

Templates are JSON files containing page settings, element definitions, and variable bindings.

At a high level, the template model covers:

• Page dimensions
• Margins and layout settings
• Element definitions
• Element position and size
• Text, image, barcode, QR, shape, and line metadata
• Variable values
• Compatibility fields for forward/backward-safe loading

The template model is designed so saved layouts can be reloaded, edited, printed, and evolved over time.

Printing pipeline

ReceiptDesigner separates the design canvas from the printing backend.

The general flow is:

Template / scene
  -> render pipeline
  -> print preview or bitmap output
  -> printer worker
  -> selected printer backend
  -> device or dry-run path

This separation keeps layout editing, rendering, and transport-specific printer behavior easier to reason about.

Technical architecture

ReceiptDesigner uses a modular desktop application structure.

The project is organized around:

• receipt_designer/core/ for data models, rendering helpers, barcode logic, utility code, and undo/redo command objects
• receipt_designer/ui/ for the PySide6 user interface, canvas, docks, dialogs, persistence helpers, layout operations, and editor workflows
• receipt_designer/printing/ for printer backends, worker thread behavior, profiles, and print-specific exception handling
• tests/ for core unit tests and optional Qt-gated UI/integration smoke tests

The UI uses a coordinator-and-extracted-module pattern. The main window acts as the central coordinator, while feature areas such as actions, persistence, presets, layout operations, dialogs, docks, and canvas behavior are separated into focused modules.

That structure keeps the application from becoming one enormous “main window of doom,” which is a real thing and it knows what it did.

Testing and quality work

The project includes a practical test suite covering core behavior, print pipeline behavior, path handling, profile persistence, command behavior, template serialization, variable handling, and UI smoke tests.

Test coverage areas include:

• Template and element serialization
• Variable parsing and resolution
• Portable image path behavior
• Print rendering and dry-run paths
• Printer configuration flow
• Printer profile persistence and migration
• Undo/redo command behavior
• Scene item reconstruction
• Shared UI helper edge cases
• Qt-gated UI smoke tests
• Autosave and recovery behavior

Qt integration and UI smoke tests can run in offscreen mode, making them safer to run in headless or CI-style environments.

Packaging and release direction

ReceiptDesigner includes PyInstaller packaging support and can be built into a single-file Windows executable.

The package metadata identifies the project as a desktop tool for designing and printing ESC/POS receipts. The current project version in the package metadata is 0.9.5.

The packaging work is important because the target use case is not just “developer runs Python script.” The goal is a practical desktop utility that can be launched, used, and distributed more easily.

Security and trust model

ReceiptDesigner is a desktop application that works with local template files, local image assets, and printer connection settings.

The security model is focused on practical desktop risks, including:

• Malicious or malformed template JSON files
• Image or asset path handling
• Unsafe deserialization risks
• Printer backend communication issues
• Network, USB, and serial device configuration

The project avoids treating templates as magic executable blobs. Template data is loaded through structured model logic, and printing errors are intended to flow through friendly and technical error reporting paths.

What it demonstrates

ReceiptDesigner is useful as a portfolio project because it brings together UI design, document modeling, hardware-adjacent workflows, and practical release engineering.

It demonstrates:

• Python desktop application development
• PySide6 UI architecture
• Visual editor design
• JSON template modeling
• Dynamic variable substitution
• Barcode and QR code generation
• Print preview and rendering logic
• ESC/POS thermal receipt printer integration
• Network, USB, and serial printer configuration
• Autosave and crash recovery patterns
• Recent-file and profile persistence
• Modular UI refactoring
• Testable architecture planning
• Packaging with PyInstaller
• Documentation and contributor guidance

Repository

ReceiptDesigner is available on GitHub at ByteAndConquer/receipt-designer.

Publishing the repository makes the project easier to review as part of a portfolio: the code, structure, documentation, tests, packaging approach, and project direction can be inspected directly instead of being summarized only on this page.

Current status

ReceiptDesigner is an active desktop application project that has been released publicly on GitHub. It has a working architecture, documented setup flow, printer profile support, template persistence, rendering pipeline, and test coverage.

The project is beyond the “idea scribbled on a napkin” phase. It has enough structure to show real application design, and the public repository provides a place to track continued refinement as the tool evolves.

Future direction

The project is still evolving, but I have not locked in a formal roadmap yet. Near-term updates will likely focus on documenting the released GitHub project more clearly and adding examples as the tool matures.

Skills demonstrated

• Desktop application development
• UI architecture and modular refactoring
• Structured data modeling
• Template persistence
• Print workflow design
• Thermal receipt printer integration
• Hardware/software integration thinking
• Test planning
• Release packaging
• Documentation discipline
• Practical tool design for operational workflows