qr-code_manager/README.md

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:

   git clone <your-repo-url>
   cd qr-code_manager
   

2. Create environment file:

   cp .env.example .env
   # Edit .env with your preferred settings
   

3. Deploy with Docker:

   ./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:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Run the application:

   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:

   FLASK_ENV=production
   SECRET_KEY=your-super-secret-key-here
   ADMIN_USERNAME=your-admin-username
   ADMIN_PASSWORD=your-secure-password
   

2. Deploy:

   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:

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