# 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

```bash
# 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**:
```bash
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)
```bash
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