320 lines
13 KiB
Markdown
320 lines
13 KiB
Markdown
# 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
|
|
|
|
## 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:
|
|
```sql
|
|
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)
|
|
```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
|
|
|
|
## gstack (REQUIRED — global install)
|
|
|
|
Before doing any AI-assisted work in this repo, verify gstack is installed globally:
|
|
|
|
```bash
|
|
test -d ~/.claude/skills/gstack/bin && echo "GSTACK_OK" || echo "GSTACK_MISSING"
|
|
```
|
|
|
|
If `GSTACK_MISSING`: stop and install it:
|
|
|
|
```bash
|
|
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
|