# 📋 LEGO Instructions Manager - Quick Reference

## 🚀 Quick Start

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

```env
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

```bash
# 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
```bash
pip install -r requirements.txt
```

### Permission Denied
```bash
chmod -R 755 app/static/uploads
```

### Database Locked
```bash
# Restart the application
# Or switch to PostgreSQL
```

### Port Already in Use
```python
# 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`:
```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

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