AI-powered album artwork management system with intelligent duplicate detection and metadata matching.

• 🎨 AI Processing - Automated artwork enhancement and optimization
• 🔍 Smart Duplicate Detection - Multi-pass matching using perceptual hashing, metadata, and exact IDs
• 🎵 Spotify Integration - Import entire playlists with one click
• 🎼 Tidal Integration - Support for Tidal music service
• 📊 Decision Logging - Complete transparency in matching decisions
• 🖼️ Image Management - Original and processed image storage
• 🌐 Web Interface - Modern UI for upload and monitoring

./run_test.sh

Visit: http://localhost:8080

./run_production.sh

⚠️ Always use test environment for development!

.
├── docs/                   # 📚 All documentation
│   ├── README.md          # Documentation index
│   ├── diagrams/          # System diagrams
│   └── *.md               # Guides and references
├── server/                # 🌐 HTTP server and API endpoints
├── matcher/               # 🔍 Duplicate detection algorithms
├── processor/             # 🎨 AI image processing
├── storage/               # 💾 MinIO object storage interface
├── spotify/               # 🎵 Spotify API client
├── tidal/                 # 🎼 Tidal API client
├── models/                # 📦 Data structures
├── web/                   # 🖥️ Web interface (HTML/CSS/JS)
├── utilities/             # 🛠️ Helper scripts and tools
├── run_test.sh           # Start test server
├── run_production.sh     # Start production server
└── clear_test_db.sh      # Clear test database safely

📚 Full Documentation

• Quick Reference - Fast overview
• Database Environments - Test vs Production
• Matching Workflow - How duplicate detection works
• Web Interface Guide - Using the UI

1. Start server: ./run_test.sh
2. Visit: http://localhost:8080/web/upload.html
3. Upload image with metadata
4. View decision: http://localhost:8080/decisions

1. Configure credentials in run_test.sh
2. Visit: http://localhost:8080/web/spotify_import.html
3. Paste playlist URL
4. Monitor import progress

./clear_test_db.sh

Pass 1: Find Best Match

• Exact ID matching (Spotify, Tidal, etc.)
• Perceptual hash comparison
• Metadata fuzzy matching

Pass 2: Sanity Check

• Validates suspicious matches
• Compares metadata confidence

Pass 3: Apply Thresholds

• >= 0.95 = DUPLICATE (skip processing)
• 0.70 - 0.94 = VARIANT (skip processing)
• < 0.70 = NEW (send to AI)

MinIO Buckets:
  album-art/              # Production
  album-art-test/         # Test

Each album:
  albums/{id}/
    metadata.json         # Title, artist, IDs
    hash.json            # Perceptual hash
    original.jpg         # Uploaded image
    processed.jpg        # AI-enhanced image
  
  decision_logs/{id}.json # Matching decision

• Go - Backend server and matching logic
• MinIO - S3-compatible object storage
• HTML/CSS/JavaScript - Web interface
• Mermaid - Diagram visualization
• Spotify Web API - Playlist import
• Tidal API - Alternative music service

✅ Safe Operations

• Use test environment for development
• Clear test database anytime
• Experiment freely with test data

❌ Dangerous Operations

• Never clear production database
• Never run mc rm on album-art bucket
• Always verify bucket name before deletion

• Go 1.21+
• MinIO running on localhost:9000
• MinIO client (mc) installed

Set in run_test.sh or run_production.sh:

• MINIO_ENDPOINT - MinIO server address
• MINIO_ACCESS_KEY - MinIO credentials
• MINIO_SECRET_KEY - MinIO credentials
• MINIO_BUCKET - Target bucket name
• SPOTIFY_CLIENT_ID - Spotify API credentials
• SPOTIFY_CLIENT_SECRET - Spotify API secret

go build -o albumws

go test ./...

1. Always use test environment
2. Document new features in docs/
3. Update README if adding new commands
4. Test duplicate detection after changes

[Add your license here]

📚 Read the Full Documentation for detailed guides and references.