Create Your Own QR Code Service

Build instructions designed for LLMs and AI coding agents (like Cursor). Copy the instructions below and paste them into your IDE with an agent to build your own QR code service with hardcoded URLs and password protection.

Build Instructions

# QR Code Service - Build Instructions for LLM/AI Agent

These instructions are designed to be pasted into an IDE with an AI coding agent (like Cursor) to build a complete QR code service.

## Stack
Next.js 16.0.3, React 19.2.0, TypeScript 5, Tailwind CSS 4, qrcode 1.5.4

## Installation
npm install next@16.0.3 react@19.2.0 react-dom@19.2.0 qrcode@1.5.4 @types/qrcode@1.5.6
npm install -D tailwindcss@4 typescript@5 @types/node@20 @types/react@19

## Environment Variables
NEXT_PUBLIC_QR_DOMAIN=your-domain.com
ADMIN_PASSWORD=your-password

## File Structure
app/
  page.tsx              # Homepage
  admin/
    page.tsx            # Password-protected QR preview/generator
  [slug]/
    route.ts            # Dynamic redirect handler (server route)
  api/
    auth/
      route.ts          # Password authentication endpoint
  data/
    urls.ts             # Hardcoded URL mappings array
  components/
    PasswordProtect.tsx # Password protection wrapper

## Hardcoded URLs (No Database)
URLs are stored in app/data/urls.ts as an array:
export const urlMappings: UrlMapping[] = [
  { slug: "example", url: "https://example.com", description: "Example" }
];

The [slug]/route.ts file creates a Map from this array for O(1) lookup and redirects via NextResponse.redirect() with 302 status.

## Password Protection
- Server-side password check in app/api/auth/route.ts
- Password stored in ADMIN_PASSWORD env var (server-side only)
- PasswordProtect component wraps admin page
- Uses sessionStorage for client-side session management
- Simple POST to /api/auth with password in body

## Logo Files
Place your logo files in the public/ directory:
- public/logo.svg - SVG logo (64x64 recommended) used for embedding in QR codes
- public/qr.png - PNG logo (optional, for headers/UI)

Reference in code as: LOGO_URL = "/logo.svg" (public path, no /public prefix)

## QR Code Generation
- Uses qrcode library (QRCode.toCanvas for PNG, QRCode.toString for SVG)
- QR_SIZE: 1000px, LOGO_SIZE: 200px (20% of QR code)
- Logo positioned center with white background rectangle

## SVG Logo Embedding (Critical)
For SVG download: Parse logo SVG with DOMParser, clone all child elements into a <g> group using importNode, position using viewBox coordinates (not pixels). Add white background rect behind logo.

For canvas/PNG: Fetch logo SVG from /logo.svg, create Blob, use FileReader.readAsDataURL to convert to data URI, then load as Image object for canvas.drawImage().

Key difference: SVG needs direct element cloning, canvas needs data URI conversion.

## Logo Positioning Math
QR codes have viewBoxes (e.g., "0 0 33 33") that don't match pixel dimensions (1000x1000). Logo must be positioned in viewBox coordinates:
- logoX = (viewBoxWidth - (LOGO_SIZE / QR_SIZE * viewBoxWidth)) / 2
- logoY = (viewBoxHeight - (LOGO_SIZE / QR_SIZE * viewBoxHeight)) / 2
- logoScale = (LOGO_SIZE / QR_SIZE * viewBoxWidth) / originalLogoSize

## Admin Page Features
- Two column layout: instructions on left, preview on right
- Auto-generates QR code as user types (debounced 500ms)
- Shows hardcoded URLs with preview QR codes
- Download as PNG or SVG
- Copy URL to clipboard

## Redirect Route Implementation
app/[slug]/route.ts:
- Validates slug format (alphanumeric, hyphens, underscores)
- Creates Map from urlMappings for fast lookup
- Validates destination URL (http/https only)
- Returns 302 redirect (not 301, so changes work immediately)
- Falls back to homepage if slug not found

## Key Implementation Details
- No database: everything in code/config files
- Server-side password: ADMIN_PASSWORD env var, not exposed to client
- SVG embedding: direct element cloning, not data URIs
- ViewBox coordinates: logo positioning uses SVG coordinate system
- Hardcoded URLs: simple array, Map lookup, fast redirects
- Session storage: client-side auth state, clears on tab close

## Deployment
Standard Next.js deployment. Set environment variables on hosting platform.
No database setup required. Just deploy and configure URLs in code.