A Python web application for organizing and managing your LEGO instruction manuals. Upload PDFs and images, search by theme, set number, or year, and integrate with Brickset API for automatic set details.

✨ Features

📤 Upload & Organize: Upload instruction PDFs and images for your LEGO sets
🔍 Advanced Search: Search and filter by theme, year, set number, or name
🎨 Theme Organization: Organize sets by LEGO themes automatically
🔗 Brickset Integration: Auto-populate set details using Brickset API v3
👤 User Authentication: Secure login and user management
📱 Responsive Design: Works on desktop, tablet, and mobile
📊 Statistics Dashboard: View collection statistics and insights
🖼️ Image Gallery: View instruction images in an organized gallery
📄 PDF Support: View and download PDF instructions directly

🚀 Quick Start

Prerequisites

Python 3.8 or higher
pip (Python package manager)
Git

Installation

Clone the repository

git clone https://gitea.hideawaygaming.com.au/jessikitty/lego-instructions-manager.git
cd lego-instructions-manager

Create a virtual environment

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

Install dependencies

pip install -r requirements.txt

Configure environment variables

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

Initialize the database

flask --app run.py init-db

Create an admin user

flask --app run.py create-admin

Run the application

python run.py

The application will be available at http://localhost:5000

⚙️ Configuration

Environment Variables

Edit the .env file with your configuration:

# Flask Configuration
SECRET_KEY=your-secret-key-here
FLASK_ENV=development

# Database (SQLite by default)
DATABASE_URL=sqlite:///lego_instructions.db

# Brickset API (optional but recommended)
BRICKSET_API_KEY=your-api-key
BRICKSET_USERNAME=your-username
BRICKSET_PASSWORD=your-password

# Upload Settings
MAX_CONTENT_LENGTH=52428800  # 50MB
SETS_PER_PAGE=20

Brickset API Setup

Register for a free account at Brickset.com
Request an API key at Brickset API Documentation
Add your credentials to the .env file

The application works without Brickset, but you'll miss out on automatic set data population.

📖 Usage

Adding a Set

Click "Add Set" in the navigation
Enter set details manually OR search using Brickset
Save the set to your collection

Uploading Instructions

Navigate to a set's detail page
Click "Upload Instructions"
Select PDF or image files
Files are automatically organized by set number

Searching & Filtering

Use the search bar to find sets by name or number
Filter by theme or year using the dropdowns
Sort by set number, name, theme, year, or newest first

🗂️ Project Structure

lego-instructions-manager/
├── app/
│   ├── models/           # Database models
│   ├── routes/           # Application routes/views
│   ├── services/         # Business logic (API, file handling)
│   ├── templates/        # HTML templates
│   └── static/           # CSS, JS, uploaded files
├── migrations/           # Database migrations
├── tests/                # Unit tests
├── requirements.txt      # Python dependencies
├── run.py               # Application entry point
└── README.md            # This file

🛠️ Development

Database Migrations

When you modify database models:

flask --app run.py db init       # Initialize migrations (first time only)
flask --app run.py db migrate -m "Description"  # Create migration
flask --app run.py db upgrade    # Apply migration

Running Tests

pytest tests/

Flask Shell

Access the Flask shell for debugging:

flask --app run.py shell

📊 Database Schema

User

id, username, email, password_hash, created_at

Set

id, set_number, set_name, theme, year_released, piece_count
brickset_id, image_url, user_id, created_at, updated_at

Instruction

id, set_id, file_type, file_path, file_name, file_size
page_number, user_id, uploaded_at

🔒 Security Notes

Passwords are hashed using bcrypt
File uploads are validated and sanitized
User authentication required for all operations
CSRF protection enabled on all forms

🚢 Deployment

Production Considerations

Use PostgreSQL instead of SQLite:

DATABASE_URL=postgresql://user:password@localhost/lego_db

Set a strong SECRET_KEY:

import secrets
print(secrets.token_hex(32))

Use gunicorn for production:

gunicorn -w 4 -b 0.0.0.0:8000 "run:app"

Set up nginx as a reverse proxy
Enable HTTPS with Let's Encrypt
Regular backups of database and uploads folder

🐛 Troubleshooting

Database Errors

# Reset database
rm lego_instructions.db
flask --app run.py init-db

File Upload Issues

# Check permissions
chmod -R 755 app/static/uploads

Brickset Connection Issues

Verify API credentials in .env
Check Brickset API status
Review application logs

📝 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions:

Open an issue on Gitea
Check existing documentation
Review Brickset API docs

🙏 Acknowledgments

Brickset for the excellent LEGO database API
Bootstrap for the UI framework
Flask for the web framework

Built with ❤️ for LEGO enthusiasts