qrmaster/README.md

# 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:
```bash
git clone https://github.com/yourusername/qr-master.git
cd qr-master
```

2. Install dependencies:
```bash
npm install
```

3. Copy and configure environment:
```bash
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:
```bash
npm run docker:dev
```

5. Run migrations and seed:
```bash
npm run db:migrate
npm run db:seed
```

6. Start development server:
```bash
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:
```bash
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:
```bash
npm run docker:prod
```

3. Run migrations:
```bash
docker-compose exec web npx prisma migrate deploy
```

4. Access at http://localhost:3050

📚 **For detailed Docker setup, see [DOCKER_SETUP.md](DOCKER_SETUP.md)**

## Demo Account

Use these credentials to test the application:

- **Email**: demo@qrmaster.com
- **Password**: demo123

## Development

### Available Scripts

```bash
# 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:
```bash
npm install
```

2. Set up PostgreSQL and Redis locally

3. Configure `.env` with local database URL:
```env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/qrmaster?schema=public
```

4. Run migrations:
```bash
npm run db:migrate
npm run db:seed
```

5. Start dev server:
```bash
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:

```bash
# 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](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](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