moto-adv-website/MEDIA_MANAGEMENT.md

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

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