QR-master/CLAUDE.md

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

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

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