Barcodes Module

Overview

The barcodes module provides centralized barcode lifecycle management for the FlowPOS platform. It handles barcode lookup, uniqueness validation, assignment history tracking, print tracking, and a management dashboard — across both simple products and product variants.

Domain Concepts

Concept	Description
Barcode Lookup	Unified search across product_variant and product tables by barcode value
Barcode Assignment	Audit trail of barcode assignments and retirements stored in barcode_assignment
Barcode Uniqueness	Validation that a barcode value is not already in use within a business
Print Tracking	Counters for how many labels have been printed per entity
Management Dashboard	Paginated view of all entities with their barcode status

Barcode Types

• ean13 — EAN-13 (international standard)
• upca — UPC-A (North America)
• code128 — Code 128 (alphanumeric)
• qr — QR code

Barcode Sources

• internal — Generated by the system
• external — Scanned or imported from manufacturer/supplier

Barcode Statuses

• active — Currently in use
• retired — Previously used, now replaced

Architecture

barcodes/
├── barcodes.module.ts                          # NestJS module
├── domain/
│   ├── barcodes-service.domain.ts              # Service interface (port)
│   ├── barcodes-repository.domain.ts           # Repository interface (port)
│   └── barcodes.constants.ts                   # Entity types, status filters
├── application/
│   └── barcodes.service.ts                     # Use cases (implements IBarcodesService)
├── infrastructure/
│   └── barcodes.repository.ts                  # Kysely queries (implements IBarcodesRepository)
└── interfaces/
    ├── barcodes.controller.ts                  # HTTP endpoints
    └── dtos/
        ├── barcode-lookup.query.ts             # GET /barcodes/lookup
        ├── barcode-management.query.ts         # GET /barcodes/management
        ├── barcode-history.query.ts            # GET /barcodes/history/:entityType/:entityId
        ├── validate-uniqueness.dto.ts          # POST /barcodes/validate-uniqueness
        └── print-tracking.dto.ts               # POST /barcodes/print-tracking

Dependency flow: Controller → Service → Repository → Database

The domain layer (domain/) contains only interfaces and constants — no framework dependencies.

Key Use Cases

1. Barcode Lookup (POS scanning)

GET /barcodes/lookup?businessId=...&barcode=...&includeRetired=false

1. Search product_variant for an active barcode match
2. If found, enrich with variant options (size, color, etc.)
3. If not found, search product (simple products without variants)
4. If includeRetired=true and still not found, search barcode_assignment history
5. Return entity details or 404

2. Uniqueness Validation

POST /barcodes/validate-uniqueness

1. Check product_variant for the barcode value (exclude current entity if editing)
2. Check product for the barcode value
3. Return { isAvailable: true } or { isAvailable: false, conflictEntity: {...} }

3. Assignment History

GET /barcodes/history/:entityType/:entityId?businessId=...

Returns the full audit trail of barcode assignments for a product or variant, ordered by most recent.

4. Print Tracking

POST /barcodes/print-tracking

Batch-updates barcode_print_count and barcode_last_printed_at on the entity tables.

5. Management Dashboard

GET /barcodes/management?businessId=...&page=1&limit=50

UNION ALL query across variants and products, with filters for status, source, type, and search. Returns total count and unassigned count for dashboard metrics.

API Endpoints

Method	Path	Permission	Description
GET	/barcodes/lookup	Barcode:Read	Look up a barcode value
GET	/barcodes/management	Barcode:Read	Paginated management list
POST	/barcodes/validate-uniqueness	Barcode:Read	Check barcode availability
GET	/barcodes/history/:entityType/:entityId	Barcode:Read	Assignment history
POST	/barcodes/print-tracking	Barcode:Update	Update print counters

Cross-Module Usage

The barcodes service exports two helper methods used by other modules:

• createAssignment() — Called by product-variants and products modules when assigning a barcode
• retireAssignment() — Called when a barcode is replaced or removed

These methods write to the barcode_assignment table to maintain the audit trail.

Bruno API Collection

See api-client/flowpos/collections/barcodes/:

File	Description
lookup-barcode.yml	Look up a barcode
management-list.yml	Paginated management list
validate-uniqueness.yml	Check barcode uniqueness
assignment-history.yml	Get assignment history
print-tracking.yml	Update print counters

Design Decisions

1. UNION ALL for management list — Variants and simple products are stored in separate tables. The management endpoint uses a UNION ALL subquery for a unified view with consistent pagination.

2. Barcode on entity, not join table — Active barcodes are stored directly on product_variant.barcode and product.barcode for fast POS lookups. The barcode_assignment table is an audit log, not the source of truth for active barcodes.

3. Print tracking on entity tables — Print counters live on the product/variant tables to avoid an extra join during label generation queries.

4. No dedicated barcode entity — Barcodes are attributes of products/variants, not standalone entities. The module aggregates barcode-related operations across these tables.