# CLAUDE.md — Databrae

## Project Overview

Databrae is a PHP web application that generates printable library spine labels with Data Matrix 2D barcodes. It serves as a low-cost alternative to RFID for library inventory, shelf-reading, and weeding workflows. Licensed under GNU GPL v3.

## Tech Stack

- **Language**: PHP >= 8.1 (no framework — standalone)
- **Frontend**: HTML5, CSS3, vanilla JavaScript
- **Dependencies**: Composer — single dependency: `tecnickcom/tc-lib-barcode` ^2.4
- **Required PHP extensions**: BCMath, GD, PCRE
- **Database**: None (stateless, no persistence)
- **Tests**: None currently

## Project Structure

```
databrae/
├── index.php          # Single label generator (simple form)
├── index-csv.php      # Bulk CSV label generator with sheet templates
├── composer.json       # Dependency config
├── composer.lock
├── vendor/             # Composer dependencies (do not edit)
├── README.md
└── LICENSE
```

## Key Files

- **`index.php`** — Single-label mode. Form with 4 data fields + barcode field. Renders one Data Matrix barcode as inline SVG.
- **`index-csv.php`** — Advanced mode. CSV upload (auto-detects delimiter), sheet template system with customizable page/label dimensions, pagination. Required CSV headers: `data1, data2, data3, data4, barcode`.

## Coding Conventions

- `declare(strict_types=1)` used in index-csv.php
- **Variables**: snake_case (`$page_width_in`, `$csv_file`)
- **Functions**: snake_case (`safe()`, `strip_bom()`, `detect_delimiter()`)
- **CSS classes**: kebab-case (`.label-card`, `.barcode-block`)
- All user input escaped via `safe()` helper wrapping `htmlspecialchars(ENT_QUOTES, 'UTF-8')`
- Null coalescing (`??`) for safe defaults
- Barcodes rendered as inline SVG (not images)
- CSS uses physical units (`in`, `cm`) for print accuracy
- `@media print` rules hide UI and preserve label dimensions

## Common Tasks

```bash
# Install dependencies
composer install

# Run locally (PHP built-in server)
php -S localhost:8000
```

## Architecture Notes

- No routing — each PHP file is its own entry point
- No database or session state — all processing is per-request
- CSV files are processed in memory (10MB max upload)
- Sheet template parameters passed via POST, with sensible defaults (Demco 1.5"×1.0" on Letter)
- Error handling: validation errors collected in array, displayed as list; barcode generation wrapped in try-catch