Media Library - CAFH Platform

The Media Library is a centralized system for uploading, organizing, and managing all media assets used across the CAFH Platform including images, videos, documents, and audio files.

Media Asset Structure

Assets are defined with comprehensive metadata (types.ts:318-329):

export interface MediaAsset {
  id: string;
  name: string;
  type: 'image' | 'video' | 'document' | 'audio';
  url: string;
  size: string;
  dimensions?: string;
  uploadedAt: string;
  tags: string[];
  folderId?: string;
}

Accessing the Media Library

Navigate to Library

Go to CMS → Media Library in the admin panel

Browse Assets

View all uploaded media in grid or list view

Filter by Type

Use type filters: All, Images, Videos, Documents, Audio

Search Assets

Search by filename, tags, or metadata

Uploading Media

Supported File Types

Images
Videos
Documents
Audio

Formats: JPEG, PNG, GIF, WebP, SVGMax Size: 10MB per fileRecommended: WebP for photos (best compression)Use Cases: Featured images, blog photos, page graphics

Upload Process

Click Upload Button

Select “Upload Media” in the Media Library toolbar

Choose Files

Select one or multiple files from your device

Add Metadata

Enter filename, tags, and optional description

Assign to Folder

Optionally place in a folder for organization

Upload

Files are processed and added to the library

Media Management UI

The Media Library UI is implemented in AdminViews.tsx with these views:

Grid View

Visual thumbnail grid showing:

Asset thumbnails
File type icons
Asset names
Quick action buttons (view, edit, delete)

List View

Detailed table showing:

Filename
Type
Size
Dimensions (for images/videos)
Upload date
Tags
Actions

View Toggle

Switch between views using icons in the toolbar:

<Grid size={18} />  // Grid view
<List size={18} />  // List view

Organizing Media

Folder System

Create folders to organize assets by project or type:

export interface MediaFolder {
  id: string;
  name: string;
  parentId?: string;  // For nested folders
}

Recommended Folder Structure

📁 Media Library
├── 📁 Blog
│   ├── 📁 2024
│   ├── 📁 2023
│   └── 📁 Featured Images
├── 📁 Pages
│   ├── 📁 Heroes
│   ├── 📁 Icons
│   └── 📁 Backgrounds
├── 📁 Events
│   ├── 📁 Posters
│   └── 📁 Galleries
├── 📁 Resources
│   ├── 📁 PDFs
│   ├── 📁 Audio
│   └── 📁 Videos
└── 📁 Logos
    ├── 📁 Primary
    └── 📁 Variations

Tagging System

Tags enable cross-folder searching and filtering:

Best Practices for Tags

Use lowercase for consistency
Include broad categories: meditation, retreat, community
Add specific descriptors: hero-image, thumbnail, icon
Use location tags: santiago, online, argentina
Include year for dated content: 2024

Example Tag Sets

Blog Featured Image:

["blog", "featured", "meditation", "2024"]

Event Poster:

["event", "poster", "retiro", "santiago", "2024"]

Resource PDF:

["resource", "pdf", "guide", "method", "beginner"]

Searching and Filtering

The Media Library supports advanced search (storage.ts:419-424):

// Search by query and type
db.media.search("meditation", "image")

// Returns assets matching:
// - Filename contains "meditation"
// - Tags include "meditation"
// - Type is "image"

Search Operators

Operator	Example	Result
Basic	`meditation`	Matches filename or tags
Type filter	`type:image`	Only images
Tag filter	`tag:hero`	Only assets with “hero” tag
Date filter	`date:2024`	Uploaded in 2024

Image Optimization

Recommended Sizes

Use Case	Dimensions	Format	Max Size
Hero backgrounds	1920x1080px	WebP/JPEG	300KB
Featured images	1200x630px	WebP/JPEG	200KB
Blog thumbnails	600x400px	WebP/JPEG	100KB
Icons	512x512px	PNG/SVG	50KB
Logos	Variable	SVG/PNG	30KB

Optimization Tools

TinyPNG/TinyJPG: Compress without quality loss
Squoosh: Google’s web-based optimizer
ImageOptim: Mac desktop app
GIMP/Photoshop: Manual optimization

Convert to WebP format for 25-35% smaller file sizes with same visual quality.

Managing Assets

Editing Asset Metadata

Select Asset

Click on any asset in the library

Open Editor

Click the edit icon or select “Edit Details”

Update Fields

Modify name, tags, or folder assignment

Save Changes

Changes are saved immediately to storage

Deleting Assets

Deleting media assets is permanent. Assets used in pages or posts will show broken links.

Select Asset

Click the checkbox on one or more assets

Click Delete

Press the delete button in the toolbar

Confirm Deletion

A dialog warns about permanent removal

Asset Removed

The asset is immediately removed from storage

Deletion is handled by (storage.ts:413-418):

db.media.delete(assetId)

Bulk Operations

Select multiple assets to:

Add tags: Apply tags to all selected
Move to folder: Bulk organize
Delete: Remove multiple assets
Download: Get a zip of selected files

Using Assets in Content

In Pages Editor

When adding an Image section:

Click “Select from Media Library”
Browse or search for the asset
Click to insert the URL automatically

In Blog Posts

For featured images:

In the image URL field, click the media icon
Select an image from the library
The URL populates automatically

In Custom Code

Reference assets by their URL:

<img src="/media/hero-meditation.jpg" alt="Meditation space" />

Storage and Performance

Media assets are stored with this configuration (storage.ts:400-425):

Storage Key	Content
`cafh_media_v1`	Array of MediaAsset objects

Storage Considerations

localStorage limit: ~10MB total for all data
Asset URLs: Typically stored as base64 or external URLs
Large files: Should be hosted externally (CDN)
Performance: Keep total assets under 500 for optimal loading

For production sites with extensive media needs, integrate with a CDN like Cloudinary or AWS S3.

Media Library Maintenance

Regular Tasks

Monthly Audit

Remove unused assets
Check for duplicate files
Verify all links still work
Update tags for better organization

Quarterly Review

Archive old event images
Optimize large files
Reorganize folder structure
Document naming conventions

Annual Cleanup

Delete deprecated assets
Migrate to CDN if needed
Review and update metadata
Export backup of all media

Access Control

Media Library access is role-based:

Role	Permissions
SUPER_ADMIN	Full access: upload, edit, delete
ADMIN	Upload, edit own uploads, view all
EDITOR	Upload, edit own uploads
MEMBER	View public assets only
GUEST	No access

Role management is covered in the User Role Management documentation.

Best Practices

File Naming

✅ Good Names:

hero-meditation-room-2024.jpg
retreat-poster-santiago-march.pdf
podcast-episode-12-spirituality.mp3

❌ Poor Names:

IMG_1234.jpg
untitled.pdf
recording.mp3

Alt Text

Always include descriptive alt text for images:

<!-- Good -->
<img src="meditation.jpg" alt="Person meditating in peaceful garden at sunset" />

<!-- Poor -->
<img src="meditation.jpg" alt="image" />

Copyright

Only upload media you own or have permission to use
Store license info in asset description
Credit photographers/creators when required
Use royalty-free stock for generic images

Troubleshooting

Upload Fails

Check file size: Must be under type-specific limit
Verify format: Use supported file types
Clear cache: Browser cache may cause issues
Check quota: localStorage may be full

Broken Image Links

Verify URL: Check that the asset still exists
Check permissions: Asset may be private
Update references: If moved to CDN, update URLs

Slow Loading

Optimize images: Compress to WebP format
Use CDN: Move large files to external hosting
Lazy load: Implement lazy loading for galleries
Reduce size: Resize images to needed dimensions

CMS Overview

Complete content management system

Pages Editor

Using media in custom pages

Blog Management

Adding images to blog posts

Content Management

Member Management

Communications

Events & Activities

Analytics

Settings

​Media Asset Structure

​Accessing the Media Library

​Uploading Media

​Supported File Types

​Upload Process

​Media Management UI

​Grid View

​List View

​View Toggle

​Organizing Media

​Folder System

​Recommended Folder Structure

​Tagging System

​Best Practices for Tags

​Example Tag Sets

​Searching and Filtering

​Search Operators

​Image Optimization

​Recommended Sizes

​Optimization Tools

​Managing Assets

​Editing Asset Metadata

​Deleting Assets

​Bulk Operations

​Using Assets in Content

​In Pages Editor

​In Blog Posts

​In Custom Code

​Storage and Performance

​Storage Considerations

​Media Library Maintenance

​Regular Tasks

​Access Control

​Best Practices

​File Naming

​Alt Text

​Copyright

​Troubleshooting

​Upload Fails

​Broken Image Links

​Slow Loading

​Related Documentation

CMS Overview

Pages Editor

Blog Management

Build docs developers (and LLMs) love

Media Asset Structure

Accessing the Media Library

Uploading Media

Supported File Types

Upload Process

Media Management UI

Grid View

List View

View Toggle

Organizing Media

Folder System

Recommended Folder Structure

Tagging System

Best Practices for Tags

Example Tag Sets

Searching and Filtering

Search Operators

Image Optimization

Recommended Sizes

Optimization Tools

Managing Assets

Editing Asset Metadata

Deleting Assets

Bulk Operations

Using Assets in Content

In Pages Editor

In Blog Posts

In Custom Code

Storage and Performance

Storage Considerations

Media Library Maintenance

Regular Tasks

Access Control

Best Practices

File Naming

Alt Text

Copyright

Troubleshooting

Upload Fails

Broken Image Links

Slow Loading

Related Documentation