From 21b6219e61b34f2dcd6f46a648da68727751ba0a Mon Sep 17 00:00:00 2001
From: xpltd_admin <admin@xpltd.co>
Date: Fri, 3 Apr 2026 23:04:45 -0600
Subject: [PATCH] Create Data-Model wiki page for media-rip

---
 Data-Model.-.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 Data-Model.-.md

diff --git a/Data-Model.-.md b/Data-Model.-.md
new file mode 100644
index 0000000..57f814d
--- /dev/null
+++ b/Data-Model.-.md
@@ -0,0 +1,95 @@
+# Data Model
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/media-rip` |
+| **Page** | `Data-Model` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Overview
+
+media-rip uses SQLite with async access via aiosqlite. The database automatically detects network filesystems and switches between WAL and DELETE journal mode. Schema is defined in `backend/app/core/database.py`.
+
+## Tables
+
+### `sessions`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | TEXT PK | UUID4 session identifier |
+| `created_at` | TEXT | ISO timestamp |
+| `last_seen` | TEXT | Updated on every request |
+
+**Index:** `idx_sessions_last_seen` on `last_seen`
+
+### `jobs`
+
+| Column | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | TEXT PK | — | UUID4 job identifier |
+| `session_id` | TEXT | — | FK → sessions |
+| `url` | TEXT | — | Source URL |
+| `status` | TEXT | `queued` | `queued`, `extracting`, `downloading`, `completed`, `failed`, `cancelled` |
+| `format_id` | TEXT | NULL | Selected format identifier |
+| `quality` | TEXT | NULL | Quality label |
+| `output_template` | TEXT | NULL | Resolved output path |
+| `filename` | TEXT | NULL | Final filename (set after download) |
+| `filesize` | INTEGER | NULL | File size in bytes |
+| `progress_percent` | REAL | 0 | Download progress (0-100) |
+| `speed` | TEXT | NULL | Current download speed string |
+| `eta` | TEXT | NULL | Estimated time remaining |
+| `error_message` | TEXT | NULL | Error details (if failed) |
+| `created_at` | TEXT | — | Job creation time |
+| `started_at` | TEXT | NULL | Download start time |
+| `completed_at` | TEXT | NULL | Completion/failure time |
+
+**Indexes:** `idx_jobs_session_status` on `(session_id, status)`, `idx_jobs_completed` on `completed_at`
+
+### `config`
+
+Admin-writable key-value settings store.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `key` | TEXT PK | Setting key |
+| `value` | TEXT | Setting value |
+| `updated_at` | TEXT | Last modification time |
+
+### `unsupported_urls`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | INTEGER PK | Autoincrement |
+| `url` | TEXT | The unsupported URL |
+| `session_id` | TEXT | Which session tried it |
+| `error` | TEXT | Error message |
+| `created_at` | TEXT | Timestamp |
+
+### `error_log`
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | INTEGER PK | Autoincrement |
+| `url` | TEXT | Source URL |
+| `domain` | TEXT | Extracted domain |
+| `error` | TEXT | Error message |
+| `format_id` | TEXT | Format that was attempted |
+| `media_type` | TEXT | video/audio |
+| `session_id` | TEXT | Session ID |
+| `created_at` | TEXT | Timestamp |
+
+## SQLite Pragmas
+
+Set at initialization:
+
+```sql
+PRAGMA busy_timeout = 5000;    -- Wait 5s on lock contention
+PRAGMA journal_mode = WAL;     -- Or DELETE on network filesystems
+PRAGMA synchronous = NORMAL;   -- Balanced durability/speed
+```
+
+## Network Filesystem Detection
+
+The database module reads `/proc/mounts` and checks the filesystem type. If it detects CIFS, NFS, SMB, 9p, or sshfs, it switches to DELETE journal mode (WAL requires POSIX shared memory which isn't available on network mounts).
\ No newline at end of file