Demo Overview

Welcome! This page is a Table of Contents for the TTB COLA Label Validator prototype. Every page, API endpoint, and key feature is listed below with a brief summary. Click any card to jump directly to that section of the app.

Pages

API Endpoints

107

Unit Tests

15+

Components

Core Features

The primary pages that deliver the TTB label validation workflow

Home

Upload a beverage label image via drag-and-drop or file picker. The system validates compliance against TTB requirements and displays pass/fail results with regulatory citations.

uploadvalidationdrag & drop

Label Editor

Advanced label processing workspace with perspective correction (4-point & mesh warp), cylindrical unwrap, surface curvature controls, OCR text extraction (Tesseract + AI), auto-flatten, sharpen, multi-label split, and export.

perspectiveOCRmesh warpmulti-label

Review Queue

Dashboard listing all submitted labels pending agent review. Filterable by status (submitted, in review, approved, rejected), beverage category, and search. Includes batch stats and real-time refresh.

dashboardfilteringstatus tracking

Test Label Generator

Generate realistic test label images using Gemini AI. Choose from 10 presets (bourbon, IPA, cabernet, vodka, etc.) or write a custom prompt. Supports front/back labels, generation history, download, and send-to-simulator.

AI generationpresetsGemini

Review Pipeline

Agent profiles, individual submission review, and performance analytics

Review Agents

Agent profiles showing name, title, division, specialties, certifications, and availability status. Each card displays lifetime performance stats (reviews, approvals, rejections, avg review time) plus recent activity.

profilesstatsperformance

Submission Review

Click any submission in the queue to open a detailed review page. Agents can examine all submitted labels, view OCR results, check the compliance checklist, compare fields against the COLA form, and render approve/reject/needs-revision decisions.

reviewOCR resultsdecisions

Developer Tools

API testing, component showcase, and interactive walkthrough

API Test Console

Interactive endpoint tester with a sample label gallery. Select an endpoint (OCR, flatten, explain, queue, generate), pick a sample image, and see the raw JSON response. Great for exploring the API without Postman.

APIinteractiveJSON viewer

Component Demo

Visual showcase of all design tokens (colors, typography), button variants, status badges, card patterns, form elements, alert types, and a complete API endpoint reference table.

design systemtokensshowcase

Guided WalkthroughClick the ? button (bottom-left on the Label Editor) for an 8-step interactive tutorial that highlights each feature with a sliding side panel.

Legacy Style Variants

The same features rendered in the original Tailwind dark-mode styling (pre-TTB.gov redesign)

Legacy Editor

Full label editor with Tailwind styling.

editor

Legacy Queue

Review queue with original dark theme.

queue

Legacy Generator

Label generator with original styling.

generator

REST API Endpoints

All backend routes available for label processing, review, and administration

Method	Endpoint	Description
POST	/api/ocr	Extract text from a label image via OpenRouter Claude 3.5 Sonnet vision model
POST	/api/flatten	AI-powered cylindrical/perspective label flattening via AWS Lambda
POST	/api/explain	LLM-generated regulatory explanation for failed validation rules
GET	/api/generate-label	List available COLA presets for test label generation
POST	/api/generate-label	Generate a realistic label image using Gemini AI
GET	/api/queue	List all submissions with optional status/category filters
POST	/api/queue	Create a new submission from the label editor
GET	/api/queue/[id]	Fetch a single submission with all labels and reviews
POST	/api/queue/[id]	Submit a review decision (approve / reject / needs revision)
GET	/api/queue/seed	Seed the in-memory store with mock submission data
GET	/api/admin/agents	List all review agents with profile and stats
GET	/api/admin/stats	Aggregate queue statistics (counts by status, category)
GET	/api/admin/stats/[agentId]	Detailed performance stats for a specific agent

Key Capabilities

Notable technical features implemented across the application

Two-Tier OCR

Browser-side Tesseract.js for instant results, plus server-side Claude 3.5 Sonnet for high-accuracy extraction.

Perspective Correction

4-point homography and multi-point mesh warp with spline interpolation for curved label surfaces.

Cylindrical Unwrap

Automatic curvature estimation with vertical/horizontal cylinder axis and cross-curvature (bow) adjustment.

Category-Aware Validation

Rules engine with presence, format, and cross-field checks tailored to beer, wine, and spirits requirements.

Fuzzy Field Matching

Levenshtein-distance comparison between OCR-extracted text and COLA form fields with exact/match/close/mismatch verdicts.

Auto-Flatten + Smart Crop

One-click corner detection, curvature estimation, and label cropping from raw photos.

Multi-Label Split

Detects and separates front/back labels from a single image into individual slots.

Batch Upload

Multi-file queue processing with CSV export of OCR results and validation outcomes.

Interactive Walkthrough

8-step guided tutorial with element highlighting and a sliding side panel, triggered by the ? FAB.

107 Unit Tests

Vitest test suite covering validation rules, OCR parsing, fuzzy matching, store operations, and agent stats.

Tech Stack

Technologies and libraries powering the application

Next.js 14

App Router, RSC

TypeScript

Strict mode

React 18

Client components

TailwindCSS

Utility-first styling

Vitest

107 unit tests

Tesseract.js

Browser-side OCR

Claude 3.5 Sonnet

Server OCR via OpenRouter

Gemini AI

Label image generation

AWS Lambda

Backend processing

Vercel

Deployment & hosting

Lucide Icons

Icon library

ESLint + Prettier

Linting & formatting

Coding Practices Applied

10 systematic improvements implemented across the codebase

Error & Loading Boundaries

Next.js error.tsx, not-found.tsx, loading.tsx for graceful error handling

Accessibility

Skip-nav, aria-labels, aria-live regions, aria-current, table captions

Prettier Config

Consistent code formatting across the entire codebase

Type Safety

Tightened Record<string,...> maps to union key types (BeverageCategory, Verdict, etc.)

API Route Tests

19 new tests for in-memory store and agent store (107 total)

Error Handling

Fixed bare catch {} blocks with bound error variables and structured logging

Layout Constants

Extracted repeated magic numbers into L layout token object

Component Decomposition

Decomposed legacy/page.tsx (2,094 → 1,394 lines) by extracting LegacyControlPanel

Logging Utility

Thin lib/logger.ts with environment-aware, level-gated, tagged output

ESLint Import Sorting

import/order rule enforcing consistent import grouping and alphabetization