chore: added documentation

2026-03-09 22:45:24 +01:00
parent dd0d0cfde6
commit ec8d5a6124
11 changed files with 963 additions and 0 deletions
--- a/docs/onboarding.md
+++ b/docs/onboarding.md
@@ -0,0 +1,108 @@
+# Trackpull — Onboarding Guide
+
+## What Is Trackpull?
+
+Trackpull is a self-hosted, multi-user web application for downloading music from Spotify URLs. It supports two download backends that can be used independently or together via a smart fallback system:
+
+- **Monochrome** — proxies audio from Tidal/Qobuz through distributed API instances. Produces high-quality lossless or MP3 files without requiring Spotify credentials.
+- **Votify** — downloads directly from Spotify using cookies-based authentication. Requires a valid `cookies.txt` and optionally a Widevine device certificate.
+- **Unified** — tries Monochrome first, falls back to Votify for any tracks that fail. This is the default and recommended mode.
+
+The app is containerized with Docker and stores all state in a mounted volume. A SQLite database tracks users, jobs, and settings.
+
+---
+
+## Systems at a Glance
+
+| System | Document |
+|--------|----------|
+| Docker & deployment | [docker-deployment.md](docker-deployment.md) |
+| Authentication & roles | [authentication.md](authentication.md) |
+| Database schema & layer | [database.md](database.md) |
+| Job management | [job-management.md](job-management.md) |
+| File management | [file-management.md](file-management.md) |
+| Votify download system | [votify.md](votify.md) |
+| Monochrome download system | [monochrome.md](monochrome.md) |
+| Unified download system | [unified.md](unified.md) |
+| Frontend (UI & PWA) | [frontend.md](frontend.md) |
+
+---
+
+## Getting Started
+
+### 1. Deploy
+
+```bash
+cp .env.example .env
+# Set ADMIN_USERNAME, ADMIN_PASSWORD, SECRET_KEY, PORT
+docker compose up -d --build
+```
+
+See [docker-deployment.md](docker-deployment.md) for all environment variables.
+
+### 2. Upload credentials (admin)
+
+Log in with your admin account, go to **Settings**, and upload:
+- `cookies.txt` — Netscape-format Spotify cookies (required for Votify).
+- `device.wvd` — Widevine device certificate (required for some Spotify content).
+
+Monochrome does not require any credentials.
+
+### 3. Download music
+
+Paste one or more Spotify track, album, or playlist URLs into the Unified tab and click Download. The job will appear in the Jobs tab with live output.
+
+---
+
+## Architecture Overview
+
+```
+Browser (index.html)
+    │
+    ├── POST /api/unified/download
+    ├── POST /api/download          (Votify)
+    └── POST /api/monochrome/download
+            │
+            ▼
+        app.py (Flask / Gunicorn)
+            │
+            ├── db.py (SQLite via thread-local connections)
+            │
+            ├── Votify path:
+            │     subprocess: votify CLI → ffmpeg (optional MP3 conversion)
+            │     output dir: /downloads/{user_id}/
+            │
+            └── Monochrome path:
+                  monochrome/api.py
+                    ├── monochrome/__init__.py  (instance discovery)
+                    ├── monochrome/spotify_to_ids.py  (Spotify scraping + Tidal search)
+                    └── monochrome/download.py  (stream, metadata embed, MP3 conversion)
+                  output dir: /downloads/{user_id}/
+```
+
+---
+
+## Key Concepts
+
+**Jobs** are asynchronous. After submitting a download, the job runs in a background thread. Poll the Jobs tab for progress. Jobs survive page refreshes but in-memory state (active downloads) is lost on container restart.
+
+**Users** are isolated. Each user's files live in `/downloads/{user_id}/` and are not visible to other users. Admins can browse all users' files.
+
+**Settings** are global (per-application, not per-user). Admins configure fallback quality, job expiry, and upload credentials.
+
+**Monochrome instances** are third-party servers. If downloads fail, it may be because instances are down. The app automatically tries multiple instances and falls back to Votify.
+
+---
+
+## Maintaining This Documentation
+
+> **Keep these docs up to date.** When you add, change, or remove a feature, update the relevant document in `docs/`. If you add a new system, create a new document and add it to the table above in this onboarding guide.
+
+Guidelines:
+- One document per system.
+- Document the *why* and *how*, not just the *what*.
+- Update API endpoint tables when routes change.
+- Update option tables when new download parameters are added.
+- If a gotcha is discovered (e.g., a third-party API quirk), add it to the relevant doc.
+
+Stale documentation is worse than no documentation — readers will trust it and waste time on outdated information.