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/frontend.md
+++ b/docs/frontend.md
@@ -0,0 +1,103 @@
+# Frontend
+
+## Overview
+
+The frontend is a vanilla JavaScript single-page-style app served by Flask from `templates/index.html`. It uses no frontend framework. The UI has a dark theme with Spotify green (#1db954) accents and is fully responsive.
+
+---
+
+## Pages / Tabs
+
+### Unified Download (default)
+- Textarea for one or more Spotify URLs.
+- Single submit button that calls `POST /api/unified/download`.
+- Buttons to switch to the Votify or Monochrome-specific tabs.
+
+### Votify Download
+- Multi-URL textarea.
+- Audio quality selector (AAC / Vorbis options).
+- Collapsible "Advanced" section with format, cover size, video, and other toggles.
+- Calls `POST /api/download`.
+
+### Monochrome Download
+- Single URL input (track, album, or playlist).
+- Quality selector (Tidal quality levels).
+- Calls `POST /api/monochrome/download`.
+
+### Jobs
+- Lists all jobs for the current user (live + historical).
+- Status badges: `queued`, `running`, `completed`, `failed`, `cancelled`.
+- Collapsible output log per job.
+- Cancel button (running jobs), delete button (terminal jobs).
+- Auto-refreshes every 3 seconds while any job is running.
+
+### Files
+- Browser-style file tree rooted at the user's download directory.
+- Breadcrumb navigation.
+- Download individual files or entire folders (as ZIP).
+- Delete files or folders with confirmation.
+
+### Settings
+- **All users**: Change own account password.
+- **Admins only**:
+  - Upload `cookies.txt` (Spotify authentication).
+  - Upload `device.wvd` (Widevine certificate).
+  - Set fallback quality (used by Unified system).
+  - Set job expiry (days before old jobs are auto-deleted).
+
+### Admin: Users (admin only)
+- List all users with creation date and last login.
+- Create new users (username, password, role).
+- View any user's jobs or files.
+- Delete users (with confirmation prompt).
+- Reset any user's password.
+
+---
+
+## Responsive Design
+
+- **Desktop**: Horizontal tab bar at the top.
+- **Mobile**: Bottom navigation bar.
+- Minimum tap target size: 36×36px.
+- Font sizes scale down on smaller screens.
+
+---
+
+## Progressive Web App (PWA)
+
+The app can be installed as a standalone PWA.
+
+### Manifest
+`/static/manifest.json` defines the app name, theme color, icons (192×192 and 512×512), and `standalone` display mode.
+
+### Service Worker
+`/static/sw.js` provides:
+
+| Resource type | Strategy |
+|---------------|----------|
+| API calls (`/api/*`) | Network only (no caching) |
+| Page navigation | Network first, fallback to offline page |
+| Static assets | Cache first, network fallback |
+
+The service worker caches the app shell (HTML, CSS, JS, icons) on install and clears old caches on activation. If the network is unavailable during navigation, `/static/offline.html` is served.
+
+---
+
+## Templates
+
+| File | Purpose |
+|------|---------|
+| [templates/index.html](../templates/index.html) | Main app (all tabs, JS logic, CSS) |
+| [templates/login.html](../templates/login.html) | Login form |
+
+---
+
+## Key Files
+
+| File | Relevance |
+|------|-----------|
+| [templates/index.html](../templates/index.html) | Entire UI: HTML, CSS, JavaScript |
+| [templates/login.html](../templates/login.html) | Login page |
+| [static/manifest.json](../static/manifest.json) | PWA manifest |
+| [static/sw.js](../static/sw.js) | Service worker |
+| [static/icons/](../static/icons/) | App icons for PWA |