Stream Fav Music Sync

A web application that synchronizes music libraries between Spotify and Amazon Music platforms with bidirectional sync capabilities, conflict resolution, and administrative controls.

Core Functionality

• Bidirectional Synchronization: Sync playlists and libraries between Spotify and Amazon Music
• Conflict Resolution: Handle sync conflicts with user-controlled resolution strategies
• OAuth Authentication: Secure authentication with both music platforms
• Web Interface: Functional web interface for managing synchronization operations
• Administrative System: System configuration, user management, and monitoring tools
• Audit Logging: Comprehensive logging of sync operations and system events

Development Setup

This project uses container-first development with Finch (Docker). All Python execution happens within containers to ensure consistent, isolated development environments.

Prerequisites

• Finch installed
• Make (for convenience commands)
• Git (for version control)

Quick Start

1. Clone and setup:

   git clone <repository-url>
   cd spotify-amazon-sync
   cp .env.example .env
   

2. Configure environment: Edit .env with your OAuth credentials from Spotify and Amazon Music developer consoles.

3. Build and start:

   make build
   make up
   make init-db
   

4. Access the application:

   • Web interface: http://localhost:5000
   • Database: localhost:5432 (PostgreSQL)

Development Commands

Container Management

• make build - Build Docker containers
• make up - Start all services (app, database)
• make down - Stop all services
• make clean - Clean up containers and volumes
• finch exec spotifytoamzn-app-1 python scripts/script_name.py - Execute Python scripts in container
• make logs - View application logs (recent history)
• make logs-follow - Follow logs in real-time
• make status - Check service status
• make health-check - Verify all services are running

Database Operations

• make init-db - Initialize database with schema
• make migrate - Create new database migration
• make upgrade - Apply database migrations
• make init-migrate - Initialize Flask-Migrate (run once)

Python Execution

Never run Python directly on the host. Use these container-based patterns:

• finch exec spotifytoamzn-app-1 your-python-command - Run any Python command
• finch exec spotifytoamzn-app-1 python path/to/script.py - Run Python scripts
• make pytest ARGS="-k test_name" - Run specific tests

Container Development Standards

This project follows a container-first development approach using Finch (Docker) to ensure consistent, isolated development environments across all team members.

Core Principles

1. Container-First Development: All development activities happen inside containers
2. Host System Isolation: Host system remains clean and dependency-free
3. Consistent Environments: Identical development environment for all developers
4. Finch Runtime: Finch is the primary container runtime for this project

Project Structure

├── app/                    # Flask application
│   ├── models/            # SQLAlchemy database models
│   ├── services/          # Business logic and service layer
│   ├── routes/            # Flask route handlers and API endpoints
│   ├── templates/         # Jinja2 HTML templates
│   ├── static/            # CSS, JavaScript, fonts, and assets
│   └── utils/             # Utility functions and helpers
├── tests/                 # Comprehensive test suite
│   ├── unit/              # Unit tests (fast, isolated)
│   ├── integration/       # Integration tests (database, services)
│   ├── property/          # Property-based tests (Hypothesis)
│   ├── security/          # Security and authentication tests
│   ├── performance/       # Performance and load tests
│   └── fixtures/          # Test data factories and fixtures
├── migrations/            # Database migrations (Alembic)
├── scripts/               # Utility and maintenance scripts
├── reports/               # Test reports and coverage data
├── logs/                  # Application logs
├── compose.yml           # Docker Compose configuration
├── Dockerfile            # Container definition
├── Makefile              # Development commands
└── requirements.txt      # Python dependencies

Testing Framework

The project uses a comprehensive testing framework with pytest and Hypothesis for property-based testing.

Running Tests

# Run all tests (optimized for parallel execution)
make test

# Run specific test categories
make test-unit          # Unit tests (fast, parallel)
make test-integration   # Integration tests (serial, database)
make test-property      # Property-based tests (Hypothesis)
make test-security      # Security and authentication tests
make test-performance   # Performance and load tests

# Run with coverage analysis
make test-coverage

# Debug tests (serial execution, verbose output)
make test-debug

# Fast feedback for development
make test-fast

Test Categories

• Unit Tests: Fast, isolated component tests with mocked dependencies
• Integration Tests: Test component interactions with real database connections
• Property-Based Tests: Hypothesis-driven testing with random input generation
• Security Tests: Authentication, authorization, and vulnerability protection
• Performance Tests: Load testing and resource usage validation

Test Configuration

• Minimum coverage threshold: 80%
• Parallel execution with automatic worker detection
• Isolated test databases per worker
• Comprehensive mock services for external APIs
• Property-based tests use Hypothesis with configurable iteration counts

Configuration

Environment Variables

Copy .env.example to .env and configure:

# Database Configuration
DATABASE_URL=postgresql://user:password@db:5432/spotify_sync

# Spotify OAuth Credentials
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Amazon Music OAuth Credentials
AMAZON_CLIENT_ID=your_amazon_client_id
AMAZON_CLIENT_SECRET=your_amazon_client_secret

# Application Settings
SECRET_KEY=your_secret_key
FLASK_ENV=development

OAuth Setup

1. Spotify Developer Console:

   • Create an app at https://developer.spotify.com/dashboard
   • Add redirect URI: http://localhost:5000/oauth/spotify/callback
   • Copy Client ID and Secret to .env

2. Amazon Music Developer Console:

   • Create an app at Amazon Developer Console
   • Configure OAuth settings with appropriate scopes
   • Copy Client ID and Secret to .env

Essential Scripts

The scripts/ directory contains utility scripts for maintenance and operations:

Core Scripts

• database_utils.py - Database operations, migrations, and testing utilities
• deploy.sh - Production deployment script (supports latest and prod tags)
• startup.sh - Container startup script with initialization and error handling

REMOVED: - check_dependencies.py - Dependency validation and health checks

Development Scripts

• test_utilities.py - Test framework utilities and helpers
• validation_utilities.py - Input validation and data integrity checks

Maintenance Scripts

REMOVED: - audit_external_resources.py - External resource and dependency auditing

• security_audit_and_fixes.py - Security vulnerability scanning and fixes
• startup_initialization.py - Application startup initialization procedures

All scripts are designed to run within containers using the make script command.

API Documentation

Authentication Endpoints

• POST /login - User login with credentials
• POST /register - User registration
• GET /oauth/spotify - Initiate Spotify OAuth flow
• GET /oauth/amazon - Initiate Amazon Music OAuth flow
• GET /logout - User logout and session cleanup

Synchronization Endpoints

• GET /api/sync/status - Get current sync status and progress
• POST /api/sync/start - Start synchronization process
• GET /api/sync/history - Retrieve sync operation history
• POST /api/sync/resolve-conflict - Resolve sync conflicts

Administrative Endpoints

• GET /admin/dashboard - Administrative dashboard and system overview
• GET /admin/users - User management interface
• GET /admin/logs - System logs and audit trail
• POST /admin/config - System configuration management

Deployment

Production Deployment

1. Prepare environment:

   cp .env.example .env.production
   # Edit .env.production with production values
   

2. Deploy using script:

   ./scripts/deploy.sh prod
   

Container Architecture

• app: Main Flask application with web interface and API
• db: PostgreSQL database with persistent storage
• test: Testing service with isolated environment and test database

Development Guidelines

Container-First Development

• All development happens inside containers
• Host system remains clean and dependency-free
• Use finch exec spotifytoamzn-app-1 python scripts/script_name.py for script execution
• Never run python or pip directly on host system

Code Organization

• Business logic in app/services/
• Database models in app/models/
• API routes in app/routes/
• Utilities and helpers in app/utils/
• Templates in app/templates/
• Static assets in app/static/

Testing Best Practices

• Write tests for all new functionality
• Use appropriate test categories (unit, integration, property)
• Maintain minimum 80% code coverage
• Use mock services for external API testing
• Property-based tests for universal behavior validation

Security Considerations

• All user inputs are validated and sanitized
• CSRF protection enabled on forms
• Secure session management with encrypted cookies
• OAuth token encryption and secure storage
• SQL injection prevention through parameterized queries
• Input validation at API boundaries

Troubleshooting

Common Issues

Application won't start:

• Check .env configuration is complete
• Verify database connection settings
• Check container logs: make logs
• Ensure services are healthy: make health-check

Tests failing in parallel but passing serially:

• Check for shared state between tests
• Ensure proper database isolation
• Verify thread-safe resource access
• Use make test-debug for serial execution

OAuth authentication failing:

• Verify client credentials in .env
• Check redirect URIs in developer consoles
• Ensure proper OAuth scopes are configured
• Check network connectivity to OAuth providers

Database connection issues:

• Run make init-db to initialize database
• Check database service status: make status
• Verify database credentials in .env
• Ensure database migrations are applied: make upgrade

Performance issues:

• Use make test-performance to identify bottlenecks
• Check container resource allocation
• Monitor database query performance
• Review application logs for errors

Getting Help

1. Check application logs: make logs or make logs-follow
2. Run health checks: make health-check
3. Verify service status: make status
4. Run tests to verify functionality: make test
5. Execute specific scripts: finch exec spotifytoamzn-app-1 python scripts/debug_script.py
6. Check database connectivity: Create and run a script to test database connection

Contributing

1. Fork the repository
2. Create a feature branch from main
3. Make changes following development guidelines
4. Write tests for new functionality
5. Ensure all tests pass: make test
6. Verify code coverage: make test-coverage
7. Submit a pull request with clear description

Code Standards

• Follow PEP 8 for Python code style
• Use type hints where appropriate
• Write comprehensive docstrings
• Maintain test coverage above 80%
• Use container-based development workflow

Maintenance Guidelines

Regular Maintenance Tasks

Weekly Tasks

1. Dependency Updates: Check for security updates in requirements.txt
2. Log Review: Review application logs for errors or warnings
3. Test Execution: Run full test suite to catch regressions
4. Performance Monitoring: Check application performance metrics

Monthly Tasks

1. Container Updates: Update base container images for security patches
2. Database Maintenance: Review database performance and optimize queries
3. Documentation Review: Update documentation for any changes
4. Security Audit: Run security scans and address vulnerabilities

Quarterly Tasks

1. Dependency Audit: Review all dependencies for updates and security issues
2. Performance Analysis: Conduct thorough performance analysis
3. Backup Testing: Verify backup and restore procedures
4. Disaster Recovery: Test disaster recovery procedures

Code Quality Standards

Python Code Standards

• Follow PEP 8 style guidelines
• Use type hints for function parameters and return values
• Write comprehensive docstrings for all functions and classes
• Maintain minimum 80% test coverage
• Use meaningful variable and function names

Container Standards

• Use multi-stage Dockerfile builds for optimization
• Pin all dependency versions for reproducibility
• Use non-root users in containers for security
• Implement proper health checks for services
• Use .dockerignore to exclude unnecessary files

Testing Standards

• Write tests for all new functionality
• Use appropriate test categories (unit, integration, property)
• Mock external dependencies in unit tests
• Use property-based testing for universal behavior validation
• Maintain test isolation and avoid shared state

Security Maintenance

Regular Security Tasks

1. Dependency Scanning: Use tools to scan for vulnerable dependencies
2. Container Scanning: Scan container images for security vulnerabilities
3. OAuth Token Management: Regularly rotate OAuth client secrets
4. Database Security: Review database access patterns and permissions
5. Log Analysis: Monitor logs for suspicious activity

Security Best Practices

• Never commit secrets or credentials to version control
• Use environment variables for all configuration
• Implement proper input validation and sanitization
• Use HTTPS for all external communications
• Regularly update base container images
• Implement proper error handling that doesn't leak information

Performance Maintenance

Monitoring

• Monitor application response times
• Track database query performance
• Monitor container resource usage
• Track test execution times

Optimization

• Optimize slow database queries
• Review and optimize container resource allocation
• Implement caching where appropriate
• Optimize test execution for faster feedback

Troubleshooting Guidelines

Common Issues and Solutions

Container Won't Start

1. Check .env configuration
2. Verify port availability
3. Check container logs: make logs
4. Rebuild containers: make build

Tests Failing Intermittently

1. Check for race conditions in parallel tests
2. Verify test isolation
3. Run tests serially: make test-debug
4. Check for shared state between tests

Database Connection Issues

1. Verify database service is running: make status
2. Check database credentials in .env
3. Restart database service: make down && make up
4. Initialize database: make init-db

Performance Degradation

1. Check container resource usage
2. Analyze database query performance
3. Review application logs for errors
4. Run performance tests: make test-performance

Debugging Process

1. Identify the Problem: Gather symptoms and error messages
2. Check Logs: Review application and container logs
3. Isolate the Issue: Use minimal reproduction steps
4. Test Hypothesis: Make targeted changes and test
5. Document Solution: Update documentation with solution

Backup and Recovery

Backup Procedures

1. Database Backups: Automated daily backups of PostgreSQL database
2. Configuration Backups: Version control all configuration files
3. Container Images: Tag and store container images for rollback
4. Environment Backups: Backup .env files securely

Recovery Procedures

1. Database Recovery: Restore from most recent backup
2. Application Recovery: Deploy previous container image version
3. Configuration Recovery: Restore configuration from version control
4. Full System Recovery: Complete environment restoration

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License Summary

The MIT License is a permissive open source license that allows for:

• Commercial use
• Modification
• Distribution
• Private use

The only requirement is that the license and copyright notice must be included with any substantial portions of the software.

Third-Party Dependencies

This project uses several open source libraries, each with their own licenses:

• Flask and related extensions (BSD License)
• PostgreSQL driver (BSD License)
• Testing frameworks (MIT/BSD Licenses)
• Other dependencies as listed in requirements.txt

All dependencies are compatible with the MIT License and open source distribution.

---

Property-Based Testing

This project includes a comprehensive property-based testing framework using Hypothesis. Property-based tests validate universal properties across the application with automatically generated test data.

Framework Components

• Hypothesis Configuration: Configurable test profiles (dev, default, ci)
• Custom Strategies: Domain-specific data generators for music, users, and sync scenarios
• Property Test Generators: High-level generators for complex test scenarios
• Base Classes: Foundation classes with setup/teardown and assertion helpers

Running Property Tests

# Run all property-based tests
make test-property

# Run with specific Hypothesis profile
export HYPOTHESIS_PROFILE=ci
make test-property

# Run with verbose output
make pytest ARGS="-k property -v"

Property-based tests automatically find minimal failing examples and provide comprehensive coverage of edge cases and boundary conditions.

For detailed information about the property-based testing framework, see tests/property/README.md.