lego-instructions-manager/QUICK_REFERENCE.md

📋 LEGO Instructions Manager - Quick Reference

🚀 Quick Start

# 1. Setup
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

# 2. Configure (edit .env)
# Add your SECRET_KEY and optionally Brickset credentials

# 3. Initialize
flask --app run.py init-db
flask --app run.py create-admin

# 4. Run
python run.py
# Visit: http://localhost:5000

📁 Key Files

File	Purpose
run.py	Application entry point
.env	Configuration (SECRET_KEY, API keys)
requirements.txt	Python dependencies
app/__init__.py	Flask app factory
app/config.py	App configuration

🔑 Environment Variables

SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///lego_instructions.db
BRICKSET_API_KEY=your-api-key
BRICKSET_USERNAME=your-username
BRICKSET_PASSWORD=your-password

🛠️ Flask Commands

# Initialize database
flask --app run.py init-db

# Create admin user
flask --app run.py create-admin

# Flask shell
flask --app run.py shell

# Database migrations
flask --app run.py db init
flask --app run.py db migrate -m "message"
flask --app run.py db upgrade

📂 Directory Structure

app/
├── models/          # Database models (User, Set, Instruction)
├── routes/          # URL routes (auth, main, sets, instructions)
├── services/        # Business logic (Brickset API, file handling)
├── templates/       # HTML templates
└── static/          # CSS, JS, uploads

🌐 Main Routes

Route	Purpose
/	Homepage
/auth/login	Login page
/auth/register	Registration
/dashboard	User dashboard
/sets/	List all sets
/sets/add	Add new set
/sets/<id>	View set details
/instructions/upload/<id>	Upload instructions

🔍 Common Tasks

Add a New Set

1. Navigate to /sets/add
2. Search Brickset OR enter manually
3. Click "Add Set"

Upload Instructions

1. Go to set detail page
2. Click "Upload Instructions"
3. Select files (PDF or images)
4. Click "Upload"

Search Sets

1. Go to /sets/
2. Use search bar for text search
3. Use filters for theme/year
4. Click column headers to sort

🐛 Troubleshooting

Module Not Found

pip install -r requirements.txt

Permission Denied

chmod -R 755 app/static/uploads

Database Locked

# Restart the application
# Or switch to PostgreSQL

Port Already in Use

# In run.py, change:
app.run(port=5001)  # Use different port

📊 Database Models

User

• username, email, password_hash
• Relationships: sets, instructions

Set

• set_number, set_name, theme, year_released
• piece_count, brickset_id, image_url

Instruction

• set_id, file_type, file_path, file_name
• file_size, page_number

🔐 Security Features

• ✅ Password hashing (bcrypt)
• ✅ CSRF protection
• ✅ SQL injection prevention
• ✅ XSS protection
• ✅ Secure file uploads
• ✅ Session management

📱 Tech Stack

• Backend: Flask 3.0, SQLAlchemy
• Frontend: Bootstrap 5, jQuery
• Database: SQLite (dev) / PostgreSQL (prod)
• Auth: Flask-Login, bcrypt
• API: Brickset API v3

🎨 Customization

Change Colors

Edit app/static/css/style.css:

:root {
    --lego-red: #d11013;
    --lego-yellow: #ffd700;
    --lego-blue: #0055bf;
}

Add Custom Routes

1. Create route in app/routes/
2. Register blueprint in app/__init__.py

Modify Models

1. Edit model in app/models/
2. Create migration
3. Apply migration

📦 Dependencies

Main packages:

• Flask 3.0.0
• Flask-SQLAlchemy 3.1.1
• Flask-Login 0.6.3
• Flask-Bcrypt 1.0.1
• requests 2.31.0
• Pillow 10.1.0

🔄 Update Workflow

# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt --upgrade

# Apply database migrations
flask --app run.py db upgrade

# Restart application
python run.py

📞 Help & Resources

• README.md - Full documentation
• SETUP_GUIDE.md - Detailed setup
• PROJECT_SUMMARY.md - Features & roadmap
• Brickset API: https://brickset.com/article/52664

⚡ Performance Tips

1. Use PostgreSQL for production
2. Enable gzip compression
3. Set up CDN for static files
4. Use Redis for caching
5. Monitor upload folder size

🎯 Production Checklist

• Change SECRET_KEY
• Use PostgreSQL
• Set FLASK_ENV=production
• Use gunicorn
• Set up nginx
• Enable HTTPS
• Set up backups
• Configure logging

---

Quick Help: For detailed information, see README.md and SETUP_GUIDE.md