Initial commit, prod ready

README.md

@@ -0,0 +1,79 @@
+# Music Orchestrator
+
+Search → preview on YouTube → download as tagged MP3, organized for PlexAmp.
+
+## Production deploy (Ubuntu server, local network)
+
+Copy the project to your Ubuntu machine, then:
+
+```bash
+bash deploy.sh
+```
+
+The script installs all dependencies, builds the frontend, configures nginx and
+a systemd service, and starts everything. Re-run it at any time to apply updates.
+
+**Access:** `http://<server-ip>` from any device on your local network.
+
+### After deploy
+
+```bash
+# Stream live logs
+journalctl -u music-orchestrator@<your-user> -f
+
+# Restart the API
+sudo systemctl restart music-orchestrator@<your-user>
+
+# Change music library path
+nano /opt/music-orchestrator/backend/.env
+sudo systemctl restart music-orchestrator@<your-user>
+```
+
+---
+
+## Local development
+
+**Requirements:** Python 3.11+, Node 18+, ffmpeg
+
+```bash
+# Backend
+cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env   # set MUSIC_DIR
+uvicorn main:app --reload --port 8000
+```
+
+```bash
+# Frontend (separate terminal)
+cd frontend
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173` — Vite proxies `/api` to the backend automatically.
+
+---
+
+## Music library structure
+
+Downloads are saved as:
+
+```
+Music/
+└── Queen/
+    └── A Night at the Opera/
+        └── 01 - Bohemian Rhapsody.mp3
+```
+
+Set `MUSIC_DIR` in `backend/.env` to your Plex library folder.
+
+## Architecture notes
+
+- **1 uvicorn worker only** — download job state is held in memory. Multiple
+  workers would each have their own job store, breaking status polling.
+- nginx serves the React build as static files and reverse-proxies `/api/*`
+  to the FastAPI backend on `127.0.0.1:8000`.
+- Metadata (title, artist, album, artwork) comes from the iTunes Search API.
+  The YouTube video is only used for audio.