QR Master - Create Custom QR Codes in Seconds

A production-ready SaaS application for creating and managing QR codes with advanced tracking, analytics, and integrations.

Features

• 🎨 Custom QR Codes - Create static and dynamic QR codes with full customization
• 📊 Advanced Analytics - Track scans, locations, devices, and user behavior
• 🔄 Dynamic Content - Edit QR code destinations anytime without reprinting
• 📦 Bulk Operations - Import CSV/Excel files to create multiple QR codes at once
• 🔌 Integrations - Connect with Zapier, Airtable, and Google Sheets
• 🌍 Multi-language - Support for English and German (i18n)
• 🔒 Privacy-First - Respects user privacy with hashed IPs and DNT headers
• 📱 Responsive Design - Works perfectly on all devices

Tech Stack

• Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
• Backend: Next.js API Routes, Prisma ORM
• Database: PostgreSQL
• Cache: Redis (optional)
• Auth: NextAuth.js (Credentials + Google OAuth)
• QR Generation: qrcode library
• Charts: Chart.js with react-chartjs-2
• i18n: i18next

Quick Start

Prerequisites

• Node.js 18+
• Docker and Docker Compose V2
• Git

Installation

Option 1: Development Mode (Recommended)

Run database in Docker, app on host machine:

1. Clone the repository:

git clone https://github.com/yourusername/qr-master.git
cd qr-master

2. Install dependencies:

npm install

3. Copy and configure environment:

cp env.example .env

Edit .env and set:

• NEXTAUTH_SECRET (generate: openssl rand -base64 32)
• IP_SALT (generate: openssl rand -base64 32)
• (Optional) Google OAuth credentials

4. Start database services:

npm run docker:dev

5. Run migrations and seed:

npm run db:migrate
npm run db:seed

6. Start development server:

npm run dev

7. Access the application:
   • App: http://localhost:3050
   • Database UI: http://localhost:8080 (Adminer)
   • Database: localhost:5432
   • Redis: localhost:6379

Option 2: Full Docker (Production)

Run everything in Docker:

1. Clone and setup:

git clone https://github.com/yourusername/qr-master.git
cd qr-master
cp env.example .env
# Edit .env with your configuration

2. Build and start:

npm run docker:prod

3. Run migrations:

docker-compose exec web npx prisma migrate deploy

4. Access at http://localhost:3050

📚 For detailed Docker setup, see DOCKER_SETUP.md

Demo Account

Use these credentials to test the application:

• Email: demo@qrmaster.com
• Password: demo123

Development

Available Scripts

# Development
npm run dev                 # Start Next.js dev server
npm run build              # Build for production
npm run start              # Start production server

# Database
npm run db:generate        # Generate Prisma Client
npm run db:migrate         # Run migrations (dev)
npm run db:deploy          # Deploy migrations (prod)
npm run db:seed            # Seed database
npm run db:studio          # Open Prisma Studio

# Docker
npm run docker:dev         # Start DB & Redis only
npm run docker:dev:stop    # Stop dev services
npm run docker:prod        # Start full stack
npm run docker:stop        # Stop all services
npm run docker:logs        # View logs
npm run docker:db          # PostgreSQL CLI
npm run docker:redis       # Redis CLI

Local Development (without Docker)

1. Install dependencies:

npm install

2. Set up PostgreSQL and Redis locally

3. Configure .env with local database URL:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/qrmaster?schema=public

4. Run migrations:

npm run db:migrate
npm run db:seed

5. Start dev server:

npm run dev

Project Structure

qr-master/
├── src/
│   ├── app/                    # Next.js app router pages
│   ├── components/             # React components
│   ├── lib/                   # Utility functions and configurations
│   ├── hooks/                 # Custom React hooks
│   ├── styles/                # Global styles
│   └── i18n/                  # Translation files
├── prisma/                    # Database schema and migrations
├── docker/                    # Docker initialization scripts
│   ├── init-db.sh            # PostgreSQL initialization
│   └── README.md             # Docker documentation
├── public/                    # Static assets
├── docker-compose.yml         # Production Docker setup
├── docker-compose.dev.yml     # Development Docker setup
├── Dockerfile                # Container definition
├── DOCKER_SETUP.md           # Complete Docker guide
└── env.example               # Environment template

API Endpoints

Authentication

• POST /api/auth/signin - Sign in with credentials
• POST /api/auth/signout - Sign out
• GET /api/auth/session - Get current session

QR Codes

• GET /api/qrs - List all QR codes
• POST /api/qrs - Create a new QR code
• GET /api/qrs/[id] - Get QR code details
• PATCH /api/qrs/[id] - Update QR code
• DELETE /api/qrs/[id] - Delete QR code

Analytics

• GET /api/analytics/summary - Get analytics summary

Bulk Operations

• POST /api/bulk - Import QR codes from CSV/Excel

Public Redirect

• GET /r/[slug] - Redirect and track QR code scan

Environment Variables

Variable	Description	Required	Default
DATABASE_URL	PostgreSQL connection string	Yes	postgresql://postgres:postgres@localhost:5432/qrmaster?schema=public
NEXTAUTH_URL	Application URL	Yes	http://localhost:3050
NEXTAUTH_SECRET	Secret for JWT encryption	Yes	Generate with openssl rand -base64 32
IP_SALT	Salt for IP hashing	Yes	Generate with openssl rand -base64 32
GOOGLE_CLIENT_ID	Google OAuth client ID	No	-
GOOGLE_CLIENT_SECRET	Google OAuth client secret	No	-
REDIS_URL	Redis connection string	No	redis://redis:6379
ENABLE_DEMO	Enable demo mode	No	false

Note: Copy env.example to .env and update the values before starting.

Security

• IP addresses are hashed with salt before storage
• Respects Do Not Track (DNT) headers
• CORS protection enabled
• Rate limiting on API endpoints
• Secure session management with NextAuth.js

Deployment

Docker (Recommended for Self-Hosting)

The application includes production-ready Docker configuration with PostgreSQL and Redis:

# Build and start all services
docker-compose up -d --build

# Run migrations
docker-compose exec web npx prisma migrate deploy

# View logs
docker-compose logs -f

For detailed deployment instructions, see DOCKER_SETUP.md.

Vercel

1. Push your code to GitHub
2. Import the project in Vercel
3. Add a PostgreSQL database (Vercel Postgres, Supabase, or other)
4. Add environment variables in Vercel dashboard
5. Deploy

Note: For Vercel deployment, you'll need to set up a PostgreSQL database separately.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email support@qrmaster.com or open an issue on GitHub.

Acknowledgments

• Next.js team for the amazing framework
• Vercel for hosting and deployment
• All open-source contributors

---

Built with ❤️ by QR Master Team