# 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.