tknuth/QR-master
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
test
QR-master/CLAUDE.md

19 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

QR Master is a production-ready SaaS application for creating and managing QR codes with advanced analytics, Stripe payment integration, and multi-tier subscription plans (FREE, PRO, BUSINESS).

Tech Stack

  • Frontend: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Framer Motion
  • Backend: Next.js API Routes, Prisma ORM, PostgreSQL
  • Authentication: NextAuth.js v4 (Credentials + Google OAuth)
  • Payments: Stripe (subscriptions, webhooks)
  • Cache: Redis (optional)
  • Analytics: PostHog (optional), QR scan tracking with IP hashing
  • QR Generation: qrcode, qr-code-styling libraries
  • Bulk Operations: Papa Parse (CSV), ExcelJS, JSZip
  • Storage: AWS S3 (via @aws-sdk)

Quick Development Commands

# Setup
npm install
npm run docker:dev              # Start PostgreSQL & Redis in Docker
npx prisma migrate dev          # Run migrations
npm run db:seed                 # Seed demo data

# Development
npm run dev                      # Start dev server (port 3050)
npm run lint                     # Run ESLint

# Database
npm run db:migrate              # Run pending migrations (dev mode)
npm run db:deploy               # Apply migrations (production)
npm run db:studio               # Open Prisma Studio UI
npx prisma migrate reset        # Reset database (drops, recreates, seeds)

# Docker
npm run docker:prod             # Start full production stack
npm run docker:dev:stop         # Stop dev services
npm run docker:logs             # View logs
npm run docker:db               # PostgreSQL CLI
npm run docker:redis            # Redis CLI
npm run docker:backup           # Backup database to SQL file

# Build & Deploy
npm run build                   # Production build
npm run start                   # Start production server

Project Structure

src/
├── app/
│   └── (main)/
│       ├── (app)/              # Authenticated app pages (dashboard, bulk-creation, settings)
│       ├── (auth)/             # Auth pages (login, signup, forgot-password)
│       ├── (marketing)/        # Public pages & marketing tools
│       │   └── tools/          # QR code type-specific generators (20+ tools)
│       └── api/                # API routes organized by domain
│           ├── auth/           # Authentication (signin, signup, OAuth, password reset)
│           ├── qrs/            # QR code CRUD (GET, POST, PATCH, DELETE)
│           ├── analytics/      # Analytics summary endpoint
│           ├── stripe/         # Payment webhooks & session management
│           ├── user/           # User profile, plan, stats, password
│           ├── newsletter/     # Subscription management
│           └── [other]/        # admin, feedback, leads, bulk, etc.
├── components/
│   ├── ui/                     # Reusable UI primitives (Card, Dialog, Input, etc.)
│   ├── generator/              # QR code generator components
│   ├── analytics/              # Charts, maps, data visualization
│   ├── dashboard/              # Dashboard-specific components
│   ├── settings/               # Settings & account components
│   └── SessionProvider.tsx     # NextAuth session provider
├── lib/
│   ├── auth.ts                 # NextAuth configuration
│   ├── db.ts                   # Prisma client
│   ├── stripe.ts               # Stripe utilities
│   ├── email.ts                # Email sending (Resend)
│   ├── qr.ts                   # QR code generation utilities
│   ├── geo.ts                  # Geolocation utilities
│   ├── hash.ts                 # IP hashing (privacy)
│   ├── csrf.ts                 # CSRF token generation/validation
│   ├── rateLimit.ts            # Rate limiting utilities
│   ├── schema.ts               # Zod validation schemas
│   ├── validationSchemas.ts    # Additional validation
│   └── cookieConfig.ts         # Cookie configuration
├── hooks/
│   ├── useCsrf.ts              # CSRF token hook
│   └── useTranslation.ts       # i18n hook
└── types/
    └── analytics.ts            # Analytics type definitions

Database Architecture

Key Models (see prisma/schema.prisma):

  • User: User accounts with Stripe subscription fields
  • QRCode: QR code records (static/dynamic, multiple content types)
  • QRScan: Analytics data (ts, ipHash, device, os, country, UTM params)
  • Account/Session: NextAuth authentication tables
  • Integration: Third-party integrations
  • NewsletterSubscription: Email subscribers
  • Lead: Lead generation data

QR Code Types: URL, VCARD, GEO, PHONE, SMS, TEXT, WHATSAPP, PDF, APP, COUPON, FEEDBACK

API Architecture

Authentication Flow

  • Credentials-based login/signup via /api/auth/signup and /api/auth/simple-login
  • Google OAuth via /api/auth/google
  • NextAuth.js session management at /api/auth/[...nextauth]
  • Password reset: /api/auth/forgot-password + /api/auth/reset-password

QR Code Operations

  • CRUD: GET/POST /api/qrs, GET/PATCH/DELETE /api/qrs/[id]
  • Static Generation: POST /api/qrs/static
  • Bulk Operations: POST /api/bulk/* for CSV/Excel import
  • Public Redirect: GET /r/[slug] (redirect + analytics tracking)

Payments

  • Stripe webhooks: POST /api/stripe/webhook
  • Checkout session: POST /api/stripe/checkout or /api/stripe/create-checkout-session
  • Customer portal: POST /api/stripe/portal
  • Subscription sync: POST /api/stripe/sync-subscription
  • Cancellation: POST /api/stripe/cancel-subscription

Analytics

  • Summary endpoint: GET /api/analytics/summary?qrId=<id>
  • Scan tracking with hashed IP (GDPR-compliant)

Key Implementation Patterns

Authentication & Authorization

  • NextAuth.js v4 with Prisma adapter
  • Sessions stored in database
  • CSRF protection on all mutations (check useCsrf hook)
  • Password hashing with bcryptjs

API Security

  • Rate limiting on sensitive endpoints (auth, payments)
  • CSRF tokens validated on POST/PATCH/DELETE
  • IP hashing for privacy (IP_SALT environment variable)
  • DNT header respected for analytics

Database Operations

  • Prisma ORM for all database access
  • Migrations stored in prisma/migrations/
  • Seed script for demo data in prisma/seed.ts
  • Database indexes on frequently queried fields (userId, createdAt, etc.)

QR Code Generation

  • qrcode library for basic generation
  • qr-code-styling for advanced customization
  • qrcode.react for inline React components
  • Canvas/SVG export via html-to-image, jspdf, jszip

State & Validation

  • Zod schemas in /lib/schema.ts for runtime validation
  • TypeScript strict mode enabled
  • Prisma provides type safety at database layer

Environment Variables

Required:

  • DATABASE_URL - PostgreSQL connection string
  • NEXTAUTH_SECRET - JWT encryption secret
  • NEXTAUTH_URL - Application URL (default: http://localhost:3050)
  • IP_SALT - Salt for IP hashing

Optional but Important:

  • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
  • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET - OAuth
  • REDIS_URL - Redis connection
  • NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST - Analytics
  • NEXT_PUBLIC_INDEXABLE - Set to true for production (enables search engine indexing)

Generate Secrets:

openssl rand -base64 32  # NEXTAUTH_SECRET and IP_SALT

Common Tasks

Adding a New QR Code Type

  1. Add type to ContentType enum in prisma/schema.prisma
  2. Create generator component in src/components/generator/ or src/app/(main)/(marketing)/tools/
  3. Add validation schema in src/lib/schema.ts
  4. Create API endpoint if needed in src/app/(main)/api/qrs/

Creating a New Marketing Tool Page

  1. Create page at src/app/(main)/(marketing)/tools/[tool-name]/page.tsx
  2. Create generator component in same directory
  3. Add SEO metadata in page component
  4. Tool should be static (no database) or use public API endpoints

Adding a New API Endpoint

  1. Create route file in appropriate directory under src/app/(main)/api/
  2. Add Zod validation schema in src/lib/schema.ts
  3. Check authentication with getServerSession() if needed
  4. Implement rate limiting for sensitive operations
  5. Return typed responses with proper status codes

Database Schema Changes

  1. Update prisma/schema.prisma
  2. Run npx prisma migrate dev --name <migration-name>
  3. This creates migration file and updates Prisma client
  4. Test with npm run db:seed if demo data affected

Testing & Debugging

  • Demo account (after seed): email: demo@qrmaster.com, password: demo123
  • Prisma Studio: npm run db:studio - visual database browser
  • API testing: Check /src/app/(main)/api/ for examples
  • Frontend: Pages hot-reload on changes during npm run dev

Performance Considerations

  • PostgreSQL indexes on QRCode(userId, createdAt) and QRScan(qrId, ts)
  • Redis optional but recommended for caching analytics
  • Static export for marketing pages when possible
  • Image optimization enabled in next.config.mjs
  • Prisma connection pooling recommended for production

Database Change Policy

IMPORTANT: No Prisma migrations. All database schema changes (new columns, new enum values, new tables) must be applied via raw SQL commands directly against the running PostgreSQL instance.

Workflow for schema changes:

  1. Write the raw SQL (e.g. ALTER TABLE, ALTER TYPE ... ADD VALUE)
  2. Run via Docker: npm run docker:db then execute SQL, or use docker-compose exec db psql -U postgres -d qrmaster -c "..."
  3. Update prisma/schema.prisma to match (so Prisma client types stay in sync)
  4. Run npx prisma generate to regenerate the client (no migrate)

Example — adding an enum value:

ALTER TYPE "ContentType" ADD VALUE 'BARCODE';

Common Pitfalls

  1. Database Connection: If "Can't reach database server", ensure Docker is running (npm run docker:dev)
  2. Prisma Out of Sync: Run npx prisma generate if TypeScript errors appear
  3. Migration Conflicts: Use npx prisma migrate reset to start fresh
  4. Port 3050 in Use: Change port in package.json dev script or kill process
  5. Build Failures: Check NODE_OPTIONS='--max-old-space-size=4096' in build script - set higher if needed

SEO & Content

  • Schema.org structured data implemented for products, organizations, FAQs
  • Breadcrumb navigation for UX/SEO
  • Meta tags configured per page
  • Open Graph images at /api/og
  • Sitemap generation via next-sitemap
  • Google Indexing API + IndexNow submission scripts available

AI SEO / AEO Tracking (AI Answer Engine Visibility)

Ongoing effort to increase QR Master's presence in AI-generated answers (ChatGPT, Perplexity, AI Overviews, etc.) for QR-code-generator-related queries. Update this section after each audit/build cycle so future sessions build on prior findings instead of re-deriving them.

Baseline audit (2026-07-22)

Query-fanout data (what an AI model searches for while answering a prompt) showed QR Master already being cited in AI-generated answers for 3 of 9 tested query themes: "best QR code generator for marketing campaigns", "QR code generator with analytics and tracking", and "affordable dynamic QR code generator for small business" — positioned as the budget/SMB pick alongside Uniqode, QR TIGER, Bitly, Flowcode, and Hovercode.

No QR Master citation appeared for: "best dynamic QR code generator 2026", "best QR code generator for businesses", "best QR code generator for agencies", "alternatives to QR TIGER", "QR code generator with unlimited scans", "free dynamic QR code generator unlimited scans".

Existing on-site AEO infrastructure found during the audit:

  • public/llms.txt present — lists core pages and cornerstone guides for AI retrieval
  • /alternatives/ pages exist only for: qr-code-generator.com, Flowcode, Beaconstac, Bitly
  • /vs/ pages exist only for: Beaconstac
  • /compare/[slug] dynamic comparison route exists (e.g. free-vs-paid-qr-code-generator)
  • Blog cornerstones: best-qr-code-generator-2026, free-vs-paid-qr-generator, qr-code-tracking-guide-2025, dynamic-vs-static-qr-codes, qr-code-small-business, qr-code-scan-statistics-2026, etc.

Pattern observed: QR Master gets cited by AI models only where first-party comparison/guide content already exists on the domain. The fanout queries repeatedly run site: searches against Uniqode, QR TIGER (qrcode-tiger.com), Hovercode, Scanova, and QRCodeChimp — none of which currently have a matching QR Master alternatives/vs page.

Priority backlog (from this audit)

  1. Build /alternatives/uniqode, /alternatives/qr-code-tiger, /alternatives/hovercode (highest fanout frequency, in that order)
  2. Build matching /vs/uniqode, /vs/qr-code-tiger, /vs/hovercode (same format as /vs/beaconstac)
  3. New cornerstone guide: "QR code generator for agencies" (white-label, bulk creation, API) — zero QR Master positioning currently exists for this query cluster
  4. Update public/llms.txt once the new pages ship, so they enter the AI retrieval list
  5. Re-run the same query-fanout test periodically to track citation-rate changes over time

Additional confirmed win — "dynamic barcode generator" (2026-07-22, same session)

Tested outside the original 9-theme set. QR Master is cited as the "Best overall option" for this query — credited for trackable/editable dynamic barcodes, bulk generation, unified analytics, and UTM tracking, plus static EAN-13/UPC-A/Code 128 support when editability isn't needed. The AI answer also included a "requirement → recommended format" decision table (dynamic QR vs. EAN-13/UPC-A vs. Code 128 vs. GS1 Digital Link) that maps closely to existing on-site content.

This maps to the /tools/barcode-generator tool, reinforcing the pattern above: dedicated first-party pages targeting a query cluster get cited, gaps without dedicated pages don't. Counts as a 4th confirmed positive theme alongside the original 3 from the baseline audit.

Note: /dynamic-barcode-generator and /barcode-generator are not live pages — both 301 to /tools/barcode-generator (see redirects() in next.config.mjs). Cite the canonical /tools/barcode-generator URL in any AEO work.

Sitemap / IndexNow drift (fixed 2026-08-13)

src/app/sitemap.ts and getAllIndexableUrls() in src/lib/indexnow.ts are two hand-maintained URL lists that had silently diverged: the whole /alternatives/* + /vs/* cluster (1,942 GSC impressions in the 3 months to 2026-08-13, avg pos ~29-47) was submitted to IndexNow and linked from the footer but missing from the sitemap, while /dynamic-barcode-generator was listed in both despite 301-ing.

When adding or redirecting a marketing page, update both lists. A redirected URL must appear in neither.

Google Review cluster — biggest non-brand opportunity (2026-08-13)

/tools/google-review-qr-code is the #2 page on the site by impressions (2,201 in 3 months) and converts almost none of it: 2 clicks, avg position 33. The query cluster is ~1,667 impressions across 50+ queries, all at position 20-50, zero clicks. Head term google review qr code generator = 268 impr at pos 35.

On-page is not the constraint — do not "improve the content". Audited 2026-08-13: it is already the deepest tool page on the site (1,352 rendered words, 8 h2 / 18 h3 vs 549 for crypto, 741 for wifi), with SoftwareApplication + HowTo + FAQPage schema, a correctly matched title, and canonical set. It also does not meaningfully cannibalize /use-cases/qr-codes-for-review-collection (36 impr, pos 11), which targets the tracking angle.

What was done: added google-review-qr-code to toolsMap in qr-code-for/[industry]/page.tsx and to the tools[] array of the 32 local-business industries in src/lib/industry-pages.ts, creating contextual internal links from crawled, well-ranking pages (barbershops pos 9.7, hotels, cafes, bars). The 20 institutional industries (airports, schools, stadiums, libraries, churches, universities, museums, theaters, cinemas, art-galleries, events, trade-shows, retail, and the non-local stores) were deliberately excluded — review collection is not their job, and blanket-linking all 52 would be boilerplate.

Remaining gap is off-site authority, not anything in this repo. Note the fallback in that template silently rewrites an unknown tool slug to /tools/url-qr-code, so any new slug must be added to toolsMap or the link disappears without erroring.

Deployment Notes

Docker (Self-Hosted)

npm run docker:prod  # Builds and starts full stack
docker-compose exec web npx prisma migrate deploy  # Run migrations in container

Vercel

  • Push to GitHub and import in Vercel dashboard
  • Set environment variables in Vercel settings
  • Requires external PostgreSQL database (Vercel Postgres, Supabase, etc.)
  • Redis is optional

Additional Resources

  • README.md - Detailed setup and feature overview
  • DOCKER_SETUP.md - Complete Docker deployment guide
  • prisma/schema.prisma - Database schema and relationships
  • env.example - Environment variable template

gstack (REQUIRED — global install)

Before doing any AI-assisted work in this repo, verify gstack is installed globally:

test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING"

If GSTACK_MISSING: stop and install it:

git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup --team

After install, use gstack skills where appropriate, especially /browse, /review, /investigate, /qa, /ship, and /cso. Use ~/.claude/skills/gstack/... for gstack file paths because this repo does not vendor the pack locally.

Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:

  • Product ideas, "is this worth building", brainstorming → invoke office-hours
  • Bugs, errors, "why is this broken", 500 errors → invoke investigate
  • Ship, deploy, push, create PR → invoke ship
  • QA, test the site, find bugs → invoke qa
  • Code review, check my diff → invoke review
  • Update docs after shipping → invoke document-release
  • Weekly retro → invoke retro
  • Design system, brand → invoke design-consultation
  • Visual audit, design polish → invoke design-review
  • Architecture review → invoke plan-eng-review
  • Save progress, checkpoint, resume → invoke checkpoint
  • Code quality, health check → invoke health
Reference in New Issue View Git Blame Copy Permalink