MyClub/DOCS/ZONERAMA_GALLERY_FIX.md

Zonerama Gallery Fix - Implementation Summary

Problem Description

The Zonerama gallery was not displaying any photos on the admin page or frontend, despite having profile data in zonerama_profile.json.

Root Cause

1. Profile fetch (zonerama_profile.json) only contained album metadata without photos (fetched with photo_limit=0)
2. Album storage (zonerama_albums.json) didn't exist - individual albums with photos were never fetched
3. Flat files (zonerama_flat.json and gallery.json) were empty because there were no albums with photos to flatten
4. Frontend reads from zonerama_flat.json → displays nothing

Solution Implemented

Backend Changes (internal/services/prefetch_service.go)

Modified fetchZonerama() function:

1. Fetch profile with album metadata (as before)
2. NEW: Fetch each album individually with photos using the Zonerama API
3. NEW: Store albums in zonerama_albums.json with all photo data
4. NEW: Regenerate flat files for frontend consumption

Added fetchZoneramaAlbums() helper function:

• Fetches individual albums from the profile
• Calls the Zonerama API /zonerama-album endpoint for each album
• Configurable photo limit per album (default: 50, env: ZONERAMA_PHOTO_LIMIT)
• Includes retry logic and delays between requests to avoid overwhelming the API

Frontend Changes (frontend/src/components/home/PhotosSection.tsx)

Updated the photo manifest loading to use fallback paths:

1. Primary: /cache/prefetch/zonerama_flat.json (new unified location)
2. Fallback 1: /cache/prefetch/zonerama/manifest.json (legacy path)
3. Fallback 2: /cache/prefetch/gallery.json (alternative)

Data Flow

1. fetchZonerama() is called (profile URL)
   ↓
2. Fetch profile → save to zonerama_profile.json (album metadata only)
   ↓
3. Parse albums from profile
   ↓
4. For each album:
   - Fetch album with photos from API
   - Collect album data with photos
   ↓
5. Save all albums → zonerama_albums.json
   ↓
6. RegenerateFlatGalleryFiles()
   - Read zonerama_albums.json
   - Flatten all photos from all albums
   - Write to zonerama_flat.json and gallery.json
   ↓
7. Frontend reads zonerama_flat.json → displays photos

Configuration

Environment Variables

• ZONERAMA_ALBUM_LIMIT: Max number of albums to fetch from profile (default: 10)
• ZONERAMA_PHOTO_LIMIT: Max photos per album (default: 50)
• ZONERAMA_FETCH_INTERVAL_MINUTES: How often to refresh (default: 1440 = daily)
• ENABLE_ZONERAMA_PREFETCH: Enable/disable Zonerama fetching (default: true)

How to Trigger Album Fetch

Automatic (Recommended)

The system will automatically fetch albums:

• On startup (after 15 seconds)
• Daily (configurable interval)

Manual Trigger

Option 1: Admin Panel

1. Go to Admin → Settings → Sociální sítě
2. Ensure Zonerama URL is configured
3. Go to Admin → Galerie (or trigger via prefetch)
4. Click "Spustit stažení" button

Option 2: API Call

POST /api/v1/admin/prefetch/trigger
Authorization: Bearer <admin-token>

Option 3: Direct Service Call (for testing)

# Trigger Zonerama refresh directly
curl "http://localhost:8080/api/v1/admin/prefetch/trigger" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Files Generated

After successful fetch, you should have:

1. cache/prefetch/zonerama_profile.json

   • Profile metadata with album list (no photos inside albums)
   • Source of truth for which albums exist

2. cache/prefetch/zonerama_albums.json ← NEW

   • Array of albums, each with full photo data
   • This is the main storage for album+photo data

3. cache/prefetch/zonerama_flat.json ← NEW (regenerated)

   • Flattened list of all photos from all albums
   • Used by admin page and frontend

4. cache/prefetch/gallery.json ← NEW (regenerated)

   • Same content as zonerama_flat.json (for compatibility)

5. cache/prefetch/zonerama_flat.json.hdr ← NEW

   • Metadata (fetched_at, source link)

Verification

Check if albums were fetched:

# Should show albums with photos
cat cache/prefetch/zonerama_albums.json | jq '.[0].photos | length'

# Should show flattened photos
cat cache/prefetch/zonerama_flat.json | jq 'length'

Check admin page:

1. Go to /admin/zonerama
2. Should display photo count and photos in grid
3. "Počet fotek" should be > 0

Check frontend:

1. Go to homepage
2. "Fotogalerie" section should show 6 photos

Troubleshooting

No photos showing after fetch

1. Check Zonerama URL is configured:

   cat cache/prefetch/settings.json | jq '.zonerama_url'
   

2. Check profile was fetched:

   cat cache/prefetch/zonerama_profile.json | jq '.albums | length'
   

3. Check albums were fetched:

   ls -lh cache/prefetch/zonerama_albums.json
   cat cache/prefetch/zonerama_albums.json | jq 'length'
   

4. Check flat files were generated:

   cat cache/prefetch/zonerama_flat.json | jq 'length'
   

5. Check logs for errors:

   # Look for "[prefetch] Zonerama" messages
   grep "Zonerama" logs/app.log
   

API Rate Limiting

The implementation includes:

• 500ms delay between album fetches
• Exponential backoff on profile fetch (3 retries)
• Configurable limits via environment variables

If you hit rate limits, you can:

• Reduce ZONERAMA_ALBUM_LIMIT (fetch fewer albums)
• Reduce ZONERAMA_PHOTO_LIMIT (fewer photos per album)
• Increase ZONERAMA_FETCH_INTERVAL_MINUTES (fetch less frequently)

API Endpoints

Public

• GET /api/v1/gallery/albums - Get all albums
• GET /api/v1/gallery/albums/:id - Get single album with photos

Admin

• GET /api/v1/admin/gallery/profile - Get Zonerama profile metadata
• POST /api/v1/admin/gallery/albums/fetch - Fetch single album by URL
• DELETE /api/v1/admin/gallery/albums/:id - Delete album from collection
• POST /api/v1/admin/prefetch/trigger - Trigger full prefetch (includes Zonerama)

Admin Features

Fetch Individual Albums

Admins can manually add albums:

POST /api/v1/admin/gallery/albums/fetch
{
  "link": "https://eu.zonerama.com/FKKofolaKrnov/Album/13939668",
  "photo_limit": 50
}

This allows:

• Adding new albums not in the profile
• Re-fetching specific albums with updated photos
• Fetching with custom photo limits

Album Management

• View all fetched albums: GET /api/v1/gallery/albums
• Delete unwanted albums: DELETE /api/v1/admin/gallery/albums/:id
• Albums are automatically included in flat files after add/delete

Notes

• Albums are fetched with photos inline (not downloaded to disk)
• Photos are served via proxy to avoid CORS issues
• The system maintains both profile metadata and full album data
• Flat files are regenerated automatically after any album operation
• Frontend has fallback logic for backward compatibility