Everything the big QR platforms do β designed for print, never held hostage.
Drop a link. Watch it bloom. QRBuddy is a full-stack QR studio for businesses, restaurants, agencies, designers, and makers that replaces Bitly, QR Code Monkey, and QR Tiger without dated black-and-white barcodes, mandatory account walls, or $35/month hostage subscriptions.
- Full-Stack QR Studio - Create URLs, Wi-Fi cards, Contact Cards (vCard), Social Bio Hubs, Media Hubs, Phone/SMS/Email triggers, and Plain Text from one smart auto-detecting input bar
- Print-Verified Design Engine - 10 luminance-tested palettes (6 in the public gallery, β€ 0.40 luminance), custom 2-stop linear/radial gradients, module, eye and centre-mark geometry, centre logo or monogram, palette-aware card labels, live WCAG contrast badge, and 3000px PNG + vector SVG export
- Looks - Classic, Halftone (the artwork becomes the ink, at 4Γ the module
grid) and Flat Foil (a flat code on an extruded tile). Every look keeps the
finder, timing and alignment patterns intact, holds a 4-module quiet zone, and
is decoder-tested before it is offered. See
docs/LOOKS.md - Smart Dynamic QR Codes - Edit destinations after printing, route by time-of-day (Breakfast/Lunch/Dinner menus), split by iOS/Android or A/B weights, rotate sequential links, or set scan caps and expiration dates
- Branded Cover Pages & White-Label - Add Warm Paper, Sunset Pop, or Midnight Ink cover pages with 1-click starters (CafΓ© Menu, Wi-Fi Card, Tip Jar, Event Check-in) and 1-click Passport White-Labeling
- Passport Field Report π - 7d/30d/90d scan trends, Top Cities & Countries, 24-hour Peak Rush Hour window, Browser & Device split, Track/Photo Leaderboard, and 1-click RFC-4180 CSV export (zero IP or raw User-Agent logging)
- Agency Bulk / Batch ZIP Generator - Paste multiple URLs (or
Label | URLrows) and export a single ZIP containing 1000px PNGs, vector SVGs, and a print-shopmanifest.csv - Daylight Media Drops & File Lockers - Drop up to 10 photos for an auto-advancing gallery, up to 10 audio tracks for a browser mixtape player, inbound File Collection Lockers, or up to 500 MB file drops with optional PIN & self-destruct limits
- Street-Safe QR Inspector - Scan any QR code to unroll up to 5 redirect hops, verify HTTPS, and inspect a live visual webpage preview before visiting
- The QRBuddy Passport πβ¨ - Cryptographic 4-word key & scannable QR card
that syncs your library and paid status (
~$32 USD / A$49for 365 days, zero auto-renewal) across laptop and phone with zero email/password sign-up - Bilingual Out of the Box - Native English (
/) and LatAm/Mexican Spanish (/es) across the studio and vertical landing pages (/for/menus,/for/weddings,/for/music,/for/lockers,/guide/printing)
# Install Deno (if not already installed)
curl -fsSL https://deno.land/install.sh | sh
# Clone the repository
git clone https://github.com/pibulus/qrbuddy.git
cd qrbuddy
# Start the Fresh dev server
deno task start
# Optional: in another terminal, start the local mock API server
# for basic destructible file + dynamic QR development without Supabase
deno task apiVisit http://localhost:8004 and start creating beautiful QR codes!
The local API server runs on port 8005 and stores files in local-api/files/
(gitignored). It is a convenience mock, not full production parity: File Locker
and Supabase security/RPC behavior should be tested against Supabase.
- β Basic QR Codes - All 8 gradient styles + custom gradients
- β Destructible QRs - Basic URL/file flows through the local mock API
- β Dynamic QR Codes - Editable redirects with scan limits & expiry (works through the local mock API)
- β KABOOM Page - Epic explosion when already accessed
β οΈ File Locker - Requires Supabase edge functions for realistic testing
Supabase schema and function operations are documented in
supabase/README.md. Use the ordered migrations as the
schema source of truth; supabase/setup.sql is a historical snapshot, not a
production bootstrap path. Supabase deployment is separate from the Fresh app.
Fresh production deploys use the Git-connected Deno Deploy build: pushing the
authorized main commit runs checks, offline unit tests, and deno task build
before the app is routed. Any failure stops that deployment. Do not upload a
local build with deployctl or deno deploy; _fresh/ is generated and
ignored by Git. See CLAUDE.md for the release contract and
current audit links.
- Fresh - The next-gen web framework
- Deno - Modern runtime for JavaScript and TypeScript
- Preact - Fast 3kB alternative to React
- Tailwind CSS - Utility-first CSS framework
- qr-code-styling - Gradient QR generation
qrbuddy/
βββ routes/ # Fresh routes + API handlers
β βββ index.tsx # English studio + SEO/JSON-LD
β βββ es/ # Buena Onda Spanish studio (/es) + verticals
β βββ for/ # English vertical landing pages (menus, weddings, music, lockers)
β βββ guide/printing.tsx # QR print calculator & anti-hostage guide
β βββ q.tsx # Shared QR showcase
β βββ edit.tsx # Dynamic QR editor + Passport Field Report
β βββ boom.tsx # Self-destruct KABOOM landing page
β βββ r.tsx # Dynamic QR redirector + branded Cover Pages
β βββ f/[code].tsx # File drop / slideshow / mixtape share page
β βββ bucket/[code].tsx # Inbound File Locker viewer
β βββ note/[code].tsx # Styled note card viewer
β βββ api/ # Server-side endpoints (download-file.ts, peek.ts)
βββ islands/ # Interactive Preact islands
β βββ QRCanvas.tsx # Core QR rendering + 3000px PNG/vector SVG export
β βββ SmartInput.tsx # Smart input (URLs/files/text + dynamic settings)
β βββ QRReader.tsx # 1080p camera QR scanner + Street-Safe Inspector
β βββ StyleSelector.tsx # Gradient selector + custom creator entry
β βββ GradientCreator.tsx # Custom gradient builder modal
β βββ CreateModal.tsx # QR type/options/design creation sheet
β βββ PricingModal.tsx # QRBuddy Passport checkout + Tactile Passport Card
β βββ LibraryDrawer.tsx # Unified local + server QR Library & 4-word sync
β βββ HistoryDrawer.tsx # Local QR history & encrypted backup drawer
β βββ OwnerStrip.tsx # Share owner bar + Passport Field Report analytics
β βββ EditQRForm.tsx # Dynamic QR edit experience
β βββ BucketQR.tsx # File locker status + QR display
β βββ edit-qr/ # Dynamic QR edit & analytics sub-islands
β βββ extras/ # Options/design sub-islands (Batch, Routing, Splash, etc.)
β βββ smart-input/ # Input toolbar sub-islands
β βββ templates/ # QR type form sub-islands
βββ components/ # Server-rendered shared components (VerticalLandingHead)
βββ hooks/ # Custom Preact hooks (useBatchGenerator, useDynamicQR, etc.)
βββ local-api/ # Local mock Supabase edge function server for offline dev
βββ supabase/ # Production schema migrations + Edge Functions
βββ utils/ # Shared utilities (passport, qr-styles, qr-decode, i18n, etc.)
βββ types/ # Shared TypeScript interfaces
βββ static/ # Fleet Standard PWA icons, manifest, robots, sitemap, WASM
βββ tests/ # 107 offline unit tests + opt-in edge integrations
βββ tailwind.config.ts # Soft Neo-Toybrut design tokens/theme
- Sunset π β Warm coral-pink to deep plum
- Candy π¬ β Vibrant magenta to electric indigo
- Blush πΈ β Rose-crimson to warm berry
- Matcha π΅ β Deep forest emerald to botanical pine
- Pool π§ β Ocean teal to deep navy
- Vapor π«οΈ β Neon violet to midnight cyber-blue
- Grape π β Royal amethyst to deep mulberry
- Licorice π€ β Warm espresso-black (
#1e1714) high-contrast classic
# Format code
deno fmt
# Lint code
deno lint
# Type check
deno check **/*.ts **/*.tsx
# Run explicit offline unit tests (no network permission)
deno task test:unit
# Build for production
deno task build- CLAUDE.md - agent/developer contract and architecture notes
- GLOSSARY.md - component and concept glossary
- docs/README.md - documentation index and status labels
- supabase/README.md - current backend setup and semantics
- tests/README.md - integration test guide
QRBuddy production is connected to the Deno Deploy Git build. An authorized push
to main runs the configured Fresh AOT build and deploys its output. Keep
APP_URL, SUPABASE_URL, and SUPABASE_ANON_KEY in the Deno Deploy app
configuration. Keep the service-role key only in Supabase function secrets.
For a self-hosted deployment, build Fresh before starting the server:
deno task build
deno run -A main.tsDo not upload a local checkout directly with deployctl or deno deploy; the
production Git integration supplies the generated Fresh manifest.
MIT - Do whatever makes you happy!
Pull requests are welcome! For major changes, please open an issue first.
Built with π§ by Pablo (@pibulus)
"The best QR codes feel like magic but work like clockwork" π°οΈ