Mixtape Editor Overview¶

The Mixtape Editor is a full-featured web interface for creating and editing mixtapes. It combines a Flask backend for data persistence with a sophisticated JavaScript frontend for search, playlist management, and rich markdown editing.

🎯 Purpose¶

The editor provides authenticated users with tools to:

Search and discover tracks from the music library
Build playlists with drag-and-drop track management
Write liner notes using markdown with track references
Design covers by uploading images or generating composites
Share mixtapes via QR codes
Track progress of background audio caching

All functionality is protected by authentication and persists mixtapes as JSON files on disk.

✨ Features¶

Feature	Description
Library Search	Full-text search with highlighting powered by SQLite FTS5
Playlist Management	Drag-and-drop reordering, preview playback, track removal
Cover Handling	Upload custom images or generate grid composites from track art
Liner Notes	Markdown editor (EasyMDE) with track reference syntax (#1, #2-4)
Save/Update	Creates new mixtapes or updates existing ones with timestamps
QR Code Sharing	Generate simple QR codes or enhanced versions with cover art
Background Caching	Automatic audio transcoding with real-time progress updates
Unsaved Changes Detection	Warns before leaving with unsaved work

🏗️ Architecture¶

System Overview¶

graph TB
    User[Authenticated User]

    Frontend[Frontend JavaScript]
    Backend[Flask Backend]

    Search[search.js]
    Playlist[playlist.js]
    Notes[editorNotes.js]
    UI[ui.js]

    Routes[Flask Routes]
    Collection[MusicCollectionUI]
    Manager[MixtapeManager]
    Cache[AudioCache]

    User --> Frontend
    Frontend --> Backend

    Frontend --> Search
    Frontend --> Playlist
    Frontend --> Notes
    Frontend --> UI

    Backend --> Routes
    Routes --> Collection
    Routes --> Manager
    Routes --> Cache

    style Frontend fill:#4a6fa5,color:#fff
    style Backend fill:#c65d5d,color:#fff

Hold "Alt" / "Option" to enable pan & zoom

Component Split¶

Backend (Flask):

Route handlers for all editor operations
Integration with music library search
Mixtape data persistence (JSON files)
Cover image processing and storage
Background audio caching orchestration

Frontend (JavaScript):

ES6 modules with clear responsibilities
Real-time search with debouncing
Drag-and-drop playlist management
Markdown editor with custom preview
Progress modal for long operations

🗺️ Quick Reference¶

Flask Routes¶

HTTP	URL Pattern	Handler	Purpose
`GET`	`/editor/`	`new_mixtape()`	Blank editor for new mixtape
`GET`	`/editor/<slug>`	`edit_mixtape(slug)`	Load existing mixtape for editing
`GET`	`/editor/search?q=`	`search()`	Search library (50 results max)
`GET`	`/editor/artist_details?artist=`	`artist_details()`	Get artist's albums
`GET`	`/editor/album_details?release_dir=`	`album_details()`	Get album's tracks
`POST`	`/editor/save`	`save_mixtape()`	Create or update mixtape
`GET`	`/editor/progress/<slug>`	`progress_stream(slug)`	SSE progress updates
`POST`	`/editor/generate_composite`	`generate_composite()`	Create cover from track art

See: Backend API Documentation

JavaScript Modules¶

Module	Responsibility
`index.js`	Page initialization and bootstrapping
`search.js`	Debounced search, results rendering
`playlist.js`	Playlist state, drag-and-drop, track management
`editorNotes.js`	EasyMDE integration, track references
`ui.js`	Cover upload, save button, unsaved changes
`progressModal.js`	SSE connection, progress display
`utils.js`	Helper functions, HTML escaping, dialogs

See: Frontend Modules Documentation

🔄 Data Flow¶

Creating a New Mixtape¶

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant MixtapeManager

    User->>Frontend: Visit /editor/
    Frontend->>Backend: GET /editor/
    Backend->>Frontend: Render empty form

    User->>Frontend: Search, add tracks
    User->>Frontend: Write notes, upload cover
    User->>Frontend: Click Save

    Frontend->>Backend: POST /editor/save
    Backend->>Backend: Generate UUID slug
    Backend->>Backend: Enrich track metadata
    Backend->>MixtapeManager: save(mixtape_data)
    MixtapeManager->>Backend: Success
    Backend->>Backend: Trigger background caching
    Backend->>Frontend: {success: true, slug, url}

    Frontend->>Frontend: Update URL to /editor/<slug>
    Frontend->>Frontend: Show QR share button

Hold "Alt" / "Option" to enable pan & zoom

Editing an Existing Mixtape¶

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant MixtapeManager

    User->>Frontend: Visit /editor/<slug>
    Frontend->>Backend: GET /editor/<slug>
    Backend->>MixtapeManager: get(slug)
    MixtapeManager->>Backend: Mixtape data
    Backend->>Frontend: Render pre-filled form

    User->>Frontend: Modify tracks/notes
    User->>Frontend: Click Save

    Frontend->>Backend: POST /editor/save (with slug)
    Backend->>MixtapeManager: update(slug, data)
    MixtapeManager->>Backend: Success
    Backend->>Frontend: {success: true, slug, url}

Hold "Alt" / "Option" to enable pan & zoom

🎨 UI Layout¶

Main Components¶

flowchart TB
    App["Mixtape Editor Screen"]

    Header["Header\nCreate Mixtape / Edit: Title"]
    Search["Search Bar\n🔍 Search library… | ℹ️ | ⟳"]

    Content["Main Content"]

    Library["Library Results\n• Artists\n• Albums\n• Tracks\n[Add]\n[Load more…]"]
    Mixtape["My Mixtape\n[Cover]\nTitle\nTabs: Tracks | Notes\n1. Track one\n2. Track two\n3. Track three\n[Clear Playlist]"]

    Player["Bottom Player\n▶️ Now Playing: Track • Artist"]
    Floating["Floating Actions (Mobile)\n💾 Save | 🎵 Tracks"]

    App --> Header --> Search --> Content --> Player
    Content --> Library
    Content --> Mixtape
    App -.-> Floating

Hold "Alt" / "Option" to enable pan & zoom

Modals¶

Cover Options - Upload image or generate composite
Progress Modal - Background caching progress with log
QR Share Modal - Display and download QR codes
Generic Alerts/Confirms - User confirmations

🚀 Quick Start Guide¶

For Backend Developers¶

Understanding the API:

Read Backend API Documentation
Focus on route handlers section
Review API contracts (JSON schemas)
Check authentication requirements

Common tasks:

Adding new search filters → Modify search() handler
Changing save logic → Update save_mixtape()
New metadata fields → Update JSON schema

For Frontend Developers¶

Understanding the modules:

Read Frontend Modules Documentation
Understand module relationships
Review state management (playlist array)
Check event flow diagrams

Common tasks:

Adding UI feature → Extend ui.js
Changing search behavior → Modify search.js
Playlist customization → Update playlist.js

For Both¶

Full feature development:

Design data flow (frontend → backend → storage)
Update API contract backend
Implement backend route handler
Create/modify frontend module
Update both documentation pages

🔧 Common Development Tasks¶

Adding a New Metadata Field¶

Backend:

# In save_mixtape()
mixtape_data = {
    'title': data.get('title'),
    'new_field': data.get('new_field'),  # Add here
    # ... rest
}

Frontend:

// In ui.js saveMixtape()
const payload = {
    title: titleInput.value,
    new_field: newFieldInput.value,  // Add here
    // ... rest
};

Extending Search Results¶

Backend:

# In search()
results = collection.search_highlighting(query, limit=50)
# Process results to add new fields
return jsonify(results)

Frontend:

// In search.js renderResults()
results.forEach(result => {
    // Add new rendering logic
});

Adding Progress Tracking¶

Backend:

# In any long operation
tracker = audio_cache.get_progress_tracker(slug)
tracker.update(step='processing', current=5, total=10)

Frontend:

// Progress modal automatically picks up SSE events
showProgressModal(slug);

📚 Detailed Documentation¶

Backend Development¶

Backend API Documentation

Complete guide to Flask routes, server-side logic, and API contracts:

Route handlers and authentication
Data flow for create/edit/save operations
Helper functions and utilities
JSON schemas for requests/responses
Progress streaming (SSE)
Cover generation
Error handling
Testing

Frontend Development¶

Frontend Modules Documentation

Complete guide to JavaScript architecture and modules:

ES6 module structure
Module responsibilities and relationships
Search implementation
Playlist management and drag-and-drop
Markdown editor integration
UI interactions and state management
Progress modal and SSE connection
Helper utilities

🧪 Testing¶

Backend Testing¶

# Test new mixtape creation
curl http://localhost:5000/editor/

# Test search
curl "http://localhost:5000/editor/search?q=beatles"

# Test save (requires auth cookie)
curl -X POST http://localhost:5000/editor/save \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","tracks":[]}'

Frontend Testing¶

Manual testing:

Open /editor/ in browser
Search for tracks
Add to playlist
Drag to reorder
Save mixtape
Verify progress modal appears

Console debugging:

// Check playlist state
console.log(playlist);

// Monitor search
window.addEventListener('search:results', (e) => {
    console.log('Search results:', e.detail);
});

Core Systems¶

Music Library - Search and metadata extraction
Mixtape Manager - JSON file persistence
Audio Caching - Background transcoding
Cover Art System - Image processing

Routes¶

Browser Routes - Public mixtape browsing
Playback Routes - Audio streaming
QR Code Routes - QR generation

Frontend¶

Player Controls - Preview playback
PWA Features - Progressive web app

🎓 Learning Path¶

New to the editor?

Start here - This overview (you are here)
Backend focus - Read Backend API
Frontend focus - Read Frontend Modules
Hands-on - Create a test mixtape

Adding a feature?

Design - Plan data flow (frontend → backend → storage)
Backend - Implement route handler (see Backend API)
Frontend - Update or create module (see Frontend Modules)
Test - Manual testing + console debugging
Document - Update both documentation pages

The editor is the creative heart of Mixtape Society. For implementation details, see the Backend API and Frontend Modules documentation linked above.

Mixtape Editor Overview¶

🎯 Purpose¶

✨ Features¶

🏗️ Architecture¶

System Overview¶

Component Split¶

🗺️ Quick Reference¶

Flask Routes¶

JavaScript Modules¶

🔄 Data Flow¶

Creating a New Mixtape¶

Editing an Existing Mixtape¶

🎨 UI Layout¶

Main Components¶

Modals¶

🚀 Quick Start Guide¶

For Backend Developers¶

For Frontend Developers¶

For Both¶

🔧 Common Development Tasks¶

Adding a New Metadata Field¶

Extending Search Results¶

Adding Progress Tracking¶

📚 Detailed Documentation¶

Backend Development¶

Frontend Development¶

🧪 Testing¶

Backend Testing¶

Frontend Testing¶

🔗 Related Documentation¶

Core Systems¶

Routes¶

Frontend¶

🎓 Learning Path¶