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

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

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