Alex's Slip-box

These are my org-mode notes in sort of Zettelkasten style

Electron and react learning project

Created on August 1, 2025

Updated on August 3, 2025

:ID: C5149989-9B88-4C01-9453-E00707B59535

# Mixxx Claude Assistant - Project Requirements & Plan

# Project Overview

A cross-platform Electron desktop application that provides an intelligent interface to Mixxx DJ software’s music library using Claude AI for playlist generation and music discovery.

# Core Functionality

# 1. Database Integration

  • Read-only access to mixxxdb.sqlite
  • Auto-detection of Mixxx database location by platform
  • Manual file selection as fallback option
  • Real-time monitoring for database changes with automatic refresh
  • Lock contention handling with retry logic and user error notifications
  • Read and write access to an application database (also sqlite)

# 2. Library Management

  • Display tracks, crates, and playlists from Mixxx database
  • Sortable table interface with comprehensive track metadata
  • Search and filtering capabilities across all library content
  • Real-time updates when Mixxx database changes

# 3. Claude AI Integration

  • User-configurable API key storage in application settings
  • Natural language queries about music library content
  • Intelligent playlist generation based on user prompts
  • Context-aware responses using actual library data

# 4. Playlist Export

  • Generate Extended M3U format playlists
  • Include track names and metadata in export
  • Local file system export for manual Mixxx import
  • User-friendly file save dialogs

# Technical Architecture

# Technology Stack

  • Frontend: React + Bootstrap for responsive UI
  • Backend: Electron main process with Node.js
  • Database: SQLite3 with read-only access
  • AI Integration: Anthropic Claude API
  • File Monitoring: Node.js file system watchers

# Database Schema Integration

  • Application database

    Schema will depend on the application state that will need to be persisted. Specific database schema TBD.

  • mixxxdb.sqlite
    • Primary Tables
      • library: Main track metadata (artist, title, album, BPM, key, genre, etc.)
      • track_locations: File paths and metadata
      • crates: User-created track collections
      • crate_tracks: Track-to-crate relationships
      • Playlists: User playlists
      • PlaylistTracks: Playlist contents
    • Metadata Available to Claude
      • Track identification (artist, title, album)
      • Technical specs (BPM, key, duration, bitrate)
      • Categorization (genre, year, rating)
      • User organization (crates, playlists)
      • Play statistics (times played, last played)

# Platform-Specific Database Locations

Platform Default Path
Windows C:\Users\<Username>\AppData\Local\Mixxx\mixxxdb.sqlite
macOS ~/Library/Containers/org.mixxx.mixxx/Data/Library/Application Support/Mixxx/mixxxdb.sqlite
Linux ~/.mixxx/mixxxdb.sqlite

# User Interface Design

# Proposed Layout Structure

┌─────────────────────────────────────────────────────────┐
│ Menu Bar (File, Settings, Help)                        │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────────────────────┐ │
│ │   Navigation    │ │                                 │ │
│ │   Sidebar       │ │        Main Content Area        │ │
│ │                 │ │                                 │ │
│ │ • Library       │ │   ┌─────────────────────────┐   │ │
│ │ • Crates        │ │   │   Library Table         │   │ │
│ │ • Playlists     │ │   │   (Sortable/Filterable) │   │ │
│ │ • Claude Chat   │ │   └─────────────────────────┘   │ │
│ │                 │ │                                 │ │
│ └─────────────────┘ └─────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ Status Bar (DB Status, Connection Status)              │
└─────────────────────────────────────────────────────────┘

# Key UI Components

  • 1. Library Table
    • Columns: Artist, Title, Album, BPM, Key, Genre, Duration, Rating
    • Features: Click-to-sort, multi-column filtering, search bar
    • Bootstrap Components: Table, Form controls, Input groups
  • 2. Claude Chat Interface
    • Chat-style interface for natural language queries
    • Prompt examples for playlist generation
    • Response display with formatted playlist suggestions
    • Export buttons for generated playlists
  • 3. Settings Panel
    • API Key management with secure storage
    • Database path configuration
    • Export preferences
    • Application preferences

# Core Features Specification

# Database Operations

// Read-only database operations
- getAllTracks()
- getTracksByFilter(criteria)
- getCrates()
- getPlaylists()
- getTrackMetadata(trackId)
- searchLibrary(query)

# File System Monitoring

// Watch for database changes
- watchDatabaseFile()
- handleDatabaseUpdate()
- refreshLibraryData()
- notifyUserOfChanges()

# Claude Integration

// AI interaction methods
- sendQueryToClaude(prompt, libraryContext)
- generatePlaylist(criteria)
- formatPlaylistResponse()
- exportToM3U(playlist)

# Error Handling Strategy

# Database Lock Contention

  1. Retry Logic: 3 attempts with exponential backoff
  2. Timeout: 10-second maximum wait
  3. User Notification: Clear error message with suggested actions
  4. Graceful Degradation: Show last known data state

# API Failures

  1. Network Issues: Retry with timeout
  2. Authentication: Clear API key validation messages
  3. Rate Limiting: Respect API limits with user feedback
  4. Service Unavailable: Offline mode with cached responses

# File System Issues

  1. Missing Database: Guide user to locate file manually
  2. Permission Errors: Clear instructions for file access
  3. Corrupted Database: Validation and recovery suggestions

# Security Considerations

# API Key Management

  • Encrypted storage using Electron’s safeStorage API
  • No plaintext storage of sensitive credentials
  • Secure transmission to Anthropic API only

# Database Access

  • Read-only mode enforcement
  • SQL injection prevention through parameterized queries
  • File permission validation

# Development Phases

# Phase 1: Foundation

  • Set up Electron + React + Bootstrap boilerplate
  • Implement database auto-detection and manual selection
  • Create basic library table with sorting/filtering

# Phase 2: Core Features

  • Add Claude API integration
  • Implement settings management
  • Create chat interface for AI queries

# Phase 3: Advanced Features

  • Add real-time database monitoring
  • Implement M3U export functionality
  • Polish UI/UX and error handling

# Phase 4: Testing & Distribution

  • Cross-platform testing
  • Performance optimization
  • Build and packaging setup

# Success Criteria

  • ✅ Successfully reads Mixxx database across all platforms
  • ✅ Provides intuitive library browsing with search/filter
  • ✅ Enables natural language queries about music collection
  • ✅ Generates contextually relevant playlist suggestions
  • ✅ Exports usable M3U files for Mixxx import
  • ✅ Handles errors gracefully with clear user feedback
  • ✅ Updates automatically when Mixxx database changes

# Questions and considerations

# Database monitoring

  • How frequently to poll for changes?
  • Consider using SQLite’s PRAGMA user_version to detect schema changes
  • Might want to hash the database file or check modification timestamps before doing full refreshes.

# Claude context management

  • How to handle large libraries that may exceed context window?
  • Limit the columns to include to only the ones that would be useful.
  • Could I have users choose which crates, playlists, or genres to include in the library context?
  • Use prompt caching
  • Include instructions for harmonic mixing. Include the camelot wheel.

# Logging

# Additional features

  • Keyboard shortcuts
  • Dark mode
  • Playlist description

    Generate a Soundcloud description and tracklist to accompany the playlist

# Electron security

  • Should I disable nodejs integration in renderer process?
  • Should I use context isolation?

Search Results