# Media Management for Motorcycle Adventure Community

## Overview

The application now uses an organized media folder structure where each post has its own dedicated folder for storing images, GPX files, and other media content.

## Folder Structure

```
app/static/media/posts/
├── post_abc12345_20250723/
│   ├── images/
│   │   ├── cover_image.jpg
│   │   ├── route_photo_1.jpg
│   │   └── route_photo_2.jpg
│   └── gpx/
│       └── route_track.gpx
├── post_def67890_20250724/
│   ├── images/
│   └── gpx/
└── ...
```

## Post Content Storage Strategy

### Database Storage (Recommended ✅)
- **Post metadata**: title, subtitle, content, difficulty, publication status
- **Relationships**: author, comments, likes
- **Media references**: filenames and metadata stored in database
- **Benefits**: 
  - Fast queries and searching
  - Proper relationships and constraints
  - ACID compliance
  - Easy backups with database tools
  - Scalability for large amounts of posts

### File Storage
- **Media files**: images, GPX files stored in organized folders
- **Benefits**:
  - Direct web server access (faster serving)
  - Easy file management
  - Reduced database size
  - CDN compatibility

## Database Schema

### Posts Table
- `media_folder`: String field containing the unique folder name for this post's media
- Content stored as TEXT in the database for optimal performance

### PostImage Table
- `filename`: Stored filename (unique)
- `original_name`: User's original filename
- `is_cover`: Boolean indicating if this is the cover image
- `post_id`: Foreign key to posts table

### GPXFile Table
- `filename`: Stored filename (unique)
- `original_name`: User's original filename
- `post_id`: Foreign key to posts table

## Media Folder Naming Convention

Format: `post_{8-char-uuid}_{YYYYMMDD}`
- Example: `post_abc12345_20250723`
- Ensures uniqueness and chronological organization

## File Upload Process

1. **Post Creation**: 
   - Generate unique media folder name
   - Create post record in database
   - Create folder structure in `app/static/media/posts/`

2. **File Upload**:
   - Save files to post-specific subfolders
   - Store metadata in database
   - Generate thumbnails (for images)

3. **File Access**:
   - URLs: `/static/media/posts/{media_folder}/images/{filename}`
   - Direct web server serving for performance

## Migration and Management

### Manual Migration Script
```bash
python manage_media.py --all
```

### Available Commands
- `--create-folders`: Create media folders for existing posts
- `--migrate-files`: Move files from old structure to new structure
- `--clean-orphaned`: Remove unused media folders
- `--stats`: Show storage statistics

## Security Considerations

1. **File Type Validation**: Only allowed image and GPX file types
2. **File Size Limits**: Configurable maximum file sizes
3. **Filename Sanitization**: Secure filename generation with UUIDs
4. **Access Control**: Media files served through static file handler

## Performance Optimizations

1. **Image Compression**: Automatic JPEG compression with 85% quality
2. **Image Resizing**: Automatic thumbnail generation and size limits
3. **Direct File Serving**: Static files served directly by web server
4. **CDN Ready**: File structure compatible with CDN distribution

## Backup Strategy

1. **Database**: Regular database backups include all post content and metadata
2. **Media Files**: File system backups of `app/static/media/posts/` directory
3. **Synchronization**: Media folder names in database ensure consistency

## Development Notes

- Post content remains in database for optimal query performance
- Media files organized by post for easy management
- Backward compatibility maintained for existing installations
- Migration tools provided for seamless upgrades