# SamCloud Music Architecture

## Overview
SamCloud Music is a unified, single-container web app that fuses SpotSpot (Spotify search + SpotDL download), Navidrome (music library browsing), and Finamp (web music player) into a seamless, Apple Music-style experience. All features are served from a single Flask+SocketIO backend for real-time updates and a modern, modular frontend.

## Key Components
- **Backend (Flask + SocketIO):**
  - Serves API endpoints for search, download, and progress.
  - Emits real-time events for progress and notifications.
  - Serves static assets and frontend UI.
  - Modular service layer for Spotify, download, and config.
- **Frontend (HTML/JS/CSS):**
  - Apple Music-style UI with tabs: Search, Browse, Downloads, Listen.
  - Real-time updates via SocketIO.
  - Embedded Navidrome and Finamp web clients for seamless experience.
- **Dockerized:**
  - All services and assets run in a single container for easy deployment and reproducibility.

## Directory Structure
- `app/spotspot.py` — Main Flask app
- `app/services/` — Service modules (Spotify, download, config)
- `app/templates/` — Jinja2 HTML templates (UI)
- `app/static/` — Static assets (JS, CSS, icons, manifest, Finamp web client)
- `.github/` — Copilot and project instructions
- `.vscode/` — VS Code tasks

## Integration Points
- **Spotify API:** For search and metadata
- **SpotDL:** For YouTube downloads
- **Navidrome:** For music library browsing (iframe or API)
- **Finamp:** For in-app music playback (web client embedded)

## Real-Time Flow
1. User searches for music (Spotify API)
2. User downloads track (SpotDL), backend emits progress via SocketIO
3. Downloaded music appears in Navidrome and is playable in Finamp tab
4. All notifications and progress are real-time

---

See README.md for setup. All code and docs are modular and reproducible.