QR File Catalog System

A two-part system for generating QR codes from your file system and scanning them with your laptop camera to quickly identify and open files.

---

Quick Start

1. Install Dependencies

pip install -r requirements.txt
# or: pip install qrcode[pil] Pillow

2. Generate QR Codes

# Scan your Documents folder (depth 2 to keep it manageable)
python qr_generator.py --path ~/Documents --depth 2 --html

# Scan a project folder
python qr_generator.py --path ~/Projects/sylogic --depth 3 --html

# Scan current directory
python qr_generator.py

This creates a qr_catalog/ folder containing:

• Individual QR code PNG images (color-coded by file type)
• catalog.json — full metadata index
• catalog.html — printable visual catalog (with --html flag)

3. Launch the Scanner

python qr_server.py

This opens http://localhost:8080 in your browser with the camera scanner.

4. Scan QR Codes

• Click Start Scanner to activate your laptop camera
• Hold a QR code in front of the camera
• The app decodes the metadata and shows file details
• Click Open File to open it with the default app, or Reveal to show it in Finder

---

QR Code Metadata

Each QR code encodes a JSON payload with:

Field	Description
name	File or folder name
path	Absolute file path
type	file or folder
category	document, image, video, audio, code, archive, data, executable, other
size	File size in bytes
ext	File extension
mime	MIME type
md5	Partial MD5 hash (for integrity)
modified	Last modified timestamp
created	Creation timestamp
items	(folders) Number of items inside

Category Color Coding

Category	Color	Examples
📁 Folder	Yellow	directories
📄 Document	Blue	.pdf, .docx, .xlsx, .pptx
🖼️ Image	Green	.jpg, .png, .svg, .psd
🎬 Video	Red	.mp4, .mov, .mkv
🎵 Audio	Amber	.mp3, .wav, .flac
💻 Code	Purple	.py, .js, .ts, .go, .rs
📦 Archive	Slate	.zip, .tar.gz, .dmg
📊 Data	Cyan	.json, .yaml, .sql, .db
⚙️ Executable	Pink	.exe, .app, .deb
📎 Other	Gray	everything else

CLI Options

python qr_generator.py [OPTIONS]

  --path, -p PATH     Directory to scan (default: .)
  --output, -o DIR    Output directory (default: ./qr_catalog)
  --depth, -d N       Max depth (-1 = unlimited)
  --html              Generate printable HTML catalog
  --hidden            Include hidden files
  --quiet, -q         Suppress per-file output

python qr_server.py [OPTIONS]

  --port, -p PORT     Server port (default: 8080)
  --no-open           Don't auto-open browser

Tips

• Print the HTML catalog and tape QR codes to physical file boxes or binders
• Depth limit (--depth 2) keeps scan times reasonable for large drives
• Upload QR images directly in the scanner app if you don't want to use the camera
• The scanner works offline after initial page load — no internet required