QR Code Generation: Deterministic Payload Encoding for Badge Workflows

QR code generation operates as a strict transformation boundary within the badge production pipeline. It consumes normalized attendee records, applies cryptographic or sequential payload encoding, and emits rasterized or vectorized assets ready for downstream composition. This stage must remain stateless, idempotent, and strictly bounded to prevent latency bleed into Badge Generation & Template Sync or downstream dispatch layers. By isolating encoding logic from layout and routing concerns, event tech teams can scale badge production to tens of thousands of records without introducing template drift or print queue bottlenecks.

Explicit Data Contract & Ingress Validation Link to this section#

The generation boundary expects a rigid input schema. Deviations must be rejected or normalized before encoding begins. The canonical contract enforces type safety, length constraints, and explicit enum validation:

Input validation occurs at the service ingress. Malformed payloads trigger a 400 Bad Request with a structured error envelope containing field paths and violation reasons. Valid payloads are passed to the encoding engine. This normalization layer typically relies on Dynamic Field Mapping to reconcile upstream registration payloads with the strict schema required for deterministic QR generation. Rejecting invalid data at the boundary prevents silent corruption downstream and simplifies audit trails.

Deterministic Payload Construction & Capacity Limits Link to this section#

QR codes must encode payloads that are both machine-readable and cryptographically verifiable. A deterministic format ensures that identical inputs always produce identical outputs, enabling cache hits and idempotent retries.

{event_slug}|{attendee_id}|{check_in_token}|{access_tier}

Payload capacity is governed by ISO/IEC 18004 standards and scales inversely with error correction levels. Alphanumeric payloads can safely reach ~2,953 bytes at L correction, but badge workflows typically target <128 bytes to maintain fast scan times on mobile and dedicated scanners. Before encoding, the pipeline must:

1. Validate total byte length against the selected error correction tier.
2. Strip non-ASCII characters or transliterate them to prevent UnicodeEncodeError during rasterization.
3. Enforce a hard timeout to prevent blocking worker threads during high-volume batch runs.

Production-Ready Python Implementation Link to this section#

The encoding step prioritizes throughput, memory safety, and deterministic output. The following implementation uses segno for high-speed QR generation, enforces explicit error correction, returns base64-encoded assets, and attaches audit metadata. It includes structured fallbacks for oversized payloads and explicit exception routing for fast incident resolution.

import segno
import base64
import hashlib
import logging
from typing import Dict, Any, Optional
from dataclasses import dataclass
from enum import Enum
import io

logger = logging.getLogger(__name__)

class QRErrorCorrection(str, Enum):
    L = "L"
    M = "M"
    Q = "Q"
    H = "H"

@dataclass
class QRGenerationResult:
    payload_b64: str
    mime_type: str
    width_px: int
    height_px: int
    checksum: str
    error_correction: str
    fallback_applied: bool = False

def _build_payload(data: Dict[str, Any]) -> str:
    return f"{data['event_slug']}|{data['attendee_id']}|{data['check_in_token']}|{data['access_tier']}"

def _calculate_checksum(raw_bytes: bytes) -> str:
    return hashlib.sha256(raw_bytes).hexdigest()[:16]

def generate_badge_qr(
    data: Dict[str, Any],
    size: int = 300,
    ec_level: QRErrorCorrection = QRErrorCorrection.M
) -> QRGenerationResult:
    raw_payload = _build_payload(data)
    
    # Capacity guardrail: ~400 chars max for reliable mobile scanning at M/H levels
    if len(raw_payload.encode('utf-8')) > 400:
        logger.warning(
            "Payload exceeds safe capacity threshold. Downgrading EC level to L.",
            extra={"attendee_id": data.get("attendee_id"), "length": len(raw_payload)}
        )
        ec_level = QRErrorCorrection.L

    try:
        qr = segno.make_qr(raw_payload, error=ec_level.value, micro=False)
        buf = io.BytesIO()
        qr.save(buf, kind="png", scale=10, border=2)
        buf.seek(0)
        raw_bytes = buf.read()
        
        return QRGenerationResult(
            payload_b64=base64.b64encode(raw_bytes).decode("utf-8"),
            mime_type="image/png",
            width_px=size,
            height_px=size,
            checksum=_calculate_checksum(raw_bytes),
            error_correction=ec_level.value,
            fallback_applied=(ec_level == QRErrorCorrection.L)
        )
    except segno.exceptions.DataOverflowError as exc:
        logger.error(
            "QR data overflow. Payload too large for selected EC level.",
            extra={"attendee_id": data.get("attendee_id"), "error": str(exc)}
        )
        raise RuntimeError(f"QR encoding failed for {data['attendee_id']}: payload exceeds capacity limits") from exc
    except Exception as exc:
        logger.critical(
            "Unexpected QR generation failure.",
            extra={"attendee_id": data.get("attendee_id"), "error_type": type(exc).__name__}
        )
        raise RuntimeError(f"QR encoding failed for {data['attendee_id']}: {exc}") from exc

Key production considerations:

• Memory Safety: io.BytesIO() avoids disk I/O and prevents file descriptor leaks in containerized workers.
• Deterministic Output: Identical inputs yield identical base64 strings and checksums, enabling CDN caching and deduplication.
• Explicit Fallback: Automatic EC level downgrade triggers a fallback_applied flag, allowing downstream systems to adjust print resolution or scanner sensitivity.
• Structured Logging: Correlation IDs and payload metadata are attached to log records for rapid triage during peak registration windows.

Debugging, Fallbacks & Incident Resolution Link to this section#

Fast incident resolution in badge workflows depends on observable failure boundaries. When QR generation fails, operators should follow this triage path:

1. Check Payload Length & Encoding: DataOverflowError indicates upstream field bloat. Verify that check_in_token isn’t accidentally concatenating full JWTs or unhashed payloads.
2. Validate Error Correction Tier: High correction (Q, H) reduces capacity. If scans fail at distance, temporarily switch to M or L and re-run.
3. Inspect Checksum Mismatches: A mismatched checksum between generation and print dispatch signals pipeline corruption or base64 truncation. Verify that downstream consumers decode using base64.b64decode() without stripping padding.
4. Fallback Routing: If generation fails after EC downgrade, route the record to a manual review queue with a placeholder QR asset. Never block the entire batch on a single malformed attendee record.

For deeper protocol validation, reference the official ISO/IEC 18004:2015 specification to align capacity limits with scanner hardware capabilities.

Downstream Handoff & Pipeline Boundaries Link to this section#

This stage strictly emits encoded assets and metadata. It does not perform layout composition, typography rendering, or PDF assembly. Those responsibilities belong to Badge Generation & Template Sync, which consumes the base64 payload, embeds it into vector templates, and applies bleed/trim marks. Once composed, assets enter PDF Routing Workflows for print queue distribution, thermal label dispatch, or digital wallet delivery.

Maintaining this boundary prevents template drift and ensures that QR generation remains horizontally scalable. If print latency spikes, isolate the bottleneck by measuring generation throughput separately from composition and routing. The checksum field enables end-to-end verification without re-encoding, reducing redundant compute during retry cycles.