# QR Code Manager

A modern Flask web application for generating and managing QR codes with authentication and dynamic link pages.

## 🚀 Features

- **Multiple QR Code Types**: Text, URL, WiFi, Email, SMS, vCard
- **Dynamic Link Pages**: Create collections of links accessible via QR codes
- **Admin Authentication**: Secure login with bcrypt password hashing
- **Customizable Styling**: Different QR code styles (square, rounded, circle)
- **Logo Integration**: Add custom logos to QR codes
- **Docker Deployment**: Production-ready containerization
- **Responsive Design**: Modern web interface that works on all devices

## 📁 Project Structure

```
qr-code_manager/
├── README.md                 # Project documentation
├── main.py                   # Application entry point
├── Dockerfile               # Docker container definition
├── docker-compose.yml       # Docker orchestration
├── requirements.txt         # Python dependencies
├── .env.example            # Environment variables template
├── deploy.sh               # Deployment script
├── app/                    # Main application package
│   ├── __init__.py         # Flask app factory
│   ├── templates/          # Jinja2 templates
│   │   ├── index.html      # Main dashboard
│   │   ├── login.html      # Authentication page
│   │   ├── link_page.html  # Public link display
│   │   └── edit_links.html # Link management interface
│   ├── static/             # Static files
│   │   ├── qr_codes/       # Generated QR code images
│   │   └── logos/          # Uploaded logo files
│   ├── routes/             # Route handlers
│   │   ├── __init__.py     # Route package
│   │   ├── main.py         # Main page routes
│   │   ├── auth.py         # Authentication routes
│   │   └── api.py          # API endpoints
│   └── utils/              # Utility modules
│       ├── __init__.py     # Utils package
│       ├── auth.py         # Authentication utilities
│       ├── qr_generator.py # QR code generation
│       ├── link_manager.py # Dynamic link management
│       └── data_manager.py # Data storage utilities
```

## 🛠️ Quick Start

### Method 1: Docker (Recommended)

1. **Clone and navigate to the project:**
   ```bash
   git clone <your-repo-url>
   cd qr-code_manager
   ```

2. **Create environment file:**
   ```bash
   cp .env.example .env
   # Edit .env with your preferred settings
   ```

3. **Deploy with Docker:**
   ```bash
   ./deploy.sh
   ```

4. **Access the application:**
   - Open http://localhost:5000
   - Login with: admin / admin123 (change in production!)

### Method 2: Local Development

1. **Set up Python environment:**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

2. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the application:**
   ```bash
   python main.py
   ```

## 🔐 Authentication

- **Default Credentials**: admin / admin123
- **Environment Variables**:
  - `ADMIN_USERNAME`: Set custom admin username
  - `ADMIN_PASSWORD`: Set custom admin password
  - `SECRET_KEY`: Set Flask secret key for sessions

## 🐳 Docker Deployment

The application is fully containerized with Docker:

- **Build and run**: `docker-compose up -d`
- **View logs**: `docker-compose logs -f`
- **Stop**: `docker-compose down`
- **Full rebuild**: `docker-compose up --build -d`

### Production Configuration

1. **Set environment variables in .env:**
   ```bash
   FLASK_ENV=production
   SECRET_KEY=your-super-secret-key-here
   ADMIN_USERNAME=your-admin-username
   ADMIN_PASSWORD=your-secure-password
   ```

2. **Deploy:**
   ```bash
   docker-compose up -d
   ```

## 📱 Usage

### Generating QR Codes

1. **Login** to the admin interface
2. **Select QR type**: Text, URL, WiFi, Email, SMS, or vCard
3. **Fill in the details** for your chosen type
4. **Customize appearance**: Size, colors, style, border
5. **Add logo** (optional): Upload custom logo for branding
6. **Generate and download** your QR code

### Dynamic Link Pages

1. **Create a link page** from the main interface
2. **Add links** to your collection via the edit interface
3. **Share the QR code** that points to your link page
4. **Update links anytime** without changing the QR code

## 🛡️ Security Features

- **Password Hashing**: Uses bcrypt for secure password storage
- **Session Management**: Secure Flask sessions with signing
- **Authentication Required**: All admin functions require login
- **Docker Security**: Non-root user in container
- **Environment Variables**: Sensitive data via environment configuration

## 🔧 Development

### Project Architecture

The application follows a modular Flask structure:

- **App Factory Pattern**: Clean application initialization
- **Blueprint Organization**: Separate route modules for different features
- **Utility Modules**: Reusable components for QR generation, auth, etc.
- **Template Organization**: Structured Jinja2 templates
- **Static File Management**: Organized asset storage

### Adding New Features

1. **New Routes**: Add to appropriate blueprint in `app/routes/`
2. **New Utilities**: Create modules in `app/utils/`
3. **New Templates**: Add to `app/templates/`
4. **New Dependencies**: Update `requirements.txt`

## 📊 API Endpoints

- `POST /api/generate` - Generate QR code
- `GET /api/qr_codes` - List all QR codes
- `GET /api/qr_codes/{id}` - Get specific QR code
- `DELETE /api/qr_codes/{id}` - Delete QR code
- `POST /api/create_link_page` - Create dynamic link page
- `POST /api/link_pages/{id}/links` - Add link to page
- `PUT /api/link_pages/{id}/links/{link_id}` - Update link
- `DELETE /api/link_pages/{id}/links/{link_id}` - Delete link

## 🚨 Troubleshooting

### Common Issues

1. **Permission Denied**: Ensure Docker has proper permissions
2. **Port 5000 in use**: Change port in docker-compose.yml
3. **Authentication Failed**: Check admin credentials in .env
4. **Image Generation Failed**: Verify PIL/Pillow installation

### Health Check

Visit `/health` to check application status:
```bash
curl http://localhost:5000/health
```

## 📝 License

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

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📞 Support

For support, please open an issue on GitHub or contact the development team.

---

**Made with ❤️ for easy QR code management**