# Project Context & System Architecture Blueprint
**Repository:** `qbittorrent-performer-sorter`  
**Gitea Remote:** `http://truenas.local:30008/david/qbittorrent-performer-sorter.git`  
**Working Workspace:** `/home/david` & `/home/david/github/qbittorrent-performer-sorter`  
**Primary App Port:** `8000` (`http://localhost:8000`)  
**Stash GraphQL Endpoint:** `http://servervm.local:9999/graphql` (Internal `/data` maps to `/mnt/isolation/videos`)

---

## 1. Executive Summary & Purpose
This application is a unified web-based media organizer, AI intelligence engine, video stream previewer, and Stash media server control center. It bridges qBittorrent, local/SMB filesystem storage (TrueNAS), and Stash GraphQL API to provide automated performer sorting, duplicate scene analysis, Stash database tag/performer normalization, and transcode optimization.

---

## 2. Key Architecture & File Structure

```
qbittorrent-performer-sorter/
├── server.py                        # Python 3 standard-library HTTP & API server
├── qbittorrent_performer_sorter.html # Single-Page Application (HTML5, Vanilla JS, CSS3)
├── mount_isolation.sh               # Auto-mount helper script for TrueNAS SMB shares
├── performer_sorter.db              # SQLite persistent caching & audit log database
├── README.md                        # Quick start and feature overview
└── CONTEXT.md                       # LLM Session Save Point & Deep Architecture Spec
```

### Zero-Dependency Python Architecture
`server.py` relies exclusively on Python standard library modules (`http.server`, `socketserver`, `sqlite3`, `urllib.request`, `urllib.parse`, `json`, `re`, `os`, `shutil`, `threading`, `time`, `mimetypes`). No external pip dependencies are required.

---

## 3. UI Tab Layout & Feature Modules

1. **Tab 1: 📡 qBittorrent Sorter**
   - Direct integration with qBittorrent WebUI (`/qb-proxy/api/v2/...`).
   - Analyzes torrent files, multi-file torrent hierarchies, and moves seeding torrents using `torrents/setLocation` without breaking active seeding.
   - AI performer parsing with multi-candidate pill selectors.

2. **Tab 2: 📂 SMB Video Sorter**
   - Direct filesystem scanner for TrueNAS video shares (`/mnt/isolation/videos/videodownloader` & `/mnt/isolation/videos/unsorted`).
   - Categorizes, cleans filenames, and relocates files to performer destination folders (`/mnt/isolation/videos/<performer>/`).
   - Automatic SMB auto-mount detection and auto-recovery.

3. **Tab 3: 🖼️ Stash Image Review**
   - Performer avatar manager, gallery browser, and quick-tagging studio.
   - Hover cards and image zoom preview modals.

4. **Tab 4: 📜 Relocation History & Analytics**
   - Persistent SQLite audit log tracking moves, size changes, timestamps, and performer classifications.
   - One-click rollback and undo support.

5. **Tab 5: ⚡ Stash Tasks & Tool Control**
   - **Section A: 👥 Performer Merge & Deduplication Studio**: Scans fuzzy and punctuation duplicate performer profiles (`cory.chase` vs `Cory Chase`) and merges them via Stash GraphQL `performerMerge`. Includes 1-Click Batch Merge All.
   - **Section B: 📡 Missing Metadata Radar**: Scans scenes lacking studios, performers, or tags with quick autotag triggers.
   - **Section C: 🏷️ Tag Normalizer & Deduplication**: Identifies tag casing/alias duplicates and merges them via `tagsMerge`. Includes 1-Click Batch Merge All.
   - **Section D: 🔀 Stash Transcode Correlator & Storage Saver**:
     - Scans generated transcodes in `/mnt/isolation/stashapp/generated/transcodes/`.
     - Matches OSHash filenames against Stash library database paths.
     - Side-by-side **🎬 Orig** vs **⚡ Transcode** in-browser video streaming comparisons.
     - True physical storage savings metrics ($\text{Freed} = \text{Original File Size}$).
     - Atomic replacement: Staging copy $\to$ size validation $\to$ `os.replace` $\to$ cache deletion $\to$ background directory metadata rescan.
     - Embedded Real-Time Live Execution Terminal Console (`#transcode-terminal-wrapper`) with auto-scroll and status monitoring.
   - **Section E: 🔍 Duplicate Scene Comparator & Plugin Hub**:
     - Visual side-by-side comparison of duplicate scenes with resolution/codec/bitrate badges and stream previews.
     - Direct triggers for Stash plugins (`DupFileManager`, `phashDuplicateTagger`).
   - **Section F: ⚡ Task Manager**:
     - Live polling of active/queued background Stash jobs (`findJobStatus`).
     - Library Scan, Identify/Auto-tag, Clean, and Generate task starters with instant job cancellation (`stopJob` / `stopAllJobs`).

---

## 4. Path Mapping & Filesystem Translation Rules

| Context | Stash Container Path | Local TrueNAS Mount Path |
| :--- | :--- | :--- |
| **Main Videos Share** | `/data/...` | `/mnt/isolation/videos/...` |
| **Generated Transcodes** | `/generated/transcodes/...` or `/media/stashapp/generated/...` | `/mnt/isolation/stashapp/generated/transcodes/...` |
| **Download Incomplete** | `/downloads/...` | `/mnt/isolation/incomplete/...` or `/mnt/isolation/videos/unsorted/...` |

### Streaming Path Translation (`resolve_stream_video_path` in `server.py`)
- Accepts any Stash GraphQL path (e.g. `/data/performer/scene.mp4`) or local path and resolves to the actual local mount path on disk before serving HTTP 206 partial content chunks.

---

## 5. GraphQL Mutation Conventions (Stash v0.31+ Compliance)
Stash v0.31+ strict GraphQL schema rejects variable declarations in mutations with `HTTP 422: GRAPHQL_PARSE_FAILED`.  
**Standard**: All mutations must be constructed using `build_stash_mutation(mutation_name, input_obj, fields)`:
- Keys are unquoted in GraphQL literals.
- String filters like `performers`, `studios`, `tags` in `metadataAutoTag` require string array filters (e.g. `["*"]`).

---

## 6. Database Schema (`performer_sorter.db`)

### `ai_cache` Table
- `item_key` (TEXT PRIMARY KEY) - Torrent hash or SMB file path.
- `item_name` (TEXT)
- `performer_result` (TEXT) - Primary chosen performer slug.
- `candidates_json` (TEXT) - JSON list of multi-performer candidate names.
- `source_type` (TEXT) - `'qb'` or `'smb'`.
- `move_status` (TEXT) - `'unmoved'` or `'moved'`.
- `target_path` (TEXT)
- `updated_at` (TIMESTAMP)

### `relocation_history` Table
- `id` (INTEGER PRIMARY KEY AUTOINCREMENT)
- `source_type` (TEXT) - `'qb'`, `'smb'`, or `'stash_transcode'`.
- `item_key` (TEXT)
- `item_name` (TEXT)
- `source_path` (TEXT)
- `target_path` (TEXT)
- `performer` (TEXT)
- `file_size` (INTEGER)
- `timestamp` (TIMESTAMP)

---

## 7. Operational Guidelines for Future AI Sessions
1. **Syncing Changes**: Always ensure modifications to `server.py` and `qbittorrent_performer_sorter.html` in `/home/david` are mirrored to `/home/david/github/qbittorrent-performer-sorter`, committed with semantic messages, and pushed to `http://truenas.local:30008/david/qbittorrent-performer-sorter.git`.
2. **Standard Library Integrity**: Keep `server.py` free of external pip packages.
3. **HTTP Range 206 Streaming**: Maintain HTTP Range handling in `handle_stream_video` for smooth seeking in the web player.
4. **Safety Verification in File Ops**: Always maintain atomic staging (`.tmp` $\to$ verify size $\to$ `os.replace`) when modifying or replacing media files.