BarcodeLabelGen

Project Overview

A self-hosted web application that lets non-technical office staff design label templates in a drag-and-drop Konva editor — text, images, barcodes (EAN-13/14, Code 128, GS1-128, QR), and dynamic {{placeholders}} — then batch-generate up to 1,000 PDF labels per run by mail-merging from CSV, Excel, or even a SQLite database with a custom SELECT.

Ships as Docker + nginx + Postgres + Redis behind Tailscale Serve, fully bilingual (Polish + English) with in-app HELP/FAQ and role-based access (admin / editor / viewer). Production-ready with 172/172 backend tests passing.

Hosted Demo

A live, public demo runs the full application — design a label template in the drag-and-drop Konva editor, then batch-generate PDFs by mail-merging from a bundled sample dataset. Each visitor gets a private demo workspace, pre-loaded with example templates, that resets after 30 minutes of inactivity.

The Problem

Office staff needed to print labels — product tags, shelf edge labels, asset stickers — but commercial label software was either expensive per seat, single-user desktop-only, or locked label files in proprietary binary formats. Every catalogue update meant manually redoing each label, and there was no way to drive a batch print from a live database or an updated spreadsheet without paying for an enterprise tier.

The Solution

A self-hosted browser app where any authorised user can design a template once and then mail-merge hundreds of variants from a spreadsheet or a live database. Templates export as a self-contained .blg-template.json file (objects plus embedded base64 images) and import cleanly into any installation. The whole stack runs from one docker compose up on a Linux host fronted by Tailscale Serve, so it's instantly reachable over a private tailnet with zero-config HTTPS.

Drag-and-Drop Editor

Konva canvas with mm-precise positioning, multi-select, Alt-drag duplicate, align + distribute tools, lockable objects, and non-printable reference images for aligning against pre-printed sheets.

Templates library with import/export, tag filtering, and per-template thumbnails. New templates start from a page-format preset or a duplicate of an existing one.

Mail-Merge from CSV, Excel, or SQLite

Four-step Generate Series wizard: upload data file → map placeholders → preview rows → generate PDF batch (up to 1,000 labels per run).

SQLite mode with table picker and a sandboxed custom-SELECT validator that rejects multi-statement queries and blocks INSERT/UPDATE/DELETE/DROP/ATTACH/PRAGMA.

Placeholder Mapping & Auto-Map

Automatic placeholder-to-column matching by name similarity — every {{token}} in the template is paired with the closest column in the imported file.

Manual override picker for any unmatched fields, with live preview of the substituted values for each row.

Generated PDF Output

Rendered ReportLab PDF (row 5 of 60) with EAN-13 barcode, QR code, and merged text — pixel-accurate to the editor preview thanks to a Konva-pixel ↔ ReportLab-mm coordinate bridge.

Template Import & Export

Partial-import modal — each imported object shows its placeholder flag, embedded images are SHA-256-deduplicated against the existing asset store, and the user picks per-object whether to drop on the current page or land as a new template.

Dashboard

Post-login dashboard with quick actions (new template, generate series, import) and recent activity per user.

Sample Dataset

Example source dataset — the kind of input the mail-merge engine consumes. Headers become placeholder candidates; each row becomes one rendered label.

Key Features

• Konva-powered drag-and-drop editor with mm-precise positioning, multi-select, Alt-drag duplicate, align + distribute tools
• Dynamic {{placeholders}} substituted from imported data; lockable objects; non-printable reference images for alignment against pre-printed sheets
• Barcode engine: EAN-13, EAN-14, GTIN, Code 128, GS1-128, QR — with checksum validation
• Mail-merge from CSV, Excel, or SQLite — including a sandboxed custom-SELECT mode with statement validator
• Self-contained .blg-template.json export/import (objects + embedded base64 images), with partial-import and SHA-256 image deduplication
• Bilingual UI (Polish + English) with in-app HELP and FAQ rendered from markdown
• Role-based access (admin / editor / viewer) with admin password resets
• Pre-built page formats: A4 / A5 / A6, Zebra 4×6" / 4×4" / 3×2" / 2×1", plus arbitrary custom mm
• Up to 1,000 PDF labels per generation batch
• One-command Docker Compose deploy fronted by Tailscale Serve for zero-config HTTPS

My Role

Full-stack development — React 18 + TypeScript + Vite + Konva editor frontend; Flask 3 + SQLAlchemy 2 + ReportLab + python-barcode backend; PostgreSQL 16 schema with Alembic migrations; Redis-backed sessions and job queue; a pytest harness covering 172 backend tests; the Docker Compose stack with nginx; and the Tailscale Serve deployment recipe. Designed around two distinct user personas — office staff who only need to generate a batch from an existing template, and template authors who need full editor control.

Technology Used

Challenges and Learning

Building a safe SQL-import mode meant designing a single-statement validator with a keyword blocklist and prepared parameterisation, so users could write expressive SELECT queries without ever being given raw query access to the host database. Coordinating Konva's pixel-space coordinate system with ReportLab's mm-space PDF output required a coordinate bridge that keeps the editor preview 1:1 with the printed result across every page format. The partial-import flow needed careful thought too — it has to handle placeholder collisions between the incoming template and the active page, and deduplicate embedded image assets via SHA-256 so the same logo isn't stored five times after five imports.

Outcome / Value

A production-ready self-hosted alternative to commercial label software, deployed onto a single Docker host over Tailscale. 172/172 backend tests pass; frontend typecheck, lint, and build are all clean (153 KB main bundle, 47 KB gzipped). Active development under GPL-3.0, with Dependabot, secret-scanning, and push-protection enabled on the repo.