# Best Barcodes - Extended Agent & Developer Technical Reference

> Complete technical architecture, math models, calibration protocols, and barcode engine specifications for Best Barcodes (https://bestbarcodes.com).

## 1. System Overview

Best Barcodes is a 100% client-side web application deployed to Cloudflare Pages static edge network. It runs without Node.js backend servers, serverless compute, or external database queries during label generation.

- **Frontend Core**: Vanilla HTML5, CSS Grid, and Modern ES Modules (ES2022+).
- **Self-Hosted Vendor Dependencies**:
  - `vendor/bwip-js-min.js`: Barcode Writer in Pure PostScript vector engine.
  - `vendor/papaparse.min.js`: Fast multi-threaded streaming CSV parser.
  - `vendor/xlsx.full.min.js`: SheetJS Excel workbook parser (.xlsx / .xls).
  - `vendor/jspdf.umd.min.js`: Vector and canvas client-side PDF document generator.
- **Privacy Guarantee**: All spreadsheet processing, barcode generation, and PDF rendering occur in volatile browser memory. Zero network payloads are transmitted with user inventory data.

## 2. Avery Template Grid Geometry & Mathematical Model

All label sheets are calibrated to standard US Letter paper (8.5 inches × 11.0 inches = 215.9 mm × 279.4 mm).

### Template Dimensions Table

| Template ID | Product Name | Columns | Rows | Total Labels | Label Width | Label Height | Col Gap | Row Gap | Top Margin | Left Margin |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `avery-6870` | Avery 6870 (Address / Barcode) | 3 | 10 | 30 | 57.15 mm (2.25") | 19.05 mm (0.75") | 3.81 mm (0.15") | 0.00 mm (0.00") | 15.875 mm (0.625") | 9.525 mm (0.375") |
| `avery-5195` | Avery 5195 (Mini Barcode / Return) | 4 | 15 | 60 | 44.45 mm (1.75") | 16.76 mm (0.66") | 7.62 mm (0.30") | 0.00 mm (0.00") | 14.224 mm (0.560") | 7.620 mm (0.300") |
| `avery-5160` | Avery 5160 / 8160 (Address) | 3 | 10 | 30 | 66.68 mm (2.625") | 25.40 mm (1.00") | 3.56 mm (0.14") | 0.00 mm (0.00") | 12.700 mm (0.500") | 4.826 mm (0.190") |
| `avery-5163` | Avery 5163 / 8163 (Shipping) | 2 | 5 | 10 | 101.60 mm (4.00") | 50.80 mm (2.00") | 3.56 mm (0.14") | 0.00 mm (0.00") | 12.700 mm (0.500") | 4.064 mm (0.160") |
| `avery-5167` | Avery 5167 / 8167 (Return Address) | 4 | 20 | 80 | 44.45 mm (1.75") | 12.70 mm (0.50") | 7.62 mm (0.30") | 0.00 mm (0.00") | 12.700 mm (0.500") | 7.620 mm (0.300") |

### Grid Alignment Verification Formula

For any valid sheet configuration:
- Horizontal sheet width constraint: `marginLeft + (cols * labelWidth) + ((cols - 1) * colGap) <= 215.9 mm (8.5 inches)`
- Vertical sheet height constraint: `marginTop + (rows * labelHeight) + ((rows - 1) * rowGap) <= 279.4 mm (11.0 inches)`

## 3. Micro-Calibration CSS Variable Engine

Physical printer rollers routinely drift by 0.5 mm to 3.0 mm. Best Barcodes binds calibration inputs directly to CSS root and container properties:

- `--page-margin-top`: Shifts the entire CSS Grid vertically down or up.
- `--page-margin-left`: Shifts the entire CSS Grid horizontally right or left.
- `--inner-offset-x`: Nudges content inside individual label cells (`transform: translate(var(--inner-offset-x), var(--inner-offset-y))`).
- `--inner-offset-y`: Vertical fine adjustment inside label boundaries.
- `--name-font-size`: Adjusts product name typography scale (5pt to 14pt).
- `--barcode-width`: Toggles between fixed centered width (84%) and edge-to-edge stretch (94%).

## 4. Retail GS1 Barcode Engineering (UPC-A & EAN-13)

### EAN-13 Outer Digit Optimization

Raw BWIPP generates EAN-13 with an excessive outer first-digit offset (`text1xoffset = -7.75` modules) and zero right quiet zone margin, resulting in a detached floating "1" and an off-center visual barcode.

Best Barcodes applies a geometric vector post-processor (`BarcodeEngine.optimizeRetailSvg`):
1. Detects `effectiveBcid === 'ean13'` with 13 text glyph paths.
2. Identifies the leftmost guard bar (`stroke-width = 2` at scale 2).
3. Translates Digit 0 (`<g transform="translate(shiftX, 0)">`) so its right boundary is placed exactly `1.2 * strokeWidth` from the first bar, eliminating the floating digit gap.
4. Symmetrizes the right quiet zone to mirror the left margin, setting `viewBox="0 0 234 59"`, ensuring exact visual centering.

### UPC-A 12-Digit Retail Auto-Routing

When users provide 12-digit numeric codes under the retail preset, Best Barcodes routes to `upca` to preserve the standard GS1 1-5-5-1 wrapped digit layout (outside leading system digit and outside trailing check digit) without generating spurious check characters.

## 5. Storage Engine & URL Sharing Schema

Calibrations can be exported as base64-encoded URL parameters for team sharing:
- URL Format: `https://bestbarcodes.com/#preset=<base64-json>`
- Schema payload:
```json
{
  "templateId": "avery-6870",
  "barcodeType": "ean13",
  "stretch": false,
  "unit": "mm",
  "calibration": {
    "pageMarginTop": 15.875,
    "pageMarginLeft": 9.525,
    "innerOffsetY": 0,
    "innerOffsetX": 0,
    "nameFontSize": 7.5,
    "barcodeHeight": 7
  }
}
```

## 6. Print Media Query Architecture

```css
@media print {
  @page {
    size: letter portrait;
    margin: 0;
  }
  body {
    background: transparent;
    print-color-adjust: exact;
    -webkit-print-color-adjust: exact;
  }
  .no-print {
    display: none !important;
  }
  .sheet {
    page-break-after: always;
    break-after: page;
  }
}
```